# Шаблонизатор TWIG

Долгое время в NGCMS использовалась собственная шаблонная система. С одной стороны она давала некоторую гибкость при разработке шаблонов, с другой - лёгкость в реализации. Основным же недостатком являлись крайне скудные возможности использования условных блоков, что приводило к созданию массы ненужных файлов-шаблонов и не позволяло проявить должную гибкость при создании шаблонов, значительно отличающихся от "базового" шаблона.
Все эти недостатки привели к необходимости найти альтертативу. И она была найдена - <a href="http://twig.sensiolabs.org/doc/templates.html" target="_blank">компилирующий шаблонизатор TWIG</a>.
TWIG объединяет в себе высокую производительность (каждый шаблон автоматически компилируется в чистый PHP код) и огромную гибкость. При этом ядро TWIG'а предусматривает широкие возможности по расширению базового функционала и даже позволяет обеспечить (в определённых рамках) обратную совместимость с текущим (старым) шаблонизатором.
Документацию по TWIG 'у можно почитать на сайте разработчика, на этой же странице будет рассказано о глобальных переменных/функциях NGCMS, доступных в любых TWIG шаблонах.

## Использование шаблонизатора TWIG в шаблонах

Все шаблоны в актуальных версиях NGCMS обрабатываются напрямую через <span class="twig">TWIG</span>, синтаксис доступен сразу без дополнительных маркеров.
Исторически существовали «обычные» шаблоны с включениями кода внутри конструкций `..`. Эта конструкция больше не поддерживается: просто удалите маркеры и оставьте чистый Twig‑код.
Пример миграции:

```
Старый вариант:
... html ...
{% if isLogged %}Привет, {{ global.user.name }}{% endif %}
... html ...
Новый вариант:
... html ...
{% if isLogged %}Привет, {{ global.user.name }}{% endif %}
... html ...
```

Проверка: если в шаблоне остались маркеры `или`, их следует удалить — иначе они будут интерпретированы как обычный текст.

## Глобальные функции

<b>template_from_string(<span class="blue">$variable</span>)</b> - встроенная <span class="twig">TWIG</span> функция, позволяет исполнять <span class="twig">TWIG</span> шаблон из переменной.<br />
Пример использования, позволяет выполнить <span class="twig">TWIG</span> шаблон из переменной category.info (описание категории для режима работы "вывод новостей из категории") шаблона news.table.tpl:<br />

<pre >
{% if (handler == 'by.category') %}
{% include template_from_string(category.info) %}
{% endif %}
</pre>

<b>pluginIsActive(<span class="blue">$pluginName</span>)</b> - сообщает включен ли плагин <b>$pluginName</b> (1 - активен, 0 - нет), обычно используется для отображения элементов плагина только в том случае, если данный плагин включен (активен).<br />
Пример, выводящий строку '_ плагин tags активен _' в случае, если плагин tags включен в админ-панели:<br />

<pre >
{% if pluginIsActive('tags') %}
* плагин tags активен *
{% endif %}
</pre>

<b>localPath(0)</b> - возвращает путь нахождения текущего шаблона, содержимое блока отображается в случае, если для категории определена иконка. Используется в случае, когда вы внутри шаблона хотите подключить другой шаблон из того же каталога.<br />
<i>Параметр (0) - обязателен.</i><br />
Пример подключения шаблона "conf.navi.tpl" из текущего каталога:<br />

<pre >
{% include localPath(0) ~ "conf.navi.tpl" %}
</pre>

<b>getLang(0)</b> - возвращает текущий язык.<br />
<i>Параметр (0) - обязателен.</i><br />
<b>isLang(<span class="blue">$lang</span>)</b> - возвращает <b>true</b> если текущий язык - $lang<br />
<i>Параметр ($lang) - обязателен.</i><br />
<b>isHandler(<span class="blue">$rule</span>)</b> - возвращает <b>true</b> в случае, если текущее местоположение пользователя соотвествует указанным правилам в <b>$rule</b><br />
Формат переменной <b>$rule</b>: ENTRY1[|ENTRY2[|ENTRY3[...]]]<br />
Формат записи ENTRYx: PLUGIN[:HANDLER]<br/> где:<br />
<b>PLUGIN</b> - ID плагина<br/> <b>HANDLER</b> - ID обработчика (если указан)<br />

<pre >
{% if isHandler('tags|news:main') %}
* Пользователь находится на главной странице или на странице плагина tags *
{% endif %}
</pre>

<b>isCategory(<span class="blue">$list</span>)</b> - работа с текущей категорией посетителя (если он находится в категории)<br />
Функция <b>isCategory</b> поддерживает 2 режима работы:<br />
Возвращает <b>true</b> в случае, если пользователь находится в одной из указанных в <b>$list</b> категориях.<br />
Список разделяется запятыми, в качестве элемента можно использовать как альт. имя так и ID категории.<br />

<pre >
{% if isCategory('news,plugins,15') %}
* Пользователь находится в одной из категорий - с альт. именами 'news', 'plugin', либо с id 15 *
{% endif %}
</pre>

Возвращает информацию о текущей категории (если пользователь сейчас в какой-либо категории).<br />
Допустимые значения для параметра <b>$list</b>:<br />
<b>:id</b> - возвращает ID категории<br />
<b>:alt</b> - возвращает альт. имя категории<br />
<b>:name</b> - возвращает имя категории<br />
<b>:icon</b> - возвращает <b>true</b> если у категории есть прикрепленная иконка (изображение)<br />
<b>:icon.url</b> - возвращает URL прикрепленной иконки<br />
<b>:icon.width</b> - возвращает ширину прикрепленной иконки<br />
<b>:icon.height</b> - возвращает высоту прикрепленной иконки<br />
<b>:icon.preview</b> - возвращает <b>true</b> если у прикрепленной иконки есть уменьшенное изображение (превьюшка)<br />
<b>:icon.preview.url</b> - возвращает URL для превью прикрепленной иконки<br />
<b>:icon.preview.width</b> - возвращает ширину для превью прикрепленной иконки<br />
<b>:icon.preview.height</b> - возвращает высоту для превью прикрепленной иконки<br />
<b>isNews(<span class="blue">$rule</span>)</b> - работа с текущей новостью посетителя (если он находится в новости).<br />
Формат переменной <b>$rule</b>: ENTRY1[|ENTRY2[|ENTRY3[...]]]<br />
Формат записи ENTRYx: TYPE[:LIST] <i>или</i>LIST (в этом случае TYPE == news)<br />
где:<br />
<b>TYPE</b> - тип записи, доступные типы:<br />
<b>news</b> - новость (ID или альт. имя)<br />
<b>cat</b> - категория (ID или альт. имя)<br />
<b>mastercat</b> - главная категория (ID или альт. имя)<br />
<b>LIST</b> - список значений через запятую<br />

<pre >
{% if isNews('my_news,very_happy,15|mastercat:12,games') %}
* Пользователь находится в новости с: альт. именем "my_news" или "very_happy" или с ID 15 или главная категория новости имеет ID 12 или главная категория новости имеет альт. имя "games" *
{% endif %}
</pre>

<b>engineMSG(<span class="blue">$type</span>, <span class="blue">$text</span>, <span class="blue">$info</span>)</b> - выводит сообщение CMS в стиле текущего шаблона.<br />
где:<br />
<b>$type</b> - тип сообщения (common, error, info)<br />
<b>$text</b> - текст сообщения<br />
<b>$info</b> - дополнительная информация (необязательный параметр)<br />
<b>isSet(<span class="blue">$variable</span>)</b> - возвращает <b>true</b> если переменная с именем $variable определена.<br />
<b>callPlugin(<span class="blue">$function, $variable</span>)</b> - вызывает функцию <b>$function</b> и передаёт ей параметр <b>$variable</b>.<br />
<b>debugContext(<span class="blue">0</span>)</b> - выводит на экран отладочную информацию по всем доступным в данном месте переменным с их значениями.<br /><i>Использовать только для отладки !!</i><br />
<b>debugValue(<span class="blue">$variable</span>)</b> - выводит на экран отладочную информацию по содержимому указанной переменной.<br /><i>Использовать только для отладки !!</i>

<pre >
&lt;!-- Выводим все параметры глобальной переменной handler --&gt;
{{ debugValue(handler) }}
</pre>

<b>getCategoryTree(<span class="blue">$filter</span>)</b> - выводит массив с деревом категорий в формате, описанном в шаблоне news.categories.tpl.<br />
где:<br />
<b>$filter</b> - фильтр выдаваемой информации:<br />
<b>не определён</b> - если переменная не определена (не передаётся в функцию), то выводится полное дерево категорий<br />
<b><span class="blue">ID</span></b> - вывести категорию и всех её детей<br />
<b>:<span class="blue">ID</span></b> - вывести всех детей заданной категории

<pre >
&lt;!-- Выводим всех детей категории с ID=6 --&gt;
{% for entry in getCategoryTree(':6') %}
[{{entry.id}}]({{ entry.level }}) {{ entry.cat }}
{% endfor %}
</pre>

## Глобальные переменные

<b>lang</b> - глобальная переменная с языковыми константами, аналогична конструкции <b>{l\_<span class="blue">Variable</span>}</b> в старом шаблонизаторе.<br />
Пример:

<pre >
{{ lang['Variable'] }}
</pre>

<b>{{ skins_url }}</b> - аналог переменной <b>{skins_url}</b><br />
<b>{{ admin_url }}</b> - аналог переменной <b>{admin_url}</b><br />
<b>{{ tpl_url }}</b> - аналог переменной <b>{tpl_url}</b><br />
<b>handler</b> - глобальная переменная <b>$CurrentHandler</b> (массив)<br />
<b>global</b> - специальный массив с различными полезными <u>глобальными</u> параметрами:<br />
<b>user</b> - структура с строчкой из таблицы ng_users залогиненного пользователя (<i>пример:</i> <b>global.user.name</b> - логин пользователя)<br />
<b>flags</b> - массив с флагами:<br />
<b>isLogged</b> - принимает значение (1) если текущий посетитель - залогиенный пользователь
