Техническое руководство по функциям парсера шаблонов, в частности функциям parse() и out(), а также основам работы с ними в Cotonti Siena через класс XTemplate.
 

Структура шаблонизатора в Cotonti Siena

В Cotonti встроена собственная система шаблонов, основанная на классе XTemplate, который является базовым механизмом для разбора и рендеринга файлов .tpl. Эта система присутствует в ядре CMF и реализована в файле system/cotemplate.php. 

Объектный интерфейс XTemplate — факты

Публичный API класса XTemplate содержит следующие методы, которые используются для управления шаблонами:

Методы в этом классе и их точные назначения:

(Это непосредственно методы класса — точная техника API, приведённая в документации XTemplate для Cotonti.) (cotonti.com)

Суть трёх ключевых методов

Ниже описано как фактически работает каждый метод, без домыслов.

1)  restart(string $path)

Назначение: Инициализация шаблона из файла.

Что делает на деле:

• Открывает файл шаблона по указанному пути $path.
• Разбирает его исходный код на базовые структуры: блоки, вложенные блоки, теги.
• Подготавливает внутренние структуры данных для дальнейшей обработки.

Этот метод не выводит HTML, а подготавливает объект XTemplate к разбору. (cotonti.com)

Пример использования:

$t = new XTemplate();
$t->restart($tpl_path);

где $tpl_path — путь к .tpl‑файлу. (cotonti.com)

2)  compile(string $code)

Назначение: Компиляция шаблона из строки, а не из файла.

Особенность:
Если вместо пути файла нужно обработать код, хранящийся в строковой переменной, используется compile().

Этот метод используется редко в пользовательском коде, но технически позволяет:

• принимать исходный текст шаблона,
• преобразовывать его в внутренние структуры так же, как restart(),
• но не производить чтение файла с диска. (cotonti.com)

3)  parse(string $block)

Назначение: Выполнить разбор одного блока, определённого в шаблоне.

Как работает технически:

• После загрузки шаблона методом restart() XTemplate знает о существующих блоках.
• Метод parse('BLOCK_NAME') запускает механизм генерации HTML для одного блока.
• Если блок содержит вложенные блоки — они будут парситься рекурсивно, согласно структуре шаблона.
• Переменные и теги (например {TAG} или {PHP.xxx}) заменяются на соответствующие значения.

Важно: это не вывод, а составление внутреннего результата. После parse() данные блока содержатся внутри объекта XTemplate. (cotonti.com)

Здесь важно понимать: чтобы блок был проанализирован более одного раза (например, для каждого элемента списка), нужно вызывать parse() в цикле. (cotonti.com)

Пример типичного цикла:

while($row = fetch data) {
    $t->assign([...]);
    $t->parse('ROW_BLOCK');
}

Сначала присваиваются переменные, затем вызывается parse для каждого набора. (cotonti.com)

4)  out(string $block)

Назначение: Вывести уже распарсенный блок.

Как работает:

• После выполнения parse('BLOCK_NAME'), внутреннее представление блока содержит готовый HTML.
• Вызов out('BLOCK_NAME') отправляет этот HTML в вывод, обычно в браузер или в буфер, в зависимости от сценария исполнения.
• out() аналогично echo для результатов разбора. (cotonti.com)

Важно: если перед out() не был вызван parse() для блока, то вывод будет пустым или некорректным, поскольку нет разобранных данных для вывода. (cotonti.com)

5)  reset(string $block)

Назначение: Очистить внутреннюю кешированную информацию блока.

Эффект:

• Удаляет данные, собранные в ранее вызовах parse() для блока.
• Позволяет повторно собрать блок с нуля (например, при смене данных). (cotonti.com)

6)  text(string $block)

Назначение: Возвращает собранный HTML не выводя напрямую.

Важное отличие от out():

• В отличие от out(), text() не отправляет результат напрямую на вывод.
• Он возвращает строку, которую можно сохранить в переменную, обработать или вставить в другой блок. (cotonti.com)

 Принцип сборки страницы в Cotonti

Типичная последовательность в Cotonti Siena выглядит так:

1. Создание XTemplate объекта

   $t = new XTemplate();
   

2. Подключение шаблона из файла

   $t->restart(cot_tplfile('page', 'module'));
   

   Функция cot_tplfile() возвращает путь к теме шаблона. (cotonti.com)

3. Присвоение значений тегам

   $t->assign('PAGE_TITLE', $page_title);
   

   Это связывает переменные PHP с TPL‑переменными. (cotonti.com)

4. Парсинг блока

   $t->parse('MAIN');
   

   Это собирает HTML внутри блока MAIN. (cotonti.com)

5. Вывод результата

   $t->out('MAIN');
   

   HTML отправляется пользователю. (cotonti.com)

 Факты vs распространённые подходы

 Факт: функции assign(), parse(), out() существуют в контексте XTemplate, а не как самостоятельные глобальные функции Cotonti. (cotonti.com)

Факт: в Cotonti используется именно объектный интерфейс XTemplate для разметки и рендеринга .tpl шаблонов. (cotonti.com)

Факт: шаблоны .tpl разбираются на блоки, имена которых чувствительны к регистру. (cotonti.com)

 Факт: CoTemplate как собственный механизм Cotonti основан на XTemplate и расширяет его возможностями по имени и синтаксису. (cotonti.com)

 Пример полного цикла (без догадок)

$t = new XTemplate();
$t->restart(cot_tplfile('page', 'main'));   // load main template
$t->assign('PAGE_TITLE', 'Hello World');     // assign variables
$t->parse('MAIN');                           // parse MAIN block
$t->out('MAIN');                             // output result

Если внутри MAIN есть вложенные блоки, они будут парситься автоматически на этапе parse('MAIN'). (cotonti.com)

 Итог

Все методы доступны в классе XTemplate, который лежит в ядре Cotonti Siena и формирует основу работы шаблонизатора для .tpl‑файлов.

Эта система присутствует в ядре CMF и реализована в файле system/cotemplate.php.