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

• Модификаторы ZoomX
• Блоки ZoomX
• Кэширование
• Файловые элементы
• Создание собственных плагинов

Smarty - мощный и один из самых быстрых PHP шаблонизаторов. Так как он входит в ядро MODX, то выбор пал на него. У него много предустановленных плагинов (встроенные функции, пользовательские функции, встроенные модификаторы). ZoomX также добавляет несколько своих плагинов.

Но кроме обычного синтаксиса с модификаторами, Smarty в ZoomX умеет работать и с синтаксисом в стиле MODX - {'*pagetitle'}, {'%lexicon'}, {'++setting'}, {'~5'}.

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

chunk – вызвать чанк.

Параметр:

• (array) properties - ассоциативный массив параметров.

// Кэшированный чанк
{'chunkName'|chunk:['foo' => 'bar']}
// Некэшированный чанк (Smarty syntax)
{'chunkName'|chunk:['foo' => 'bar'] nocache}

Параметр:

• (mixed) default - значение по-умолчанию в случае отсутствие указанной системной настройки.

//[[++site_name]]
{'site_name'|config}

Параметр:

• (string) media - тип медиа.

{'assets/css/styles.css'|csstohead}
{'assets/css/styles.css'|csstohead:all}

Параметр:

• (string) format - формат даты.

{'publishedod'|resource|dateAgo}  // 3 часа назад
{'17.10.2021 21:00'|dateAgo}  // 17 октября 2021, 21:00
{'17.10.2021 21:00'|dateAgo:'Y-m-d'}  // 2021-10-17

Параметр:

• (array) words - массив из слов. Для русского языка 3 формы, для английского достаточно указать две.
• (bool) include - выводить ли само число.

{4|declension:['день','дня','дней']}  // дня
{4|declension:['день','дня','дней']:true}  // 4 дня

{4|declension:['day','days']:true}  // 4 days

Параметр:

• (string) format - формат даты.

{'publishedod'|resource|fuzzyDate}  // Вчера в 17:15

{'HTML content'|htmltobottom}

{'HTML content'|htmltohead}

Параметр:

• (bool) plaintext - указывает, является ли указанное значение ссылкой на файл (false) или яваскрипт текстом (true).

{'assets/js/scripts.js'|jstobottom}
{'<script>let foo = "bar";</script>'|jstobottom:true}

Параметр:

• (bool) plaintext - указывает, является ли указанное значение ссылкой на файл (false) или яваскрипт текстом (true).

{'assets/js/scripts.js'|jstohead}
{'<script>let foo = "bar";</script>'|jstohead:true}

{'content'|resource|ignore}  // вывод: {'content'|resource}
// тоже самое используя стандартный синтаксис Smarty
{literal}
{'content'|resource}
{/literal}

{if 'group1,group2'|ismember}
    Контент для пользователя, входящего в одну из указанных групп
{/if}

{if ['group1', 'group2']|ismember:true}
    Контент для пользователя, входящего во все указанные группы
{/if}

Параметры:

• (array) params - массив плейсхолдеров.
• (string) language - код языка (если лексикон уже загружен) или строка параметрами в формате "язык:пространство_имён:топик", чтобы предварительно загрузить лексикон. Подробнее в официальной документации MODX.

# Вывести строку для уже загруженного лексикона.
//[[%lang]]
{'lang_key'|lexicon}
// with parameters
{'lang_key'|lexicon:['foo' => 'bar']}
# Загрузить лексикон перед обработкой
lang_key 

Параметр:

• (bool) secure - режим безопасности. Используется для дополнительного кодирования пользовательского контента.

{'[[*pagetitle]] - [[++site_name]]'|modx}

{'[[*pagetitle]] - [[++site_name]]'|modx}

Параметр:

• (string) parser - класс парсера. По-умолчанию, используется указанный в системной настройке zoomx_parser_class.

// Использовать ZoomX парсер, указанный в настройке "zoomx_parser_class".
{'content'|resource|parse}
// Использовать парсер MODX.
{'[[*pagetitle]] - [[++site_name]]'|parse:'modParser'}

//[[+modx.user.id]]
{'modx.user.id'|ph}

Параметры:

• (bool) pre - форматировать вывод. Оборачивает вывод в тег <pre>. По-умолчание, true.
• (bool) esc - экранировать вывод. Использует функцию htmlspecialchars(). По-умолчание, true.

{$array|print}
// вывести необработанную строку
{$array|print:false:false}

Параметр:

• (string) defaultField - альтернативное поле ресурса, которое будет выведено, если начальное поле пустое.

{'pagetitle'|resource}
// значением по-умолчанию является другое поле ресурса.
{'longtitle'|resource:'pagetitle'}
// значение по-умолчанию является строкой.
{'longtitle'|resource|default:'Строка'}
// TV значение
{'tv'|resource}

Параметр:

• (array) properties - массив параметров.
• (int) cache_lifetime - время хранения результата в кэше в секундах.

// Кэшированный сниппет
{'snippetName'|snippet:['foo' => 'bar']}
// Некэшированный сниппет (Smarty syntax)
{'snippetName'|snippet:['foo' => 'bar'] nocache}
// Некэшированный сниппет в набором параметров
{'snippetName@PropSet'|snippet:['foo' => 'bar'] nocache}
// Кэширование на 10 минут. Обязательно вызывать с nocache.
{'snippetName'|snippet:['foo' => 'bar']:600 nocache}

{'tv_name'|tv}

Параметры:

• (string|array) context - контекст. С версии 2.0 можно указать массив со всеми перечисленными параметрами.
• (array) args - массив агрументов URL.
• (integer|string) scheme - схема.
• (array) options - массив опций.

{5|url}
{5|url:'web':['foo' => 'bar']:-1}
# С версии 2.0
{5|url:['scheme' => 'full']}

Параметр:

• (mixed) default - значение по-умолчанию, если указанное поле пользователя пустое (null).

{'username'|user}
{'fullname'|user:'username'}

Блоки

{auth nocache}
Контент для аутентифицированных пользователей.
{/auth}

Проверка для указанного контекста.

{auth context="mgr" nocache}
Контент для аутентифицированных в админке пользователей.
{/auth}

{guest nocache}
Контент для неаутентифицированных пользователей.
{/guest}

{modx nocache}
<a href="[[~[[*id]]]]">[[*pagetitle]]</a>
{/modx}

Параметр:

• (string) parser - класс парсера. Пользовательский класс должен быть предварительно загружен.

{parse nocache}
<a href="[[~[[*id]]]]">[[*pagetitle]]</a>
{/parse}

// Можно указать любой другой
{parse parser="pdoParser" nocache}
<a href="[[~[[*id]]]]">[[*pagetitle]]</a>
{/parse}

Кэширование

В Smarty заложены мощные возможности кэширования. Вы можете управлять кэшированием отдельных тегов также, как это делается в MODX с помощью знака !, но несколько иначе - используя специальный аттрибут nocache или одноимённый блок.

// Аттрибут
{'username'|user nocache}
// Блок
{nocache}
{'username'|user}
{'email'|user}
{/nocache}

Для подшаблонов (чанков по-нашему) возможностей больше. Для них можно указать даже время кэширования.

{include file="chunks/header.tpl" cache_lifetime=300}

Можно указать разные кэши одного подшаблона для разных условий

// Разные кэши для разных категорий
{include file="header.tpl" cache_id="cache_key_{$modx->resource->parent}" title="{$modx->resource->pagetitle}"}

Для сниппетов также можно указывать определённое время кэширования.

// Кэширование на 10 минут.
{'snippet'|snippet:['foo' => 'bar', 'tpl' => 'chunk.tpl']:600 nocache}
{run name='snippet' params=['foo' => 'bar', 'tpl' => '@INLINE {$pagetitle}'] cache_lifetime=600 nocache}

Управлять кэшированием можно с помощью системной настройки zoomx_caching. При разработке советую её отключать. Также кэш не будет создаваться для документов, у которых снят чекбокс "кэшируемый".

Файловые элементы

Понятие файловых элементов - исключительно модыксовское. В других системах подобных сущностей нет. Многие знакомы с ними по pdoTools. В ZoomX также добавлен подобный функционал.

Начнём с того, что для Smarty все шаблоны и подшаблоны (или чанки по модыксовски) являются файловыми. Поэтому достаточно в шаблоне страницы написать include.

{include "имя_файла_шаблона"}

Но что делать, если нужно использовать чанк в сниппете или передать в параметре? Для этого предусмотрен уже привычный по pdoTools механизм.

// Для передачи в параметрах сниппета на странице
{'mySnippet|snippet:['tpl' => '@FILE profile.tpl']'}
// API для использования в сниппете
$content = zoomx()->getChunk('@FILE profile.tpl', $user->toArray());

В шаблоне также можно использовать вариант с байндингом @FILE.

{'@FILE имя_файла_шаблона.tpl'|chunk}

Расширение .tpl можно не указывать — к имени файла будет автоматически добавлено расширение, указанное в системной настройке zoomx_template_extension.

Для файловых сниппетов также создана аналогичная чанкам инструкция - run.

// Кэшированный сниппет (если включено кэширование шаблонов Smarty).
{run file='file_snippet.php' params=['foo' => 'bar', 'tpl' => '@INLINE {$pagetitle}']}
// Кэширование данных на 10 минут. Сниппет должен вызываться некэшированным (с nocache).
{run file='file_snippet.php' params=['foo' => 'bar', 'tpl' => '@INLINE {$pagetitle}'] cache_lifetime=600 nocache}

Но доступен и синтаксис pdoTools.

// "pdoTools like" - через использование байндигна @FILE 
{'@FILE file_snippet'|snippet:['foo' => 'bar', 'tpl' => '@FILE file_chunk.tpl']}
// Использование объекта $zoomx (появляется при включении настройки "zoomx_include_modx") с сохранением в кэше на 10 минут.
{$zoomx->runFileSnippet('file_snippet', ['foo' => 'bar', 'tpl' => 'modx_chunk'], 600) }

Расширение .php можно не указывать — оно добавится автоматически.

Создание собственных плагинов

Для большей части задач можно использовать непосредственно функции PHP. Например, вместо {$string|trim} можно вызвать {trim($string)}. Если данных возможностей не хватает, то можно создать собственный модификатор или функцию. Сделать это можно двумя способами:

1. Создать файл плагина следуя инструкции и положить его в папку smarty/custom_plugins/ в ядре компонента ZoomX. Он будет подключён автоматически. Если вы создали свою собственную папку плагинов, то не забудьте указать её в системной настройке smarty_custom_plugin_dir.
2. Динамически подключить во время загрузки MODX с помощью метода registerPlugin(). Для этого необходимо создать плагин на событие OnHandleRequest и в нём подключить нужный функционал:

   <?php
   // OnHandleRequest
   
   function print_current_date($params, $smarty)
   {
     if(empty($params["format"])) {
       $format = "%b %e, %Y";
     } else {
       $format = $params["format"];
     }
     return strftime($format,time());
   }
   
   // Подключение функции
   parserx()->registerPlugin("function","date_now", "print_current_date");
   // Пробросить PHP функцию ucfirst в виде модификатора.
   $smarty->registerPlugin("modifier","ucfirst", "ucfirst");
   

   В шаблоне теперь доступна функция date_now и модификатор ucfirst.

   {date_now}
   {* Или с форматированием *}
   {date_now format="%Y/%m/%d"}
   
   {$name|ucfirst}