13 514
правок
Изменения
Новая: Шаблонизатор VMX::Template зародился реализованным на языке PHP, как адаптация шаблонизатора из phpBB2. Далее б...
Шаблонизатор VMX::Template зародился реализованным на языке PHP, как адаптация шаблонизатора из phpBB2. Далее был развит и переписан на Perl. Далее был [[Шаблонизатор VMX::Template|развит ещё больше]] и переписан с нуля.
VMX::Template — простой и быстрый шаблонизатор, выросший из шаблонизатора phpBB2.
Legacy-версия. Новая стабильная версия входит в Solstice Homepage System (см. ветку svn branches/solstice).
== Программный интерфейс ==
<code perl>
# Конструктор
$template = VMX::Template->new(
root => '.', # каталог с шаблонами
reload => 1, # если 0, шаблоны не будут перечитываться с диска, и вызовов stat() происходить не будет
wrapper => undef, # фильтр, вызываемый перед выдачей результата parse
cache_dir => undef, # необязательный кэш, ускоряющий работу только в случае частых инициализаций интерпретатора
use_utf8 => undef, # шаблоны в UTF-8 и с флагом UTF-8
);
# Выбор файла шаблона:
$template->set_filenames('alias' => 'file-name.tpl');
# Задание кода шаблона «на месте»:
$template->set_filenames('alias' => \ 'код шаблона');
# Загрузка файлов автоматических переводов:
# Каждый такой файл содержит код на языке Perl, возвращающий ссылку на хеш.
# Загрузка происходит с автоматическим пересчитыванием с диска при изменениях.
$template->load_lang(«файл1.pl», «файл2.pl»);
# Загрузка хешей в качестве языковых данных:
$template->load_lang_hashes({ block => { var => 'перевод' } });
# Присвоение переменных корневого уровня:
$template->assign_vars(KEY => «значение»);
# Присвоение переменных блока-цикла в новую итерацию блока:
$template->assign_block_vars(«block», KEY => «значение»);
# Или то же, но без копирования готового хешрефа:
$template->assign_block_vars(«block», { KEY => «значение» });
# Или то же, но в последнюю заданную итерацию блока, а не в новую:
$template->append_block_vars(«block», KEY => «значение»);
# Выполнение шаблона и получение результатов (страницы):
# Выбранные файлы автоматически перезачитываются с диска при изменениях.
# Код кэшируется на 2-х уровнях: на диске в виде perl-кода и в памяти в скомпилированном виде.
$page = $template->parse('alias');
# Очистка сохранённых данных для генерации новой страницы:
$template->clear;
</code>
== Синтаксис ==
Идея синтаксиса шаблонов — быть максимально простым и не поганить HTML-код.
=== Комментарии ===
<pre><!--# Комментарий, не попадающий в результат исполнения #--></pre>
=== Включение (INCLUDE) ===
<pre>
Включение шаблона с именем filename.tpl:
<!-- INCLUDE filename.tpl -->
</pre>
=== Подстановки переменных ===
{переменная} или {переменная->путь} или {переменная/преобразование}
Где переменная — цепочка идентификаторов, разделённая точками. Все, кроме последнего — имена блоков, последний — имя переменной. После имени переменной может идти путь по ней, если она представляет собой хеш или массив. Путь — цепочка идентификаторов или чисел, разделённая стрелками -> Например, {DOMAIN} — подстановка корневой переменной DOMAIN. А {site.url.DOMAIN} — подстановка переменной DOMAIN блока url, вложенного в блок site. А {site.url.CONFIG->rules->0/s} — подстановка первого элемента массива, вложенного в переменную CONFIG блока url, вложенного в блок site, по ключу rules, в HTML-безопасном виде (то есть с преобразованием s, см.ниже).
А преобразование — одно из:
# T — удаление всех HTML тегов из значения
# H — удаление всех HTML тегов из значения, кроме разрешённых в VMX::Common
# i — преобразование значения к целому числу
# s — замена всех символов < > & " ' на HTML сущности < > & " '
# l — перевод значения в нижний регистр
# u — перевод значения в верхний регистр
# q — замена всех символов « ' \ на \» \' \\
# L — замена значения на его контекстный перевод, если таковой имеется
# Lz — замена значения на его контекстный перевод, если таковой имеется, и на пустое значение, если нет
=== Условный вывод (IF) ===
<pre>
<!-- IF[тест] подстановка -->
<!-- END -->
</pre>
Где подстановка — любая допустимая в {фигурных.скобках} подстановка.
Тесты:
# ! — логическое отрицание
# EVEN — истина в случае, если значение — чётное число
# ODD — истина в случае, если значение — нечётное число
# EQ:строка — истина в случае, если значение переменной совпадает с «строка»
# MOD:делитель, остаток — истина в случае, если остаток от деления значения переменной на «делитель» равен «остатку»
Например:
<pre>
<!-- IF! site.url.CONFIG->rules->0/Lz -->
<!-- END -->
</pre>
=== Циклический вывод (BEGIN block) ===
Циклический вывод, начать с итерации start (считаются с нуля), и вывести максимум по итерацию count. Либо обработать все итерации с номерами, дающими остаток от деления на «div» равный «mod». Имя блока состоит из латинских символов, цифр и символа '_' (подчёркивания).
Итак, варианты начала:
<pre>
<!-- BEGIN block -->
<!-- BEGIN block AT start -->
<!-- BEGIN block AT start count -->
<!-- BEGIN block MOD div mod -->
</pre>
Конец блока — всегда <!-- END block -->.
Пример:
<pre>
<!-- BEGIN block -->
<!-- BEGIN inner_block -->
{block.inner_block.VARIABLE}
{inner_block.#}
<!-- END inner_block -->
<!-- END block -->
</pre>
И специальный случай: внутри внутреннего блока {inner_block.#} имеет значением номер текущей итерации внутреннего блока, считающийся с 1. Именно {inner_block.#}, а не {block.inner_block.#}.
=== Автоматические контекстные переводы ===
Они доступны в двух вариантах: %Переводимая строка% и {переменная/L}.
Идея в том, чтобы автоматически заменять строки на другие строки в зависимости от их расположения в файле шаблона (контекста).
Контекст включает в себя:
# путь к файлу шаблона.
# путь к текущему блоку-циклу.
# в случае перевода переменной — имя переменной.
Данные перевода представляют собой вложенный хеш. Подставляемые строки берутся по наиболее детализированному доступному пути в нём. То есть если есть ->1->2->3, берётся ->1->2->3, если нет ->1->2->3, но есть ->2->3, берётся ->2->3, иначе берётся просто ->3.
Соответственно и загружаемые файлы переводов должны содержать просто код, возвращающий хешреф. То есть в простейшем случае — просто хешреф.
VMX::Template — простой и быстрый шаблонизатор, выросший из шаблонизатора phpBB2.
Legacy-версия. Новая стабильная версия входит в Solstice Homepage System (см. ветку svn branches/solstice).
== Программный интерфейс ==
<code perl>
# Конструктор
$template = VMX::Template->new(
root => '.', # каталог с шаблонами
reload => 1, # если 0, шаблоны не будут перечитываться с диска, и вызовов stat() происходить не будет
wrapper => undef, # фильтр, вызываемый перед выдачей результата parse
cache_dir => undef, # необязательный кэш, ускоряющий работу только в случае частых инициализаций интерпретатора
use_utf8 => undef, # шаблоны в UTF-8 и с флагом UTF-8
);
# Выбор файла шаблона:
$template->set_filenames('alias' => 'file-name.tpl');
# Задание кода шаблона «на месте»:
$template->set_filenames('alias' => \ 'код шаблона');
# Загрузка файлов автоматических переводов:
# Каждый такой файл содержит код на языке Perl, возвращающий ссылку на хеш.
# Загрузка происходит с автоматическим пересчитыванием с диска при изменениях.
$template->load_lang(«файл1.pl», «файл2.pl»);
# Загрузка хешей в качестве языковых данных:
$template->load_lang_hashes({ block => { var => 'перевод' } });
# Присвоение переменных корневого уровня:
$template->assign_vars(KEY => «значение»);
# Присвоение переменных блока-цикла в новую итерацию блока:
$template->assign_block_vars(«block», KEY => «значение»);
# Или то же, но без копирования готового хешрефа:
$template->assign_block_vars(«block», { KEY => «значение» });
# Или то же, но в последнюю заданную итерацию блока, а не в новую:
$template->append_block_vars(«block», KEY => «значение»);
# Выполнение шаблона и получение результатов (страницы):
# Выбранные файлы автоматически перезачитываются с диска при изменениях.
# Код кэшируется на 2-х уровнях: на диске в виде perl-кода и в памяти в скомпилированном виде.
$page = $template->parse('alias');
# Очистка сохранённых данных для генерации новой страницы:
$template->clear;
</code>
== Синтаксис ==
Идея синтаксиса шаблонов — быть максимально простым и не поганить HTML-код.
=== Комментарии ===
<pre><!--# Комментарий, не попадающий в результат исполнения #--></pre>
=== Включение (INCLUDE) ===
<pre>
Включение шаблона с именем filename.tpl:
<!-- INCLUDE filename.tpl -->
</pre>
=== Подстановки переменных ===
{переменная} или {переменная->путь} или {переменная/преобразование}
Где переменная — цепочка идентификаторов, разделённая точками. Все, кроме последнего — имена блоков, последний — имя переменной. После имени переменной может идти путь по ней, если она представляет собой хеш или массив. Путь — цепочка идентификаторов или чисел, разделённая стрелками -> Например, {DOMAIN} — подстановка корневой переменной DOMAIN. А {site.url.DOMAIN} — подстановка переменной DOMAIN блока url, вложенного в блок site. А {site.url.CONFIG->rules->0/s} — подстановка первого элемента массива, вложенного в переменную CONFIG блока url, вложенного в блок site, по ключу rules, в HTML-безопасном виде (то есть с преобразованием s, см.ниже).
А преобразование — одно из:
# T — удаление всех HTML тегов из значения
# H — удаление всех HTML тегов из значения, кроме разрешённых в VMX::Common
# i — преобразование значения к целому числу
# s — замена всех символов < > & " ' на HTML сущности < > & " '
# l — перевод значения в нижний регистр
# u — перевод значения в верхний регистр
# q — замена всех символов « ' \ на \» \' \\
# L — замена значения на его контекстный перевод, если таковой имеется
# Lz — замена значения на его контекстный перевод, если таковой имеется, и на пустое значение, если нет
=== Условный вывод (IF) ===
<pre>
<!-- IF[тест] подстановка -->
<!-- END -->
</pre>
Где подстановка — любая допустимая в {фигурных.скобках} подстановка.
Тесты:
# ! — логическое отрицание
# EVEN — истина в случае, если значение — чётное число
# ODD — истина в случае, если значение — нечётное число
# EQ:строка — истина в случае, если значение переменной совпадает с «строка»
# MOD:делитель, остаток — истина в случае, если остаток от деления значения переменной на «делитель» равен «остатку»
Например:
<pre>
<!-- IF! site.url.CONFIG->rules->0/Lz -->
<!-- END -->
</pre>
=== Циклический вывод (BEGIN block) ===
Циклический вывод, начать с итерации start (считаются с нуля), и вывести максимум по итерацию count. Либо обработать все итерации с номерами, дающими остаток от деления на «div» равный «mod». Имя блока состоит из латинских символов, цифр и символа '_' (подчёркивания).
Итак, варианты начала:
<pre>
<!-- BEGIN block -->
<!-- BEGIN block AT start -->
<!-- BEGIN block AT start count -->
<!-- BEGIN block MOD div mod -->
</pre>
Конец блока — всегда <!-- END block -->.
Пример:
<pre>
<!-- BEGIN block -->
<!-- BEGIN inner_block -->
{block.inner_block.VARIABLE}
{inner_block.#}
<!-- END inner_block -->
<!-- END block -->
</pre>
И специальный случай: внутри внутреннего блока {inner_block.#} имеет значением номер текущей итерации внутреннего блока, считающийся с 1. Именно {inner_block.#}, а не {block.inner_block.#}.
=== Автоматические контекстные переводы ===
Они доступны в двух вариантах: %Переводимая строка% и {переменная/L}.
Идея в том, чтобы автоматически заменять строки на другие строки в зависимости от их расположения в файле шаблона (контекста).
Контекст включает в себя:
# путь к файлу шаблона.
# путь к текущему блоку-циклу.
# в случае перевода переменной — имя переменной.
Данные перевода представляют собой вложенный хеш. Подставляемые строки берутся по наиболее детализированному доступному пути в нём. То есть если есть ->1->2->3, берётся ->1->2->3, если нет ->1->2->3, но есть ->2->3, берётся ->2->3, иначе берётся просто ->3.
Соответственно и загружаемые файлы переводов должны содержать просто код, возвращающий хешреф. То есть в простейшем случае — просто хешреф.
