Руководство по методам parse(), text() и out() в XTemplate Cotonti Siena v0.9.26

В Cotonti Siena v0.9.26 шаблонизатор CoTemplate (также известный как XTemplate в документации) управляет рендерингом шаблонов. Класс XTemplate обрабатывает присвоение переменных, парсинг блоков и вывод. Методы parse(), text() и out() — ключевые для обработки блоков в файлах .tpl. Они работают с блоками, обозначенными как ... . Блоки могут быть вложенными (MAIN.SUBBLOCK).

XTemplate инициализируется как $t = new XTemplate('path/to/template.tpl');. После assign() (присвоение тегов) используются эти методы. Все методы принимают string block (имя блока, например 'MAIN' или 'MAIN.PAGE_ROW').

1. Метод parse(string block)

Определение: Парсит указанный блок, заменяя теги на значения, обрабатывая условия, циклы и callbacks. Модифицирует внутреннее состояние объекта ($blocks, $vars, $index). Не выводит результат.

Параметры:

• block (string): Имя блока для парсинга.

Возвращаемое значение: Объект XTemplate ($this) для цепочки вызовов.

Контекст использования: Вызывается после assign() для подготовки блока. Обязателен в циклах для накопления данных без перезаписи. В плагинах/модулях парсит динамические данные из БД. MAIN-блок парсится автоматически Cotonti; другие — вручную.

Пример кода (из документации Cotonti):

PHP

$sql = $db->query("SELECT * FROM $db_pages WHERE page_state=0");
while ($row = $sql->fetch()) {
 $t->assign([
 'PAGE_ROW_ID' => $row['page_id'],
 'PAGE_ROW_TITLE' => $row['page_title']
 ]);
 $t->parse('MAIN.PAGE_ROW'); // Парсит блок для каждой строки
}

Шаблон (.tpl):

text

<!-- BEGIN: MAIN -->
 <!-- BEGIN: PAGE_ROW -->
 <p>ID: {PAGE_ROW_ID}, Title: {PAGE_ROW_TITLE}</p>
 <!-- END: PAGE_ROW -->
<!-- END: MAIN -->

Результат: Накопленный HTML для всех строк в MAIN.PAGE_ROW.

Аналогия: Parse() — как компилятор кода: читает исходник (блок), заменяет плейсхолдеры (теги) на данные, но не исполняет/выводит. Как make в сборке ПО: подготавливает объектные файлы.

Факты из кода Cotonti v0.9.26: Внутренне использует regex для замены тегов, обрабатывает callbacks (например, {TAG|function()}), поддерживает строгие операторы (===, !==) с версии 0.9.0. В debug_mode добавляет отладочные данные в $debug_output.

2. Метод text(string block)

Определение: Возвращает парсированный HTML-текст блока как строку. Требует предварительного parse(). Не выводит, позволяет дальнейшую обработку (например, в email или AJAX).

Параметры:

• block (string): Имя блока.

Возвращаемое значение: string — парсированный HTML.

Контекст использования: Для захвата вывода без эха. Полезно в модулях для генерации строк (например, для cot_mail()). В standalone-плагинах — альтернатива out() для манипуляции строкой перед выводом.

Пример кода (из Cotonti reference):

PHP

$t = new XTemplate('templates/my_template.tpl');
$t->assign('TITLE', 'Welcome');
$t->parse('HEADER');
$html = $t->text('HEADER'); // Возвращает строку
echo $html; // <h1>Welcome</h1>

Шаблон (.tpl):

text

<!-- BEGIN: HEADER -->
<h1>{TITLE}</h1>
<!-- END: HEADER -->

Результат: Строка '

Welcome

'.

Аналогия: Text() — как getContents() в буфере вывода: собирает готовый текст после парсинга, но не печатает. Как чтение файла после записи: возвращает содержимое без показа.

Факты из кода Cotonti v0.9.26: Зависит от $blocks после parse(). Поддерживает cleanup (удаление пробелов/комментариев) если $cleanup=true в init(). В debug — добавляет array('filename.tpl' => array('BLOCK.NAME' => ...)).

3. Метод out(string block)

Определение: Выводит (echo) парсированный HTML блока. Автоматически вызывает parse() если блок не парсирован. Возвращает $this для цепочки.

Параметры:

• block (string): Имя блока.

Возвращаемое значение: Объект XTemplate ($this).

Контекст использования: Для прямого вывода в standalone-плагинах (не MAIN). Cotonti автоматически вызывает out('MAIN') для основного шаблона. В hooks — для вставки контента.

Пример кода (из Cotonti docs):

PHP

$t = new XTemplate('templates/index.tpl');
$t->assign('USER', 'Alice');
$t->out('MAIN'); // Выводит: <div>Hello, Alice</div>

Шаблон (.tpl):

text

<!-- BEGIN: MAIN -->
<div>Hello, {USER}</div>
<!-- END: MAIN -->

Результат: Прямой вывод HTML в поток.

Аналогия: Out() — как printf в C: парсит и сразу печатает. Как echo после подготовки: комбинирует parse() + text() + echo.

Факты из кода Cotonti v0.9.26: Внутренне: if (!parsed) parse(block); then echo text(block). Поддерживает cache via $cache_enabled/$cache_dir. В admin-панели — отдельные вызовы для custom тем.

Сравнение методов

Рекомендации по использованию в Cotonti Siena v0.9.26

1. Инициализация: $t = new XTemplate(cot_tplfile('name', 'module')); — стандарт для модулей.
2. В циклах: Всегда parse() внутри loop после assign().
3. Standalone: parse() + out() для не-MAIN блоков.
4. Debug: $cfg['debug_mode'] = true; — показывает теги/блоки в выводе.
5. Callbacks: В блоках — {TAG|func($this)} — обрабатывается в parse().
6. Версия: С 0.9.19 — поддержка multi-аргументов в callbacks (e.g. {PHP|cot_url('page', 'c=news')}).
7. Очистка: reset(string block) — сбрасывает парсированные данные.

Примеры в реальных сценариях

Пример 1: Плагин с выводом списка (standalone):

PHP

$t = new XTemplate(cot_tplfile('plugin', 'plug'));
$t->assign('PLUGIN_TITLE', 'List');
$sql = $db->query("SELECT * FROM table LIMIT 5");
while ($row = $sql->fetch()) {
 $t->assign('ROW_DATA', $row['data']);
 $t->parse('ALTERNATIVE.ROW');
}
$t->parse('ALTERNATIVE');
$t->out('ALTERNATIVE');

Шаблон:

text

<!-- BEGIN: ALTERNATIVE -->
<h2>{PLUGIN_TITLE}</h2>
<!-- BEGIN: ROW -->
<p>{ROW_DATA}</p>
<!-- END: ROW -->
<!-- END: ALTERNATIVE -->

Пример 2: Захват текста для email:

PHP

$t = new XTemplate('email.tpl');
$t->assign('USER_NAME', $usr['name']);
$t->parse('EMAIL');
$body = $t->text('EMAIL');
cot_mail($email, 'Subject', $body);

Шаблон:

text

<!-- BEGIN: EMAIL -->
Dear {USER_NAME},
...
<!-- END: EMAIL -->

Аналогия для всех:

 XTemplate — как кухонный комбайн: 

parse() — измельчает ингредиенты (данные в блоки), 

text() — возвращает смесь (строку), 

out() — подает блюдо (выводит).