CoTemplate: Документация по шаблонизатору Cotonti
CoTemplate — это быстрый и легковесный шаблонизатор, входящий в состав Cotonti CMF. Он совместим с синтаксисом XTemplate (http://www.phpxtemplate.org), но имеет ряд дополнительных возможностей: поддержка фильтров, условных блоков, циклов, кеширование, встроенные средства отладки. Шаблонизатор компилирует шаблоны во внутреннее представление (объекты), что обеспечивает высокую производительность.
Данная статья познакомит вас с основными возможностями CoTemplate и научит эффективно использовать его при разработке сайтов на Cotonti.
1. Основы работы с XTemplate
1.1. Создание экземпляра и загрузка шаблона
Для работы с шаблоном необходимо создать объект класса XTemplate, передав конструктору путь к файлу шаблона:
php
$tpl = new XTemplate('путь/к/файлу.tpl');Если файл не найден, будет выброшено исключение.
1.2. Передача переменных в шаблон
Метод assign() используется для передачи значений в шаблон:
php
$tpl->assign('TITLE', 'Заголовок страницы');
$tpl->assign([
'NAME' => 'Иван',
'EMAIL' => '[email protected]'
]);Переменные становятся доступны в шаблоне как {TITLE}, {NAME}, {EMAIL}.
1.3. Разбор и вывод шаблона
Шаблонизатор работает с блоками. По умолчанию существует корневой блок MAIN. Чтобы получить обработанный HTML, необходимо вызвать parse() для нужного блока, а затем text() или out():
php
$tpl->parse('MAIN');
echo $tpl->text('MAIN');Метод out('MAIN') сразу выводит результат.
2. Синтаксис шаблонов
2.1. Переменные
Простые переменные выводятся как {ИМЯ}. Если переменная не определена, подставляется пустая строка.
Поддерживаются составные переменные через точку для доступа к элементам массива или свойствам объекта: {USER.NAME}.
Пример:
html
<p>Привет, {USER.NAME}!</p>2.2. Фильтры (модификаторы)
К переменным можно применять фильтры через символ |. Например:
html
{PAGE_DATE|cot_date('d.m.Y', $this)}Здесь cot_date — это функция PHP, которая получает значение переменной (если передано $this) и возвращает отформатированную строку. Можно указывать несколько фильтров последовательно:
html
{NAME|strip_tags|trim|ucfirst}В качестве аргументов фильтров можно передавать строки в кавычках, числа, другие переменные:
html
{PHP|cot_url('page', 'id=' . $this)}2.3. Специальная переменная {PHP}
Переменная {PHP} предоставляет доступ к глобальным переменным PHP (массиву $GLOBALS). Например:
{PHP.cfg.version} — версия Cotonti{PHP.usr.id} — ID текущего пользователя{PHP.sys.now} — текущий timestamp
Можно использовать составные ключи: {PHP.cfg.defaulttheme}.
3. Работа с блоками
Блоки позволяют многократно выводить повторяющиеся фрагменты, например, списки новостей.
3.1. Определение блока
Блок задаётся конструкцией:
html
<!-- BEGIN: blockname -->
... содержимое блока ...
<!-- END: blockname -->
Блоки могут быть вложенными.
3.2. Разбор блока
В PHP для заполнения блока вызывают parse() с именем блока. Если блок должен повторяться, parse() вызывают несколько раз:
php
foreach ($items as $item) {
$tpl->assign('ITEM_TITLE', $item['title']);
$tpl->parse('MAIN.ITEM_ROW'); // блок ITEM_ROW внутри MAIN
}Имена вложенных блоков указываются через точку: 'MAIN.ITEM_ROW'.
3.3. Очистка блока
Если нужно сбросить ранее накопленные данные блока (например, для повторного использования), используйте reset('blockname').
3.4. Проверка наличия блока
Метод hasBlock('blockname') возвращает true, если блок присутствует в шаблоне.
4. Условные блоки (IF)
CoTemplate поддерживает полноценные условные конструкции с логическими операторами.
4.1. Синтаксис
html
<!-- IF условие -->
текст, если условие истинно
<!-- ELSE -->
текст, если условие ложно
<!-- ENDIF -->
4.2. Операторы
Поддерживаются следующие операторы (в порядке убывания приоритета):
*, /, % — умножение, деление, остаток+, - — сложение, вычитаниеHAS — проверка наличия значения в массиве~= — проверка вхождения подстроки (contains)==, ===, !=, !==, <, >, <=, >= — сравнения! — логическое НЕAND — логическое ИOR, XOR — логическое ИЛИ, исключающее ИЛИ
Также можно использовать скобки для группировки.
Примеры:
html
<!-- IF {COUNT} > 0 AND {COUNT} < 10 -->
Количество от 1 до 9
<!-- ENDIF -->
<!-- IF {USER_GROUP} HAS 'admin' -->
Привет, администратор!
<!-- ENDIF -->
<!-- IF {STRING} ~= 'error' -->
Обнаружена ошибка
<!-- ENDIF -->4.3. Операнды
В качестве операндов могут выступать:
- числа (целые и с плавающей точкой)
- строки в кавычках (одинарных или двойных)
- переменные
{VAR} - булевы константы
true, false null
5. Циклы FOR
CoTemplate позволяет перебирать массивы с помощью цикла FOR.
5.1. Синтаксис
html
<!-- FOR {key}, {value} IN {array} -->
<!-- содержимое цикла -->
<!-- ENDFOR -->Если ключ не нужен, можно использовать сокращённую форму:
html
<!-- FOR {value} IN {array} -->
...
<!-- ENDFOR -->5.2. Пример
В PHP:
php
$tpl->assign('USERS', [
['name' => 'Иван', 'age' => 25],
['name' => 'Петр', 'age' => 30]
]);В шаблоне:
html
<!-- FOR {index}, {user} IN {USERS} -->
<p>Пользователь {index}: {user.name}, возраст {user.age}</p>
<!-- ENDFOR -->Цикл автоматически подставляет на каждой итерации значения в переменные {user} и {index} (если указан ключ). Внутри цикла можно использовать составные переменные для доступа к полям.
6. Включение файлов (FILE)
Директива {FILE "путь"} позволяет вставить содержимое другого шаблонного файла.
html
{FILE "parts/header.tpl"}Путь может содержать переменные:
html
{FILE "{PHP.cfg.themes_dir}/default/parts/footer.tpl"}Шаблонизатор рекурсивно обрабатывает включения.
7. Кеширование скомпилированных шаблонов
Для повышения производительности CoTemplate может кешировать внутреннее представление шаблонов на диске.
7.1. Настройка кеша
Перед созданием объектов XTemplate необходимо вызвать статический метод XTemplate::init() с параметрами:
php
XTemplate::init([
'cache' => true,
'cacheDir' => '/path/to/cache',
'cleanup' => false, // удалять лишние пробелы (минификация)
'debug' => false, // режим отладки
'debugOutput' => false // вывод отладочной информации
]);
Папка cacheDir должна быть доступна для записи. Кеш автоматически обновляется при изменении исходного шаблона.
8. Отладка
CoTemplate предоставляет удобные средства отладки.
8.1. Режим отладки
При включённом режиме (debug и debugOutput) шаблонизатор выводит структуру переменных, переданных в каждый блок, прямо в браузер. Это помогает быстро найти ошибки в assign.
8.2. Получение отладочных данных
Метод XTemplate::debugData() возвращает массив с информацией о всех переменных, использованных при разборе шаблона.
8.3. Фильтр dump
В шаблоне можно использовать фильтр dump для вывода дампа переменной:
html
{USER|dump}Это выведет структуру переменной в отформатированном виде.
9. Дополнительные возможности
9.1. Проверка наличия тегов
Метод getTags() возвращает список всех тегов, встречающихся в шаблоне. Метод hasTag('TAG') проверяет, присутствует ли тег.
9.2. Работа с произвольным кодом шаблона
Метод compile($code) позволяет скомпилировать шаблон непосредственно из строки, а не из файла. Это полезно для генерации динамических шаблонов.
10. Пример использования
Рассмотрим небольшой пример. Пусть у нас есть шаблон list.tpl:
html
<!-- BEGIN: MAIN -->
<h1>{TITLE}</h1>
<!-- BEGIN: ITEM_ROW -->
<div class="item">
<h3>{ITEM_TITLE}</h3>
<p>{ITEM_DESC}</p>
</div>
<!-- END: ITEM_ROW -->
<!-- END: MAIN -->PHP-код:
php
$tpl = new XTemplate('list.tpl');
$tpl->assign('TITLE', 'Список новостей');
$items = [
['title' => 'Новость 1', 'desc' => 'Описание 1'],
['title' => 'Новость 2', 'desc' => 'Описание 2']
];
foreach ($items as $item) {
$tpl->assign([
'ITEM_TITLE' => $item['title'],
'ITEM_DESC' => $item['desc']
]);
$tpl->parse('MAIN.ITEM_ROW');
}
$tpl->parse('MAIN');
echo $tpl->text('MAIN');
11. Заключение
CoTemplate — мощный, но простой в освоении шаблонизатор. Он предоставляет все необходимые конструкции для отделения логики от представления: блоки, условия, циклы, фильтры. Благодаря кешированию и компактному коду он отлично подходит для высоконагруженных проектов.
Документация по конкретным функциям и классам всегда доступна в исходных файлах Cotonti. Освоив основные приёмы, вы сможете быстро создавать гибкие и удобные в поддержке шаблоны для своих сайтов.
