Шаблонизатор XTemplate

В Rapido.CMS используется open-source шаблонизатор XTemplate. XTemplate позволяет полностью отделить HTML код от PHP. У библиотеки есть много возможностей для, например, обработки блоков данных и переменных, за счет чего код становится легкочитаемым, коротким, а главное – оптимизированным. Примечательно то, что файлы шаблонов являются полностью валидными HTML-документами, что упрощает работу с шаблонами верстальщикам и вебмастерам мало знакомым с PHP.

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

$xtpl = new XTemplate( "main.htm", "./tpl/default/html" );

"main.htm" - файл шаблона
"./tpl/default/html" - путь ко всем шаблонам

Передача  переменных в шаблон (assign)

Простейший вариант:
$xtpl->assign('name', 'value');
В шаблоне будет доступен как {name}

Массив в качестве переменной:
$arr = array('key' => 'value', 'key2' => 'value2');
$xtpl->assign( 'name', $arr );
В шаблоне значения массива будут доступны как {name.key} и {name.key2}

Ассоциативный массив с переменными:
$xtpl->assign(array('name' => 'value', 'name2' => 'value2'));
В шаблоне: {name} {name2}

Ассоциативный массив также может содержать внутри себя массивы, например в файле index.php в шаблон передается сразу несколько массивов:
$xtpl->assign( array(
    'razdel' => $razdel,
    'opt' => $opt,
    'tpl' => $tpl );
В шаблонах элементы этих массивов доступны так: {opt.site_title} {razdel.URL} /tpl/default/

Использование многомерных массивов:
$xtpl->assign( 'name', array( 'level1' => array( 'level2' => "value" ) ) );
В шаблоне значение можно получить так: {name.level1.level2}

Парсинг (parse)

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

<!-- BEGIN: page -->
<!DOCTYPE html>
<html lang="ru">
<body>
    <!-- BEGIN: news -->
    <div class="news">
        <!-- BEGIN: i -->
        <div class="news-item"><a href="{f.url}">{f.ZAG}</a></div>
        <!-- END: i -->
    </div>
    <!-- END: news -->
</body>
</html>
<!-- END: page -->

Необходимо выполнить PHP скрипт следующего содержания:

for( $i=0; $i<3; $i++){
    $xtpl->assign( 'f', $news[$i] );
    $xtpl->parse( 'page.news.i' );
}
$xtpl->parse( 'page.news' );
$xtpl->parse( 'page' );

Важно соблюдать последовательность. Сначала выполняется передача переменной в шаблон (assign), потом парсинг внутренних блоков, потом парсинг внешних. Если сначала спарсить блок, а потом передать переменную, то на месте переменной будет пусто, или значение, которое ранее было назначено этой переменной в другом месте кода сайта.

Short-hand методы

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

Парсинг сразу нескольких блоков подряд:
$xtpl->parses( 'page.news', 'page' );

Передача переменной и парсинг в одной строке:
$xtpl->insert_loop( 'page.news.i', 'f', $news[$i] );

Парсинг всех элементов массива одной строкой:
$xtpl->array_loop( 'page.news.i', 'f', $news );

 

Получение и вывод результата

Вывод результата на экран:
$xtpl->out( $bname );

Вывод результата в файл:
$xtpl->out_file( $bname, $fname );

Получение результата в виде переменной:
$html = $xtpl->text( $bname );

$bname - название блока. Например "page.news.i" или "page"

 

Проверки

$xtpl->parsed( $bname );
Возвращает true если указанный блок уже парсился

Когда требуется проверить в php наличие необходимого блока в шаблоне, то можно выполнить следущий код:
if( isset( $xtpl->sub_blocks["page.menu.i.submenu"] ) ){
    // Some code
}

Вложенные файлы

К примеру у нас есть шаблон main.htm и мы хотим вложить в него содержимое из файла header.htm. Тогда в шаблоне main.htm необходимо вставить тег {FILE 'header.htm'} в месте, где должно появится содержимое этого файла. Вложенные файлы также являются шаблонами и могут содержать как блоки <!-- BEGIN: blockname -->, так и переменные {opt.site_title} и вложенные файлы. Таким образом вложенность файлов не ограничивается.

Еще один вариант: вкладывание файла через переменную.
PHP:
$xtpl->assign_file( 'MODULFILE', 'video.htm');
В шаблоне:
{FILE {MODULFILE}}

Механизм функций-обработчиков (callback)

Если в шаблон вставляется переменная, которую необходимо дополнительно обработать, то можно воспользоваться механизмом callback встроенным в шаблонизатор XTemplate. Например, в панели управления мы можем создать опцию для ввода адреса, в адресе могут быть переносы на новую строку и чтобы они корректно отобразились в HTML необходимо дополнительно обработать эту переменную функцией nl2br(). Чтобы не делать этого в коде PHP и не нарушать идеологию MVC можно сделать вставку в шаблон переменной с указанием функции-обработчика: {address|nl2br}

Также часто требуется перевести специальные символы в html сущности. Например если мы вставляем название товара в атрибут alt изображения, то надо обезопасить себя от возможных кавычек в названии. Сделать это можно так:
<img src="image.jpg" alt="{f.ZAG|htmlspecialchars}">

Если необходимо указать несколько обработчиков, то они указываются в той последовательности, в которой их необходимо вызывать:
{var|func1|func2|func3}

Передача переменных в обработчик

Если в качестве обработчика используется php функция, которая принимает в качестве аргументов несколько переменных, то аргументы указываются в скобках, при этом вместо аргумента с обрабатываемой переменной указывается %s.
{var|callback(true, %s)}

Если обрабатываемая переменная должна указываться в обработчике первой, то ее можно не указывать. Например следующие две строки эквивалентны:
{var|callback( %s, true)}
{var|callback(true)}

Доступные обработчики

В качестве обработчиков могут выступать только разрешенные функции. Список поддерживаемых функций перечислен в следующем массиве:

$allowed_callbacks = array(
	// Simple string modifiers
	'strtoupper', 'strtolower', 'mb_strtoupper', 'mb_strtolower', 'ucwords', 'ucfirst', 'mb_ucfirst', 'strrev', 'str_word_count', 'strlen',
	// String replacement modifiers
	'str_replace', 'str_ireplace', 'preg_replace', 'strip_tags', 'stripcslashes', 'stripslashes', 'substr',
	'str_pad', 'str_repeat', 'strtr', 'trim', 'ltrim', 'rtrim', 'nl2br', 'wordwrap', 'printf', 'sprintf',
	'addslashes', 'addcslashes', 'space2nbsp',
	// Encoding / decoding modifiers
	'htmlentities', 'html_entity_decode', 'htmlspecialchars', 'htmlspecialchars_decode',
	'urlencode', 'urldecode',
	// Date / time modifiers
	'date', 'idate', 'strtotime', 'strftime', 'getdate', 'gettimeofday',
	// Number modifiers
	'number_format', 'money_format',
	// Miscellaneous modifiers
	'var_dump', 'print_r', 'textcrop', 'dformat', 'arr_get', 'plural', 'gender', 'ifis', 'rpnum', 'units', 'rpdt', 'rpimg', 
	'toTranslit', 'parse_links', 'num2str', 'nl2p', 'get2levdomain', 'getage', 'month_form2', 'showtime', 'get_tels'
	);

 Описание обработчиков, специфичных для Rapido.CMS можно прочитать на странице с описанием разметки.