Описание шаблонизатора

В CMS Boxcode используется шаблонизатор собственной разработки. Но он похож на шаблонизатор Smarty, только по проще и более удобнее.
Шаблонизатор поддерживает обычные для php конструкции, все конструкции должны заключаться в разделители шаблонизатора:

- Левая фигурная скобка ({) - левый разделитель шаблонизатора;
- Правая фигурная скобка (}) - правый разделитель шаблонизатора;
- Левая фигурная скобка со звездочкой ({*) - левый разделитель комментария шаблонизатора;
- Правая фигурная скобка со звездочкой (*}) - правый разделитель комментария шаблонизатора.

К примеру

{$var1}
{* содержимое комментария *}

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

Подключение и использование шаблонизатора

В CMS Boxcode шаблонизатор dmk расположен по адресу

/addapplication/dmk

Для работы шаблонизатора нужно подключить файл dmk.class.php и создать объект шаблонизатора:

include("путь_к_папке_dmk/dmk.class.php");
$tpl = new DmkTemplate;

Далее нужно указать папки, которые нужны будут шаблонизатору.

Задаем папку с скомпилированными шаблонами

$tpl->compile_dir = "путь_к_папке/templates_c/";

Задаем папку конфигурации. На данный момент не используется, зарезервирована для дальнейших разработок

$tpl->config_dir = "путь_к_папке/configs/";

Задаем папку кэша

$tpl->cache_dir = "путь_к_папке/templates_cache/";

Задаем путь к папке с шаблонами

$tpl->template_dir = "путь_к_папке/templates/";

Обычно в шаблон передаются какие-либо данные, к примеру, заголовок страницы, текст страницы (статьи), и т.п. Их нужно подготовить до использования шаблона. Передавать данные нужно в виде массива, элементы которого должны быть в виде ключ => значение. Причем ключ элемента массива будет в шаблоне переменной, поэтому должен состоять из тех символов, что допускаются для переменных в php (без символа $).

Например, возьмем переменную $mas_perem и будем добавлять в неё нужные данные.

$mas_perem = array();

$mas_perem["my_var1"] = "Это значение моей первой переменной my_var1 в шаблоне!";
$mas_perem["title_article"] = "Это заголовок статьи!";
$mas_perem["text_article"] = "Это текст статьи!";

Далее передаем шаблонизатору данные

$tpl->assign($mas_perem);

Теперь можно использовать шаблон:

$t = $tpl->fetch("test_hablon.html");

Метод fetch() возвращает результат, не выводя его браузеру. Поэтому нужно вывести этот текст:

echo ($t);

Можно сразу отдавать результат браузеру, для этого нужно использовать метод display("имя_шаблона"), например

$tpl->display("test_hablon.html");

В целом будет такой код:

include("путь_к_папке_dmk/dmk.class.php");
$tpl = new DmkTemplate;

$tpl->compile_dir = "путь_к_папке/templates_c/";
$tpl->config_dir = "путь_к_папке/configs/";
$tpl->cache_dir = "путь_к_папке/templates_cache/";

$tpl->template_dir = "путь_к_папке/templates/";

$mas_perem = array();

$mas_perem["my_var1"] = "Это значение моей первой переменной my_var1 в шаблоне!";
$mas_perem["title_article"] = "Это заголовок статьи!";
$mas_perem["text_article"] = "Это текст статьи!";

$tpl->assign($mas_perem);

$t = $tpl->fetch("test_hablon.html");
echo ($t);

Код шаблона test_hablon.html:

<h1>{$title_article}</h1>
<div>Текст статьи</div>
<div>{$text_article}</div>
<div>Значение переменной my_var1: {$my_var1}</div>

Тестовые шаблоны

В шаблонизаторе есть тестовые файлы, расположены они в папке /test.

Кэширование в шаблонизаторе

Шаблонизатор может кэшировать результат выполнения шаблона. Кэшированием управляет свойство caching объекта шаблонизатора. Данному свойству, в случае необходимости, нужно передать одно из значений:
0 - кэширование отключено;
1 - использовать кэширование только для следующего шаблона;
2 - использовать кэширование для всех последующих шаблонов.

Время действия кэша определяет свойство cache_lifetime объекта шаблонизатора. Нужно указать время действия кэша в секундах или указать значение "-1", если ограничения по времени действия кэша нет.

Для проверки кэша нужно использовать метод $tpl->is_cached("имя_шаблона")

include("путь_к_папке_dmk/dmk.class.php");
$tpl = new DmkTemplate;

$tpl->compile_dir = "путь_к_папке/templates_c/";
$tpl->config_dir = "путь_к_папке/configs/";
$tpl->cache_dir = "путь_к_папке/templates_cache/";

$tpl->template_dir = "путь_к_папке/templates/";

$tpl->caching = 1;
$tpl->cache_lifetime = 60;// 60 секунд - 1 минута

if ( !$tpl->is_cached("test_hablon.html") )
  {
    $mas_perem = array();
    $mas_perem["my_var1"] = "Это значение моей первой переменной my_var1 в шаблоне!";
    $tpl->assign($mas_perem);
  }

$t = $tpl->fetch("test_hablon.html");
echo ($t);

В приведенном выше примере показывается обычная работа с кэшем, что не всегда удобно. А точнее кэширование по времени не всегда хорошо, если данные (контент) могут поменяться в любой момент времени, а отображаться на сайте должна только актуальная информация. В шаблонизаторе dmk есть возможность обновить кэш другим способом. Нужно в методе $tpl->fetch() или $tpl->display() указать второй параметр равный true. К примеру:

include("путь_к_папке_dmk/dmk.class.php");
$tpl = new DmkTemplate;

$tpl->compile_dir = "путь_к_папке/templates_c/";
$tpl->config_dir = "путь_к_папке/configs/";
$tpl->cache_dir = "путь_к_папке/templates_cache/";

$tpl->template_dir = "путь_к_папке/templates/";

$tpl->caching = 1;
$tpl->cache_lifetime = -1;//кэш без ограничения по времени

$on_update_cache = false или true;//проверяем, нужно ли обновить кэш или нет.
//Если нужно, то пишем true, если не нужно - то false

$mas_perem = array();

$my_var1 = "";
$title_article = "";
$text_article = "";

if ( $on_update_cache )
  {
   //кэш нужно обновить, поэтому определяем нужные данные
   $my_var1 = "Это значение моей первой переменной my_var1 в шаблоне!";
   $title_article = "Это заголовок статьи!";
   $text_article = "Это текст статьи!";
  }

$mas_perem["my_var1"] = $my_var1;
$mas_perem["title_article"] = $title_article;
$mas_perem["text_article"] = $text_article;

$tpl->assign($mas_perem);

$t = $tpl->fetch("test_hablon.html",$on_update_cache);
echo ($t);

Конструкции шаблонизатора

Рассмотрим конструкции, которые можно использовать в шаблонизаторе.

Комментарии.

Комментарии пишутся следующим образом:

{* тут комментарий. *}

Содержимое комментария не будет в скомпилированном шаблоне и, соответственно, не будет в коде страницы (например, при просмотре кода страницы в браузере). Комментарии нужны для примечаний в самих шаблонах.

Константы шаблонизатора

В шаблонизаторе есть константы ldelim и rdelim, которые выводят, соответственно, левый разделитель шаблонизатора (правая фигурная скобка "{") и правый разделитель шаблонизатора (левая фигурная скобка "}"). К примеру

{ldelim}этот текст будет в фигурных кавычках{rdelim}

Результатом будет текст

Так как в шаблоне разделители нельзя использовать вне тегов шаблонизатора, а поставить правую и левую фигурные скобки в тексте нужно будет, то нужно использовать эти константы. Также можно использовать блоки literal (о блоках literal будет написано ниже).
Еще один пример:

<script type='text/javascript'>
function test_function(a)
  {ldelim}
    alert (a);
  {rdelim}

test_function (123);
</script>

Переменные и массивы.

Для вывода переменной нужно написать следующий код

{$var2}

Можно выводить элементы массивов

{$masv["key1"]}

Переменные и массивы можно передавать шаблонам (об этом будет написано дальше), можно создавать переменные.

{? $myvar1 = "Тут значение переменной"}

В этом коде создается переменная $myvar1. Обратите внимание на символ «вопросительный знак» после открывающего тега шаблонизатора. Для вывода значения созданной переменной нужно написать уже известный нам код

{$myvar1}

Аналогичным образом создаются и массивы:

{?$my_mas = array ( "key1" => "первый элемент массива", "key2" => "второй элемент массива" )}

Для вывода значения элемента массива, к примеру, key2, нужно написать

{$my_mas["key2"]}

Условный оператор

Условия записываются следующим образом

{if условие}
...
{elseif условие}
...
{else}
...
{/if}

Пример использования условного оператора

{if $var1 == 234}
Переменная $var1 содержит значение 234
{/if}

Можно использовать условия с else, как в php:

{if $var1 == 234}
Переменная $var1 содержит значение 234
{else}
Переменная $var1 не содержит значение 234
{/if}

Также можно использовать elseif:

{if $var1 == 234}
Переменная $var1 содержит значение 234
{elseif $var1 == 345}
Переменная $var1 содержит значение 345
{else}
Переменная $var1 не содержит значения 234 и 345
{/if}

Цикл foreach

Оператор foreach нужен для перебора массивов. Структура следующая:

{foreach from = $mas_elem key = $key_elem value = $value_elem}
...
{foreachelse}
...
{/foreach}

В атрибуте from указывается массив, который будет в цикле перебираться. В атрибуте key указывается переменная, которая будет содержать ключ элемента массива. В атрибуте value указывается переменная, которая будет содержать значение элемента массива.

{?$mas_color = array("red"=>"#d00","blue"=>"#00d","green"=>"#0d0")}
<div>
Просмотрим значения массива в виде: ключ -> значение
{foreach from = $mas_color key = $name_color value = $one_color}
<div>
{$name_color} -> <span style="color:{$one_color};">{$one_color}</span>
</div>
{/foreach}
</div>

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

{?$mas_color = array("синий","красный","зеленый")}
<div>
{foreach from = $mas_color value = $one_color}
<p>{$one_color}</p>
{/foreach}
</div>

Блок foreachelse будет выполнен, если в массиве нет элементов. Необязательно указывать блок foreachelse.

{?$mas_color = array()}
{foreach from = $mas_color value = $one_color}
<p>{$one_color}</p>
{foreachelse}
<p>В массиве нет элементов.</p>
{/foreach}

Цикл for

Структура цикла for следующая

{for value = $name_var loop = N start = NN step = NNN}
...
{/for}

В атрибуте value указывается имя переменной для цикла. В атрибуте loop указывается максимальное возможное число для цикла. В атрибуте start указывается начальное значение цикла. Этот атрибут не обязательный. Если атрибут start не указан, то начальное значение будет равно 0. В атрибуте step задается шаг цикла. Атрибут step также не обязательный, если он не указан, то шаг цикла будет равен 1. Например:

{for value = $i loop = 20 start = 10 step = 2}
<p>число {$i}</p>
{/for}

Можно так написать

{for value = $i loop = 10}
<p>число {$i}</p>
{/for}

Цикл while

Структура цикла while следующая

{while условие}
...
{/while}

Пример цикла while:

{?$n = 5}
{while $n < 10}
<p>переменная $n содержит значение {$n}</p>
{?$n++}
{/while}

Оператор switch

Оператор switch шаблонизатора идентичен оператору switch в php. Структура оператора switch следующая

{switch выражение}
{case значение}
...
{default}
...
{/switch}

Пример использования:

<p>
{?$fff = "яблоко"}
{switch $fff}
{case "яблоко"}
В переменной $fff содержится яблоко
{break}
{case "груша"}
В переменной $fff содержится груша
{break}
{default}
В переменной $fff нет фруктов
{/switch}
</p>

По аналогии оператора в php, нужно использовать конструкцию break, если есть такая необходимость.

Оператор include

Для подключения шаблона в шаблон нужно использовать конструкцию include. Синтаксис следующий

{include file="имя_файла"}

Атрибуту file нужно передать имя подключаемого шаблона. Например два файла в одном каталоге:
Файл main_tpl.html

{$masFruit = array("яблоко","груша","апельсин")}
{include file="add_tpl.html"}

Файл add_tpl.html

{foreach from = $masFruit value = $one_fruit}
<p>{$one_fruit}</p>
{/foreach}

Оператор literal

Блок literal позволяет указать часть текста/кода который не нежно компилировать - текст между открывающим и закрывающим тегами literal не будет обрабатываться шаблонизатором и вставлен в скомпилированный шаблон без изменений. Такая возможность может понадобиться, если в файле есть javascript код, css-инструкции или какой-либо другой код содержащий большое количество фигурных скобок. Например:

{literal}
<script type="text/javascript">
function check_param(v)
{
 if ( v )
  {
   alert ("Значение задано!");
  }
 else
   {
     alert ("Значение не задано!");
   }
}

check_param(10);

</script>
{/literal}

Модификаторы

Модификаторы упрощают обработку различных данных. Модификаторы могут применяться к переменным, к результатам функции и строкам. Модификатор указывается следующим образом: после нужного значения прописывается вертикальная черта (|) и далее сам модификатор. К примеру:

{?$more_text = "Тут какой-либо текст"}
{$more_text|codehtml}
{"Тут обычный текст"|codehtml}
{trim($more_text)|codehtml}

Если модифицировать нужно сложное (составное) выражение, к примеру, состоящее из строковых значений и/или переменных, то нужно использовать скобки, например:

{?$more_text1 = "Тут какой-либо текст."}
{?$more_text2 = "Тут еще какой-либо текст."}
{($more_text1." ".trim($more_text2))|codehtml}

Модификатор codehtml

Модификатор codehtml нужен для преобразования определенных символов в мнемоники HTML. Преобразуются следующие символы (выполнение данного модификатора аналогично выполнению функции в php htmlspecialchars($str,ENT_QUOTES)):
- амперсанд (&) преобразуется в "&amp;"
- двойная кавычка (") преобразуется в "&quot;"
- одинарная кавычка (') преобразуется в "&#039;"
- знак «меньше чем» (<) преобразуется в "&lt;"
- знак «больше чем» (>) преобразуется в "&gt;"

Данный модификатор может использоваться, к примеру, для кодирования значений полей формы:

{?$value_pf='Текст поля формы, содержащий различные символы, в том числе двойные и одинарные кавычки " \' и знаки > и <.'}
<div>
<input type="text" value="{$value_pf|codehtml}" name="name_article">
</div>
<div>
<textarea name="test_pf">{($value_pf." А также закрывающий тег много строчного текстового поля - </textarea>")|codehtml}</textarea>
</div>

Если значение поля формы будет содержать кавычки (одинарные или двойные), и символы < и >, то форма (поля формы) будет правильно отображаться при использовании модификатора codehtml.

Модификатор rawurlencode

Модификатор rawurlencode выполняет тоже самое действие, что и функция в php rawurlencode(), то есть преобразует текст так, чтобы его можно было использовать в URL-адресах. К примеру, можно использовать для кодирования кириллических символов в строке, с последующим использованием в URL-адресе:

<a href="?text={'это обычный текст'|rawurlencode}">ссылка</a>

Модификатор urlencode

Модификатор urlencode выполняет тоже самое действие, что и функция в php urlencode(), то есть преобразует текст так, чтобы его можно было использовать в URL-адресах. К примеру, можно использовать для кодирования кириллических символов в строке, с последующим использованием в URL-адресе:

<a href="?text={'это обычный текст'|urlencode}">ссылка</a>

Файлы

Вы можете скачать шаблонизатор для ознакомления с его работой.

В шаблонизаторе есть тестовые файлы в папке /test.