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

Руководство для новичков: методы assign(), parse(), text() и out() в XTemplate (CoTemplate) Cotonti Siena v0.9.26

Представьте, что вы — повар, а XTemplate — ваш кухонный комбайн. Вы хотите приготовить красивое «блюдо» — веб-страницу. Шаблон .tpl — это рецепт (чистый HTML + специальные теги {НАЗВАНИЕ}). Данные из базы или PHP — это продукты (овощи, мясо, специи).

Методы assign(), parse(), text() и out() — это четыре главные кнопки комбайна:

Теперь разберём каждую кнопку подробно, с примерами и комментариями, как будто вы впервые открыли кухню Cotonti.

0. Метод assign() — «Кладём продукты на рабочую поверхность»

Простыми словами:
Самый первый шаг. Вы говорите комбайну: «Вот эти данные — используй их вместо {ТЕГОВ} в рецепте».

Когда использовать:
Всегда **перед** parse() — без assign() в шаблоне будут пустые места или останутся сами {ТЕГИ}.

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

Пример кода (самые частые варианты)

// Вариант 1: одна переменная
$t->assign('PAGE_TITLE', 'Моя первая статья');
// Вариант 2: сразу много — самый удобный и частый способ
$t->assign([
 'SITE_NAME' => $cfg['maintitle'],
 'USER_NAME' => $usr['name'],
 'CURRENT_YEAR' => date('Y'),
 'WELCOME_TEXT' => 'Приветствуем вас на сайте!',
 'LOGO_URL' => cot_url('index') . '/images/logo.png'
]);
// Вариант 3: целый кусок готового HTML
$t->assign('CUSTOM_BANNER', 'Акция -50% до конца недели!');

Важно: теги в шаблоне пишутся в верхнем регистре: {USER_NAME}, а не {user_name}. Если забыть assign — в debug-режиме увидите незаполненные теги.

1. Метод parse(string $block) — «Готовим порцию в миске»

Простыми словами: Метод берёт блок из шаблона, заменяет все {ТЕГИ} на реальные данные, обрабатывает циклы и условия — и складывает готовый кусок HTML внутрь объекта. На экран ничего не выводит!

Когда использовать:

• Внутри циклов (чтобы накопить много строк).
• Когда нужно подготовить блок, но выводить позже.

Аналогия: Вы нарезаете 10 огурцов и кидаете их в одну большую миску. Миска (объект $t) теперь содержит все огурцы, но на стол вы ещё ничего не поставили.

Пример кода (самый частый случай — вывод списка страниц)

// 1. Создаём комбайн и даём ему рецепт (шаблон)
$t = new XTemplate(cot_tplfile('list', 'module')); // или просто 'templates/mytpl.tpl'
// 2. Берём продукты из базы
$sql = $db->query("SELECT * FROM $db_pages WHERE page_state = 0 LIMIT 20");
while ($row = $sql->fetch()) { // для каждой страницы
 // 3. Кладём продукты в миску именно для этой строки
 $t->assign([
 'PAGE_ROW_ID' => $row['page_id'], // {PAGE_ROW_ID} → 15
 'PAGE_ROW_TITLE' => $row['page_title'], // {PAGE_ROW_TITLE} → "О чём эта статья"
 'PAGE_ROW_URL' => cot_page_url($row) // ссылка
 ]);
 // 4. САМОЕ ВАЖНОЕ: «нарезаем» эту строку и добавляем в миску
 // Без этого строка просто потеряется!
 $t->parse('MAIN.PAGE_ROW'); // вложенный блок
}
// 5. Говорим: «Теперь собери всё главное блюдо»
$t->parse('MAIN');
// Дальше можно вывести (см. метод out ниже)

Шаблон list.tpl (рецепт):

<!-- BEGIN: MAIN -->
 <h1>Список страниц</h1>
 <!-- BEGIN: PAGE_ROW -->
 <div class="page-item">
 <a href="{PAGE_ROW_URL}">{PAGE_ROW_TITLE}</a>
 (ID: {PAGE_ROW_ID})
 </div>
 <!-- END: PAGE_ROW -->
<!-- END: MAIN -->

Результат: в MAIN накопится 20 готовых <div class="page-item">...</div>.

2. Метод text(string $block) — «Переливаем в контейнер»

Простыми словами: После parse() вы можете взять готовый HTML как обычную строку и делать с ней всё что угодно: отправить по почте, сохранить в файл, отдать через AJAX и т.д.

Аналогия: Вы приготовили суп в комбайне, а теперь перелили его в пластиковый контейнер, чтобы забрать домой или отправить другу.

Пример:

$t = new XTemplate('templates/email.tpl');
$t->assign([
 'USER_NAME' => $usr['name'],
 'USER_EMAIL' => $usr['email']
]);
$t->parse('EMAIL'); // готовим
$body = $t->text('EMAIL'); // ← вот тут получили строку!
// Теперь можно отправить письмо
cot_mail($usr['email'], 'Привет от сайта!', $body);

Шаблон email.tpl:

<!-- BEGIN: EMAIL -->
 <p>Здравствуйте, {USER_NAME}!</p>
 <p>Ваш email: {USER_EMAIL}</p>
 <p>Спасибо, что вы с нами ❤️</p>
<!-- END: EMAIL -->

3. Метод out(string $block) — «Подаём на стол»

Простыми словами: Самый простой способ показать результат пользователю. Сначала пытается сделать parse(), потом сразу echo (выводит на экран).

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

Пример:

$t = new XTemplate(cot_tplfile('index', 'module'));
$t->assign('SITE_TITLE', 'Мой крутой сайт');
$t->assign('USER', $usr['name']);
// Один вызов — и всё на экране!
$t->out('MAIN');

Cotonti сам вызывает $t->out('MAIN') в конце работы модуля — поэтому в обычных шаблонах вам почти никогда не нужно писать out('MAIN') вручную.

Сравнение четырёх методов (таблица для запоминания)

Полезные советы для новичков

1. Всегда делайте parse('MAIN.ЧТО_ТО') внутри while/for — иначе данные перезапишутся!
2. Главный блок MAIN почти всегда парсится автоматически.
3. Хотите очистить миску? → $t->reset('MAIN.PAGE_ROW');
4. Включайте отладку: $cfg['debug_mode'] = true; — увидите все блоки и теги.
5. Callback-функции — это «специи»: {PAGE_ROW_TITLE|cot_string_truncate:50}

Общая аналогия-шпаргалка (кухонная)

• assign() → кладёте продукты на стол комбайна
• parse() → включаете режим «измельчить и смешать»
• text() → переливаете в банку
• out() → сразу ставите тарелку на стол

Теперь вы точно знаете, какую кнопку нажать, чтобы ваше «блюдо» (веб-страница) получилось идеальным!