Синтаксис CoTemplate

Краткое руководство по выражениям и синтаксису поддерживаемому шаблонизатором CoTemplate

Этот документ описывает возможности, структуру и синтаксис применяемый в шаблонизаторе CoTemplate версии 2.7 и выше.

#1. Блоки

Блоки являются основой структуры шаблонов. Шаблон содержит блоки, блоки могут содержать другие блоки, выражения, условия, теги и обычный текст. Рассмотрим пример блока:

<!-- BEGIN: BLOCK_NAME -->
Содержимое блока в виде HTML кода
<!-- END: BLOCK_NAME -->

Где `BLOCK_NAME` — это имя блока (допустимы латинские буквы и символ подчеркивания). Большинство блоков состоят из единственного корневого блока `MAIN`. Шаблон допускает применение нескольких корневых блоков одновременно. Текст (как и HTML код) находящийся вне корневых блоков игнорируется.

Названия блоков задаются в верхнем регистре, это основное правило.

Блок идентифицируется и выводится контроллером. Блоки могут быть идентифицированы по их полному имени: 'PARENT_BLOCK.BLOCK_NAME'. Блоки самые быстрые структуры в шаблонах. Эти три основные момента делают их основой всех остальных конструкций шаблонизатора.

#2. Теги

Переменные в CoTemplate именуются Тегами шаблона (TPL Tags) или просто Тегами. Используются 2 вида тегов: глобальные и локальные.

Локальные теги назначаются (определяются) через вызов метода XTemplate::assign() в управляющем PHP коде. Их синтаксис таков:

{TAG_NAME}

Такая запись будет заменена на значение локальной переменной шаблона (определенной внутри объекта XTemplate ) с именем 'TAG_NAME'. Указание имен в верхнем регистре используется, как основное правило, позволяющее выделить Теги шаблона среди прочего кода.

Глобальные теги это по сути ссылка на переменную PHP в глобальной области видимости. Такие теги используют для этого ключевое слово «PHP» в своем имени:

{PHP.my_var}

В большинстве случаев рекомендуется использование локальных тегов. Глобальные применяются для вывода переменных, которые должны использоваться в разных блоках или шаблонах или как выход из ситуации когда специальный локальный тег не определен..

#2.1. Массивы и объекты

Теги могут быть использованы для доступа к элементам массива или (публичным) свойствам объекта. Для указания ключей массива или имен свойств используется запись через точку:

{ARRAY_TAG_NAME.array_key_name}
{OBJECT_TAG_NAME.object_property_name}
{PHP.global_var_name.key_name}

Массивы/объекты могут быть вложенными. Доступ к вложенным элементам осуществляется аналогично:

{TAG_NAME.level1_key.level2_key}

Ограничения на вложенность нет, но надо иметь в виду, что чем больше вложенность, тем медленней работает такой тег.

#2.2. Вызов функций

Вызов функций позволяет перед выводом значения тега обработать его с помощью заданной функции. Для этого используется вертикальная черта (знак «пайп») для отделения имени тега и имени функции:

{TAG_NAME|function_name}

Результатом будет возвращенный функцией результат по обработке значения тега с именем «TAG_NAME». В качестве имени функции может быть использовано имя любой PHP функции, которая принимает один строковый параметр и возвращает строковое значение (можно использовать как встроенные функции, так и определенные пользователем).

Если функция подразумевает более одного аргумента, они  могут быть заданы в круглых скобках. Синтаксис аналогичен обычному вызову PHP функции. В качестве аргументов могут быть указаны скалярные значения (целые и дробные числа, строки, true, false или null), другие теги (в т.ч теги, содержащие вызов других функций) и ключевое слово `$this`, которое будет заменено на значение тега или предыдущего вызова функции:

{MY_TAG|substr($this, 3, 'foo')}
{MY_TAG|someFunc(30.5, $this 'bar', {ANOTHER_TAG}, {PHP.someVar}, null, true)}

Возможен вызов цепочкой, при этом результат вызова первой функции будет передан далее в следующую. Пример:

{MY_STRING|str_replace('foo', 'bar', $this)|htmlspecialchars}

Вызов функций и использование массивов/объектов можно совмещать:

{MY_TAG.item1|doSomething|mb_strtoupper}

Глобальные теги также могут быть обработаны через вызов функции. Причем таким образом может быть вызвана функция без передачи содержимого какого-либо тега вообще:

{PHP|myFunctionCall('some data', 10, {SOME_TAG}, false)}

Используйте механизм вызова функций с умом, чтобы не превратить код вашего шаблона в кашу.

#3. Оператор FILE

Оператор FILE используется для включения дополнительных файлов шаблоны в текущий. Синтаксис таков:

{FILE "path/to/file.tpl"}

Путь указывается относительно корня вашего сайта. Вы можете использовать теги шаблона при задании пути к файлу:

{FILE "{PHP.cfg.plugins_dir}/{PHP.theme}/something.tpl"}

Таким образом происходит фиксированная вставка: содержимое указанного файла целиком и без изменений вставляется на место оператора перед тем, как произойдет дальнейшая обработка шаблона.

#4. Оператор IF (условные блоки)

Оператор IF используется для вывода отдельных частей шаблона исходя из логического условия проверяемого на момент запуска. Оператор IF так же называется условным блоком или логическим блоком. Простейший синтаксис условного блока:

<!-- IF expression -->
  часть HTML кода
<!-- ENDIF -->

Содержимое блока будет отображено, если выражение (expression) истинно (равняется TRUE). Синтаксис условного выражения аналогичен таковому в PHP может содержать Теги шаблона, константы, операторы и скобки. Полный перечень приведен здесь.

Также поддерживается конструкция IF/ELSE :

<!-- IF {FOO} > 10 AND ({PHP.bar} OR {BAZ} ~= 'boo') -->
  This is rendered if the condition is TRUE.
<!-- ELSE -->
  This is rendered if the condition is FALSE.
<!-- ENDIF -->

Условные блоки могут содержать внутри себя другие блоки, условные блоки и циклы, теги, операторы FILE и обычный HTML код.

#5. Оператор FOR (циклы)

Оператор FOR используется для обработки данных, которые сами по себе такого механизма не имеют. Простейший пример:

<!-- FOR {VALUE} IN {MY_ARRAY} -->
Используем {VALUE}
<!-- ENDFOR -->

или

<!-- FOR {KEY}, {VALUE} IN {MY_ARRAY} -->
Используем {KEY} и {VALUE}
<!-- ENDFOR -->

Здесь 'MY_ARRAY' — это имя тега, данные которого мы хотим обработать. 'KEY' и 'VALUE' имена тегов, используемых для доступа к имени элемента и значению; {VALUE} представляет собой значение элемента, а {KEY} содержит строковое или числовое значение ключа массива.

Использование совместно с вызовом функций предоставляет большие возможности. Пример одного из вариантов использования:

<ul>
<!-- FOR {KEY}, {VALUE} IN {MY_ARRAY}  -->
  <li><strong>{VALUE.title}: </strong> <input name="{KEY}" type="text" value="{VALUE.text|htmlspecialchars}" /></li>
<!-- ENDFOR -->
</ul>

Обычный цикл по диапазну:

<!-- FOR {INDEX} IN {PHP|range(1,10)} -->
  {INDEX}<!-- IF {INDEX} < 10 -->,<!-- ENDIF -->
<!-- ENDFOR -->

Цикл от 10 до 2 с шагом -2:

<!-- FOR {NUM} IN {PHP|range(10, 2, -2)} -->
  {NUM}<br />
<!-- ENDFOR -->

Как и логические блоки циклы могут включать в себя любые доступные для шаблона типы блоков и текста.

Имя ключа и значение находятся, как и другие теги, в едином с ними пространстве. В шаблонизаторе нет понятия области видимости или стеков.



1. Sergeich  11.03.2024 10:45

Спасибо большое за статью.

Добавление комментариев доступно только зарегистрированным пользователям