XTemplate в Cotonti

XTemplate для программистов

Каждый, кто работал с шаблонами в Cotonti, сталкивался с использованием шаблонных тегов. Теги — это короткие фрагменты кода, которые при разборе (парсинге) системой XTemplate заменяются на соответствующие блоки HTML-кода. Это позволяет использовать файл шаблона исключительно для хранения HTML-кода, в то время как весь сгенерированный код, выполняемый на стороне сервера, поддерживается с помощью плагинов и обрабатывается через теги.

Основы работы с XTemplate

При разработке плагина для Cotonti важно понимать, как в системе XTemplate определяются теги и условные блоки. Ранее многие плагины использовали стандартный способ получения HTML-кода для парсинга и отображения. Хотя использование XTemplate с собственным файлом шаблона предоставляет гораздо больше возможностей, можно использовать и старый метод для отдельных плагинов. Для этого нужно работать с переменными $plugin_title, $plugin_subtitle, и $plugin_body, которые автоматически привязываются к тегам {PLUGIN_TITLE}, {PLUGIN_SUBTITLE}, и {PLUGIN_BODY}.

Если вы хотите использовать свой собственный файл шаблона, необходимо создать объект XTemplate. Это объектно-ориентированный элемент Cotonti. Для создания объекта XTemplate можно использовать следующий код:

$t = new XTemplate('path/to/file.tpl');

Здесь $t — это переменная, представляющая объект XTemplate, а 'path/to/file.tpl' — путь к файлу шаблона относительно корня Cotonti. Однако, такой способ не очень гибок, и для большей универсальности рекомендуется использовать функцию cot_tplfile():

$t = new XTemplate(cot_tplfile('pluginname', 'plug'));

В этом случае первый параметр — это имя файла без расширения, а второй параметр указывает на тип файла, который может быть plug для плагинов, module для модулей, или core для основного кода. Функция cot_tplfile() автоматически находит правильный путь к файлу шаблона. Обратите внимание, что имя файла должно начинаться с pluginname. Для нескольких файлов шаблонов можно использовать имена вроде pluginname.secondary.tpl, где расширение .tpl опускается.

Использование метода assign()
Следующий шаг — это назначение значений тегам в шаблоне. Для этого используется метод assign():

$t->assign();

Метод assign() может принимать как одиночные теги, так и массив тегов:

$t->assign('SINGLE_TAG', '<p>HTML-код</p>');
$t->assign(array(
    'TAG_ONE' => '<p>HTML-код</p>',
    'TAG_TWO' => $somevariable
));

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

Использование цикла и метода parse()
Однако если вы хотите отобразить несколько строк данных, например, из базы данных, вам нужно использовать цикл, например, while. Рассмотрим следующий код:

while($row = $sql->fetch())
{
    $t->assign(array(
        'PAGE_ROW_ID' => $row['page_id'],
        'PAGE_ROW_TITLE' => $row['page_title']
    ));
}

Этот код назначает значения тегам для каждой строки результата SQL-запроса. Однако если вы используете несколько строк, теги будут переопределяться на каждой итерации цикла. Чтобы избежать этого, нужно использовать метод parse():

$t->parse();

Метод parse() принимает один параметр — блок кода, который должен быть определен в файле шаблона в виде HTML-комментариев. Каждый блок должен быть заключен в теги BEGIN и END:

<!-- BEGIN: BLOCK_CODE -->
...
<!-- END: BLOCK_CODE -->

В файле шаблона Cotonti основной блок всегда называется MAIN, но можно использовать и другие блоки. В коде PHP плагина нужно добавить метод parse() к циклу while:

while($row = $sql->fetch())
{
    $t->assign(array(
        'PAGE_ROW_ID' => $row['page_id'],
        'PAGE_ROW_TITLE' => $row['page_title']
    ));
    $t->parse('MAIN.PAGE_ROW');
}

Здесь мы создали блок PAGE_ROW внутри основного блока MAIN. Если вам нужно использовать несколько блоков, вы можете задать их и обработать по аналогии.

Структура шаблона

Шаблон может выглядеть следующим образом:

<!-- BEGIN: MAIN -->
    <h1>{SINGLE_TAG}</h1>
 
    <!-- BEGIN: PAGE_ROW -->
    <p>{PAGE_ROW_TITLE}</p>
    <!-- END: PAGE_ROW -->
<!-- END: MAIN -->

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

$t->parse('ALTERNATIVE');
$t->out('ALTERNATIVE'); // Только для standalone

Лучше всего делать это непосредственно перед закрытием тега PHP.