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

Долгое время в NGCMS использовалась собственная шаблонная система. С одной стороны она давала некоторую гибкость при разработке шаблонов, с другой - лёгкость в реализации. Основным же недостатком являлись крайне скудные возможности использования условных блоков, что приводило к созданию массы ненужных файлов-шаблонов и не позволяло проявить должную гибкость при создании шаблонов, значительно отличающихся от "базового" шаблона.

Все эти недостатки привели к необходимости найти альтертативу. И она была найдена - компилирующий шаблонизатор TWIG.

TWIG объединяет в себе высокую производительность (каждый шаблон автоматически компилируется в чистый PHP код) и огромную гибкость. При этом ядро TWIG'а предусматривает широкие возможности по расширению базового функционала и даже позволяет обеспечить (в определённых рамках) обратную совместимость с текущим (старым) шаблонизатором.

Документацию по TWIG'у можно почитать на сайте разработчика, на этой же странице будет рассказано о глобальных переменных/функциях NGCMS, доступных в любых TWIG шаблонах.

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

• [T] на базе TWIG - в этих шаблонах синтаксис TWIG можно использовать сразу

• Обычные шаблоны - в них TWIG функции доступны внутри блока [TWIG] .. [/TWIG]

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

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

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

• pluginIsActive($pluginName) - сообщает включен ли плагин $pluginName (1 - активен, 0 - нет), обычно используется для отображения элементов плагина только в том случае, если данный плагин включен (активен).
  Пример, выводящий строку '* плагин tags активен *' в случае, если плагин tags включен в админ-панели:
  

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

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

  	{% include localPath(0) ~ "conf.navi.tpl" %}
  	

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

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

• isCategory($list) - работа с текущей категорией посетителя (если он находится в категории)
  Функция isCategory поддерживает 2 режима работы:
  • Возвращает true в случае, если пользователь находится в одной из указанных в $list категориях.
    Список разделяется запятыми, в качестве элемента можно использовать как альт. имя так и ID категории.
    

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

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

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

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

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

• getCategoryTree($filter) - выводит массив с деревом категорий в формате, описанном в шаблоне news.categories.tpl.
  где:
  $filter - фильтр выдаваемой информации:
  
  • не определён - если переменная не определена (не передаётся в функцию), то выводится полное дерево категорий
  • ID - вывести категорию и всех её детей
  • :ID - вывести всех детей заданной категории

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

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

• lang - глобальная переменная с языковыми константами, аналогична конструкции {l_Variable} в старом шаблонизаторе.
  Пример:

   	{{ lang['Variable'] }}
  	

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