MODX fenom — документация и примеры

Сегодня документация по шаблонизатору Fenom + реальные примеры из практики (шпаргалки).

Fenom — это быстрый и достаточно удобный шаблонизатор, по синтаксису схож со Smarty. Это отличная альтернатива стандартному синтаксису MODX. С его помощью можно ускорить разработку сайта, сократить количество чанков, время на выполнение запросов, использовать циклы прям в шаблонах/чанках и многое другое.

Fenom в MODX появился в 2015 году, с выходом обновления pdoTools 2.0. После установки pdoTools, парсер Fenom уже активен, но только в чанках.

Нет особого смысла использовать fenom с modParser одновременно (используйте что то одно).

Полноценное включение Fenom

На обработку шаблонизатором влияют следующие системные настройки:

• pdotools_fenom_default — включает обработку через Fenom чанков pdoTools. Включено по умолчанию.
• pdotools_fenom_parser — включает обработку шаблонизатором всех страниц сайта. То есть, не только чанков, но и шаблонов. Есть один нюанс — шаблонизатор может неверно реагировать на фигурные скобочки, которые в MODX очень любят — решение проблем ниже.
• pdotools_fenom_php — включает поддержку PHP функций в шаблонизаторе. Очень опасная функция, так как любой менеджер получит доступ к PHP прямо из чанка.
• pdotools_fenom_modx — добавляет системные переменные {$modx} и {$pdoTools} в шаблоны Fenom. Тоже очень опасно — любой менеджер может управлять объектами MODX из чанков.
• pdotools_fenom_options — JSON строка с массивом настроек согласно официальной документации. Например: {"auto_escape":true,"force_include":true}
• pdotools_fenom_cache — кэширование скопмилированных шаблонов. Имеет смысл только для сложных чанков на рабочих сайтах, по умолчанию отключено.

Синтаксис

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

Все переменные от сниппетов передаются в чанк как есть, поэтому переписывать старые чанки на новый синтаксис — сплошное удовольствие.

MODX	Fenom
[[+id]]	{$id}
[[+id:default=`test`]]	{$id ?: 'test'}
[[+id:is=``:then=`test`:else=`[[+pagetitle]]`]]	{$id == '' ? 'test' : $pagetitle}

Для использования более сложных сущностей, в pdoParser предусмотрена служебная переменная {$_modx}, которая даёт безопасный доступ к некоторым переменным и методам системы.

MODX	Fenom
[[*id]]	{$_modx->resource.id}
[[*tv_param]]	{$_modx->resource.tv_param}
[[%lexicon]]	{$_modx->lexicon('lexicon')}
[[~15]]	{$_modx->makeUrl(15)}
[[~[[*id]]]]	{$_modx->makeUrl($_modx->resource.id)}
[[++system_setting]]	{$_modx->config.system_setting}

Помимо этого вам доступны переменные: {$_modx->config} — системные настройки

{$_modx->config.site_name}
{$_modx->config.emailsender}
{$_modx->config['site_url']}
{$_modx->config['any_system_setting']}

{$_modx->user} — массив текущего пользователя. Если он авторизован, то добавляются и данные из профиля:

{if $_modx->user.id > 0}
    Привет, {$_modx->user.fullname}!
{else}
    Вам нужно авторизоваться.
{/if}

{$_modx->context} — массив с текущим контекстом

Вы находитесь в контексте {$_modx->context.key}

{$_modx->resource} — массив с текущим ресурсом, это вы уже видели в примерах выше

{$_modx->resource.id}
{$_modx->resource.pagetitle}
{$_modx->makeUrl($_modx->resource.id)}

{$_modx->lexicon} — объект (не массив!) modLexicon, который можно использовать для загрузки произвольных словарей:

{$_modx->lexicon->load('ms2gallery:default')}
Проверка словарей ms2Gallery: {$_modx->lexicon('ms2gallery_err_gallery_exists')}

За вывод записей отвечает отдельная функция {$_modx->lexicon()}.

Теги fastField

Вывод тегов fastField с помощью Fenom, на примере вывода заголовка:

{15 | resource : 'pagetitle'}

Где 15 id нужного ресурса, pagetitle — необходимое поле для вывода.

Плейсхолдеры с точкой или тире

Во многих местах MODX используются плейсхолдеры, которые нельзя указывать в Fenom, так как они не сосуществуют правилам наименования переменных PHP. Например, плейсхолдеры с точкой (MODX обычно выставляет так данные массивов) или с тире (ТВ параметры).

Для доступа к этим плейсхолдерам нужно использовать вторую служебную переменную — {$_pls}:

<!-- Вывод сразу -->
{$_pls['tag.subtag']}

<!-- Или через переменную -->
{var $tv_name = $_pls['tv-name']}
{$tv_name}

Если плейсхолдер был выставлен в глобальный массив modX::placeholders, то его нужно получать вот так:

{var $tag_sub_tag = $_modx->getPlaceholder('tag.sub_tag')}
{$tag_sub_tag}

{$_modx->getPlaceholder('tv_name')}

При указании неправильных переменных ваш шаблон не будет скомпилирован и вы получите запись об этом в системном журнале.

Заполнение плейсхолдеров

Fenom работает за один проход, то есть, не является рекурсивным, как родной парсер MODX.

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

Например: необходимо получить значение плейсхолдера {$mse2_query} (Поисковой запрос) в форме, но форму поиска отобразить над результатами. Для этого необходимо выполнить сниппет mSearch2 и передать результаты плейсхолдеру, например searchResults:

{'!pdoPage' | snippet : [
    'element' => 'mSearch2',
    'toPlaceholder' => 'searchResults'
]}

Далее вызвать сниппет формы поиска, где парсер Fenom подставит значение плейсхолдера {$mse2_query}:

{'!mSearchForm' | snippet}

После чего вывести результаты работы сниппета mSearch2:

{'searchResults' | placeholder}

Если сниппет не умеет сохранять результаты своей работы с плейсхолдер, вы можете присваивать их переменной Fenom:

{var $date = 'dateAgo' | snippet : ['input' => '2016-09-10 12:55:35']}

...

Ваша дата: {$date}.

Очень похоже на логику работы обычного скрипта.

Вывод сниппетов и чанков

Переменная {$_modx} на самом деле представляет собой простой и безопасный класс microMODX

Поэтому сниппеты и чанки вызываются так:

{$_modx->runSnippet('!pdoPage@PropertySet', [
    'parents' => 0,
    'element' => 'pdoResources',
    'where' => ['isfolder' => 1],
    'showLog' => 1,
])}
{$_modx->getPlaceholder('page.total')}
{$_modx->getPlaceholder('page.nav')}

Как видите, синтаксис практически полностью повторяет PHP, что открывает новые возможности. Например, можно указывать массивы, вместо JSON строк.

По умолчанию все сниппеты вызываются кэшированными, но вы можете добавить ! перед именем — как в тегах MODX.

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

{$_modx->getChunk('MyChunk@PropertySet')}

{$_modx->parseChunk('MyChunk', [
    'pl1' => 'placeholder1',
    'pl2' => 'placeholder2',
])}

{$_modx->getChunk('@TEMPLATE Base Template')}

{$_modx->getChunk('@INLINE
    Имя сайта: {$_modx->config.site_name}
')}

{$_modx->getChunk(
    '@INLINE Передача перемнной в чанк: {$var}',
    ['var' => 'Тест']
)}

{$_modx->getChunk('
    @INLINE Передача переменной в вызов сниппета:
    {$_modx->runSnippet("pdoResources", [
        "parents" => $parents
    ])}
    Всего результатов: {$_modx->getPlaceholder("total")}
    ',
    ['parents' => 0]
)}

Примеры выше немного безумные, но вполне себе работают.

Управление кэшированием

В объекте {$_modx} доступен сервиc modX::cacheManager, который позволяет вам устанавливать произвольное время кэширование вызываемых сниппетов:

{if !$snippet = $_modx->cacheManager->get('cache_key')}
    {set $snippet = $_modx->runSnippet('!pdoResources', [
        'parents' => 0,
        'tpl' => '@INLINE {$id} - {$pagetitle}',
        'showLog' => 1,
    ])}
    {set $null = $_modx->cacheManager->set('cache_key', $snippet, 1800)}
{/if}

{$snippet}

Посмотреть этот кэш можно в /core/cache/default/, в примере он сохраняется на 30 минут.

set $null = ... нужен, чтобы cacheManager->set не вывел 1 (т.е. true) на страницу.

А еще вы можете запускать системные процессоры (если прав хватит):

{$_modx->runProcessor('resource/update', [
    'id' => 10,
    'alias' => 'test',
    'context_key' => 'web',
])}

Проверка авторизации

Так как объекта с пользователем в {$_modx} нет, методы проверки авторизации и прав доступа вынесены непосредственно в класс:

{$_modx->isAuthenticated()}
{$_modx->hasSessionContext('web')}
{$_modx->hasPermission('load')}

Вывод информации о скорости работы

С версии 2.1.4 вы можете использовать метод {$_modx->getInfo(string, bool, string)} для получения данных о скорости работы системы в данный момент. У него три параметра:

• string — вывести определённый ключ из массива данных (пусто, по умолчанию)
• bool — вывести все данные как строку, а не массив (true, по умолчанию)
• string — оформить строки в чанк, можно использовать любые типа чанков pdoTools (@INLINE {$key}: ${value}).

Вывод по умолчанию (строка со всеми данными):

{$_modx->getInfo()}
// queries: 39
// totalTime: 0.1067 s
// queryTime: 0.0069 s
// phpTime: 0.0998 s
// source: database

Вывод конкретного значения:

{$_modx->getInfo('totalTime')}
// 0.1067 s
{$_modx->getInfo('source')}
// database

Оформление строк в свой чанк:

{$_modx->getInfo('', true, '@INLINE {$key} => {$value}')}
// queries => 39
// totalTime => 0.1155 s
// queryTime => 0.0091 s
// phpTime => 0.1064 s
// source => database

Вы можете даже добавить строки в лексикон pdoTools (или любой другой) и выводить ключи через него:

{$_modx->lexicon->load('pdotools:default')}
{$_modx->getInfo('', true, '@INLINE {$_modx->lexicon("pdotools_" ~ $key)} => {$value}')}

Или оформить без лексиконов, произвольно. Просто присваиваем переменной массив данных и выводим его ключи:

{set $info = $_modx->getInfo('', false)}
Время работы: {$info.totalTime}
Время запросов: {$info.totalTime}
Количество запросов: {$info.queries}
Источник: {$info.source}

Вывод информации только пользователям, которые авторизованы в менеджере:

{if $_modx->hasSessionContext('mgr')}
    {$_modx->getInfo()}
{/if}

Остальные методы

Эти методы должны быть знакомы всем разработчикам MODX, поэтому просто покажу их на примерах:

{$_modx->regClientCss('/assets/css/style.css')}
{$_modx->regClientScript('/assets/css/script.js')}

{$_modx->sendForward(10)}
{$_modx->sendRedirect('http://yandex.ru')}

{$_modx->setPlaceholder('key', 'value')}
{$_modx->getPlaceholder('key')}

{if $res = $_modx->findResource('url-to/doc/')}
    {$_modx->sendRedirect( $_modx->makeUrl($res) )}
{/if}

Вы даже можете получать и выводить ресурсы без сниппетов:

{var $resources = $_modx->getResources(
    ['published' => 1, 'deleted' => 0],
    ['sortby' => 'id', 'sortdir' => 'ASC', 'limit' => 50]
)}
{foreach $resources as $resource}
    {$_modx->getChunk('@INLINE <p>{$id} {$pagetitle}</p>', $resource)}
{/foreach}

Переодически в класс добавляются новые методы, так что смотрите их в самом файле

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

Fenom умеет использовать сниппеты MODX в качестве модификаторов. Например, установив компонент dateAgo, вы сразу можете исопльзовать его для вывода дат:

[[!pdoResources?
    &parents=`0`
    &tpl=`@INLINE <p>{$id} - {$pagetitle} {$createdon | dateago}</p>`
]]

Также работает и Jevix, и любые другие сниппеты-фильтры MODX, которые принимают параметры $input и $options, согласно документации.

[[!pdoResources?
    &parents=`0`
    &includeContent=`1`
    &tpl=`@INLINE <p>{$id} - {$pagetitle} {$createdon | dateago} {$content | jevix}</p>`
]]

Модификаторы могут работать последовательно:

[[!pdoResources?
    &parents=`0`
    &includeContent=`1`
    &tpl=`@INLINE <p>{$id} - {$pagetitle} {$createdon | date_format:"%Y-%m-%d %H:%M:%S" | dateago}</p>`
]]

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

Встроенные модификаторы

На данный момент вы можете использовать следующие модификаторы в Fenom (в скобках указаны равноценные синонимы):

• date_format — форматирование даты через функцию strftime. Если переменная пуста, будет получено текущее время.

{'2015-01-10 12:45' | date_format : '%d.%m.%Y'} // 10.01.2015
{'' | date_format : '%Y'} // текущий год

• date — форматирование даты через функцию date. Если переменная пуста, будет получено текущее время.

{'2015-01-10 12:45' | date : 'd.m.Y'} // 10.01.2015
{'' | date : 'Y'} // текущий год

• escape (e) — экранирование переменной. Первым параметром принимает режим работы, вторым — кодировку.

{'<p>value</p>' | escape : 'html' : 'utf-8'} // &lt;p&gt;value&lt;/p&gt;
{'http://site.com/?key=value' | escape : 'url'} // http%3A%2F%2Fsite.com%2F%3Fkey%3Dvalue
{['key' => 'value'] | escape : 'js'}

• unescape — декодирование переменной

{'&lt;p&gt;value&lt;/p&gt;' | unescape : 'html' : 'utf-8'} // <p>value</p>
{'http%3A%2F%2Fsite.com%2F%3Fkey%3Dvalue' | unescape : 'url'} // http://site.com/?key=value
{'{"key":"value"}' | unescape : 'js'}

• truncate (ellipsis) — Обрезает переменную до определенной длинны, по умолчанию — 80 символов. В качестве необязательного второго параметра, вы можете передать строку текста, которая будет отображатся в конце обрезанной переменной. Символы этой строки не включаются в общую длинну обрезаемой строки. По умолчанию, truncate попытается обрезать строку в промежутке между словами. Если вы хотите обрезать строку строго на указаной длинне, передайте в третий необязательный параметр значение true.

{var $str = 'very very long string'}
{$str | truncate : 10 : ' read more...'} // very very read more...
{$str | truncate : 5 : ' ... ' : true : true} // very ... string

• strip — убирает пробелы в начале и конце текста. Если указан дополнительный параметр, то убираются и все повторяющиеся пробелы в тексте.

{'text     with      spaces' | strip : true} // text with spaces

• length (len, strlen) — выводит длину переменной. Может принимать строку или массив.

{'var' | length} // 3
{['key' => 'value'] | len} // 1

• in — оператор проверки наличия подстроки в строке или значения в массиве

{var $key = '10'}
// строка
{if $key | in : 'У меня 10 яблок'}
    Ключ найден
{/if}
// массив + тернарный оператор
{$key | in : [1, 3, 42] ? 'ключ найден' : 'не найден'}

• iterable — проверка возможности перебора переменной

{var $array = ['key' => 'value']}
{if $array | iterable}
    {foreach $array as $key => $value}
        <p>{$key} is {$value}</p>
    {/foreach}
{/if}

• replace — заменяет все вхождения строки поиска на строку замены

{$fruits | replace : "pear" : "orange"} // все pear будут заменены на orange

• ereplace — выполняет поиск и замену по регулярному выражению.

{'April 15, 2014' | ereplace : '/(\w+) (\d+), (\d+)/i' : '${1}1, $3'} // April1, 2014

• match — проверят совпадение строки с шаблоном, через функцию fnmatch. Можно использовать простые маски:

{if $color | match : '*gr[ae]y'}
  какой-то оттенок серого
{/if}

• ematch — выполняет проверку на соответствие регулярному выражению

{if $color | ematch : '/^(.*?)gr[ae]y$/i'}
  какой-то оттенок серого
{/if}

• split — разбивает строку и возвращает массив, используя первый параметр в качестве разделителя (по умолчанию ,).

{var $fruits = 'banana,apple,pear' | split} // ["banana", "apple", "pear"]
{var $fruits = 'banana,apple,pear' | split : ',apple,'} // ["banana", "pear"]

• esplit разбивает строку по регулярному выражению в первом параметре (по умолчанию /,\s*/).

{var $fruits = 'banana, apple, pear' | esplit} // ["banana", "apple", "pear"]
{var $fruits = 'banana; apple; pear' | esplit : '/;\s/'} // ["banana", "apple", "pear"]

• join — объединяет элементы массива в строку, используя первый параметр в качестве соединителя (по умолчанию ,).

{var $fruits1 = ["banana", "apple", "pear"]}
{$fruits1 | join} // banana, apple, pear
{$fruits1 | join : 'is not'} // banana is not apple is not pear

• number (number_format) — форматирование числа php функцией number_format()

{var $number = 10000}
{$number | number : 0 : '.' : ' '} // выведет 10 000

• md5, sha1, crc32 — подсчёт контрольной суммы строки разными алгоритмами

{'text' | md5} // 1cb251ec0d568de6a929b520c4aed8d1
{'text' | sha1} // 372ea08cab33e71c02c651dbc83a474d32c676ea
{'text' | crc32} // 999008199

• urldecode, urlencode, rawurldecode — обработка строки соответствующей PHP функцией.

{'http://site.com/?key=value' | urlencode} // http%3A%2F%2Fsite.com%2F%3Fkey%3Dvalue
{'http%3A%2F%2Fsite.com%2F%3Fkey%3Dvalue' | urldecode} // http://site.com/?key=value

• base64_decode, base64_encode — кодирование и декодирование строки алгоритмом base 64

{'text' | base64_encode} // dGV4dA==
{'dGV4dA==' | base64_decode} // text

• json_encode (toJSON), json_decode (fromJSON)

{'{"key":"value"}' | fromJSON} // ["key" => "value"]
{["key" => "value"] | toJSON} // {"key":"value"}

• http_build_query — генерирация URL-кодированной строки из массива

{['foo'=>'bar','baz'=>'boom'] | http_build_query} // foo=bar&baz=boom

• print_r — распечатка переменной через PHP функцию. Если передан параметр, то можно сохранить результат.

{var $printed = (['key' => 'value'] | print_r : true)} // Array ( [key] => value )

• var_dump (dump) — распечатка переменной вместе с типом
• nl2br — вставляет HTML-код разрыва строки перед каждым переводом строки
• lower (low, lcase, lowercase, strtolower) — перевод строки в нижний регистр

{'Текст для проверки' | lower} // текст для проверки

• upper (up, ucase, uppercase, strtoupper) — перевод строки в верхний регистр

{'Текст для проверки' | upper} // ТЕКСТ ДЛЯ ПРОВЕРКИ

• ucwords — преобразует в верхний регистр первый символ каждого слова в строке, а остальные символы в нижний

{'теКст Для провЕрки' | ucwords} // Текст Для Проверки

• ucfirst — преобразует в верхний регистр первый символ первого слова в строке, а остальные символы в нижний

{'теКст Для провЕрки' | ucfirst} // Текст для проверки

• htmlent (htmlentities) — преобразует все возможные символы в соответствующие HTML-сущности

{'<b>Текст для проверки</b>' | htmlent} // &lt;b&gt;Текст для проверки&lt;/b&gt;gt;

• limit — обрезка строки до указанного количества символов

{'Привет, как дела' | limit : 6} // Привет

• esc (tag) — экранирование HTML и MODX тегов

{'Привет, [[+username]]' | esc} // тег username не будет обработан

• notags (striptags, stripTags, strip_tags) — удаление HTML тегов из строки

{'<b>Привет!</b>' | notags} // Привет!

• stripmodxtags — удаление тегов MODX из строки

{'Привет, [[+username]]' | stripmodxtags} // Привет,

• cdata — оборачивает вывод тегами CDATA. Обычно это нужно для экранирования значений в XML разметке.
• reverse (strrev) — переворачивает строку символ за символом

{'mirrortext' | reverse} // txetrorrim

• wordwrap — вставляет перенос строки после каждого n-ого символа (слова не разбиваются)

{'very very long text' | wordwrap : 3} // very<br />very<br />long<br />text

• wordwrapcut — вставляет перенос строки после каждого n-ого символа, даже если этот символ будет внутри слова

{'very very long text' | wordwrapcut : 3} // ver<br />y<br />ver<br />y<br />lon<br />g<br />tex<br />t

• fuzzydate — выводит дату относительно сегодня и вчера, используя словари системы. Если прошло уже больше 2х дней, то форматирует дату через strftime.

{'2016-03-20 13:15' | fuzzydate : '%d.%m.%Y'} // 20.03.2016
{'' | date : 'Y-m-d 13:15' | fuzzydate} // сегодня в 01:15 PM

• declension (decl) — склоняет слово, следующее за числом по правилам русского языка. Например: 1 яблоко, 2 яблока, 10 яблок. Вторым параметром указывается выводить ли само число, по умолчанию выводится только подходящий вариант слова. Разделитель вариантов можно задавать третьим параметром, по умолчанию |.

{6 | declension : 'яблоко|яблока|яблок'} // яблок
{3 | declension : 'яблоко|яблока|яблок' : true} // 3 яблока
{101 | decl : 'яблоко,яблока,яблок' : false : ','} // яблоко

• ismember (memberof, mo) — проверка принадлежности пользователя к группе или группам пользователей MODX. Если переменная пуста, то проверка проводится для текущего пользователя.

{1 | ismember : 'Administrator'} // true
{0 | ismember : ['Administrator', 'Manager']} // false

• isloggedin, isnotloggedin — проверка авторизации текущего пользователя в контекте. Если контекст не указан, то проверяется текущий.

{'' | isloggedin : 'web'} // true
{'' | isnotloggedin : 'web'} // false

• url — генерация ссылки на документ системы через modX::makeUrl.

{10 | url}
{10 | url : ['scheme' => 'full'] : ['param' => 'value']}

• lexicon — вывод записи из словарей системы через modX::lexicon. Некоторые словари предварительно нужно загрузить.

{$_modx->lexicon->load('en:core:default')}
{'action_err_nfs' | lexicon : ['id' => 25] : 'en'} // No action with 25 found.

• user (userinfo) — вывод поля пользователя системы

{1 | user : 'fullname'} // Administrator

• resource — вывод поля документа системы. Можно выводить и ТВ параметры

{1 | resource : 'longtitle'} // Home page
{1 | resource : 'my_tv'} // My_tv value

• print — функция распечатки и экранирования любых переменных. Очень удобно использовать для отладки, когда нужно узнать, что находится внутри. Единственный параметр указывает, нужно ли обернуть данные в тег <pre> (по умолчанию — да).

{1 | resource | print} // распечатает массив с данными всего ресурса
{0 | user : 'extended' | print : false} // распечатает массив поля `extended` текущего пользователя в одну строку

• setOption — выставление значения в массив modX::config. Обязательно нужно указать ключ значения в массиве.

{'Новое имя сайта' | setOption : 'site_name'}

• option (getOption) — получение значения из массива modX::config

{'site_name' | option} // Новое имя сайта

• setPlaceholder (toPlaceholder) — выставление значения в массив modX::placeholders. Обязательно нужно указать ключ значения в массиве.

{'My text' | setPlaceholder : 'my_text'}

• placeholder (fromPlaceholder) — получение значения из массива modX::placeholders.

{'my_text' | placeholder} // My text

• cssToHead — регистрация CSS кода в шапке страницы
• htmlToHead — регистрация произвольного HTML в шапке страницы
• htmlToBottom — регистрация произвольного HTML в подвале страницы
• jsToHead — регистрация javascript файла в шапке страницы. Если передать параметром true, то можно регистрировать сразу код.
• jsToBottom — регистрация javascript в подвале страницы. Если передать параметром true, то можно регистрировать сразу код.

{'<script>alert();</script>' | jsToBottom : true} // При загрузке страницы будет javascript alert

для работы функций регистрации на странице должны быть теги head и body

PCRE модификаторы

• preg_quote — добавляет обратный слеш перед каждым служебным символом. Это бывает полезно, если в составлении шаблона участвуют строковые переменные, значение которых в процессе работы скрипта может меняться в регулярных выражениях служебными считаются следующие символы:

. \ + * ? [ ^ ] $ ( ) { } = ! < > | : -

• preg_match — выполняет проверку на соответствие регулярному выражению

Например, выведем email если соответствует регулярному выражению:

{if 'email@mail.ru'|preg_match : '/^.+@.+\\.\\w+$/' }
email
{/if}

• preg_get — выполняет поиск по регулярному выражению, результат содержит первый набор вхождений

Например, получим первое изображение из поля content:

{set $image = $_modx->resource.content|preg_get : '!http://.+\.(?:jpe?g|png|gif)!Ui}

• preg_get_all — выполняет поиск по регулярному выражению, результат содержит набор всех вхождений
• preg_grep — возвращает массив вхождений, которые соответствуют шаблону

Например, получим только даты:

{["26-04-1974", "Сергей", "27-11-1977", "Юля"] | preg_grep : "/(\d{2})-(\d{2})-(\d{4})/" | print_r : true}

• preg_replace — выполняет поиск и замену по регулярному выражению

Например, выведем название сайта без http:

Website: {'http://site.name'|preg_replace : '~^https?://~': ''}

• preg_filter — выполняет поиск и замену по регулярному выражению идентична preg_replace за исключением того, что возвращает только те значения, в которых найдено совпадение
• preg_split — разбивает строку по регулярному выражению

Например:

{'I love MODX' | preg_split : '/ /' | print_r : true}// Array ( [0] => I [1] => love [2] => MODX )

• Простая конкатенация массивов (Можно использовать теги HTML)

Пример:

{set $array = [1,2,3,4]}

{set $output}
    {foreach $array as $item}{$item}{/foreach}
{/set}

{$output} //Вывод 1234

Собственные модификаторы

Сниппет-фильтр должен принимать 2 параметра: обязательны $input и необязательный $options. Возвращать он может только строки.

В качестве примера давайте создадим сниппет randomize, который будет брать полученную строку и прибавлять к ней случайный набор символов. В параметре мы можем передать количество добавляемых символов:

<?php
if (empty($options)) {
    $options = 10;
}
$rand = md5(rand());

return $input . ' ' . substr($rand, 0, $options);

Теперь можно смело использовать новый модификатор как в Fenom

{'any text' | randomize : 5}

так и в MODX

[[!*pagetitle:randomize=`5`]]

Собственные модификаторы Fenom

Начиная с версии 2.6.0, для добавления модификаторов можно использовать системное событие pdoToolsOnFenomInit:

<?php
/** @var modX $modx */
switch ($modx->event->name) {
    case 'pdoToolsOnFenomInit':
        /** @var Fenom $fenom
        Мы получаем переменную $fenom при его первой инициализации, так что можем добавить
        модификатор "website" для вывода имени домена из произвольной ссылки.
        */
        $fenom->addModifier('website', function ($input) {
            if (!$url = parse_url($input)) {
                return $input;
            }
            $output = str_replace('www.', '', $url['host']);

            return strtolower($output);
        });
        break;
}

Теперь модификатор website можно использовать в любых чанках и шаблонах Fenom:

<a href="{$link}" target="blank">{$link | website}</a>

Такие модификаторы являются внутренними методами Fenom и работают быстрее сниппетов, потому что не нужно делать запрос в БД для их загрузки, а потом кэшировать код в файл для запуска.

Собственные теги Fenom

В fenom можно создавать собственные теги

<?php
/** @var modX $modx */
switch ($modx->event->name) {
    case 'pdoToolsOnFenomInit':
        $fenom->addCompiler('exit', function () {
            return "return;";
        });
        break;
}

Теперь спокойно можете перервать работу шаблонизатора используя {exit} Пример:

тут текст
{exit}
тут текст после exit
вывод "тут текст"

Расширение шаблонов

Использование шаблонизатора Fenom позволяет включать одни чанки (шаблоны в другие) и даже расширять их.

Например, вы можете просто подгрузить содержимое чанка:

Обычный чанк {include 'имя чанка'}
Шаблон modTemplate {include 'template:имя шаблона'}
Чанк с набором параметров
{include 'chunk@propertySet'}
{include 'template:Name@propertySet'}

Подробнее про {include} читайте в официальной документации.

Гораздо более интересная функция — {extends} шаблонов, она требует включенной системной настройки pdotools_fenom_parser.

Пишем базовый шаблон «Fenom Base»:

<!DOCTYPE html>
<html lang="en">
<head>
    {include 'head'}
</head>
<body>
    {block 'navbar'}
        {include 'navbar'}
    {/block}
    <div class="container">
        <div class="row">
            <div class="col-md-10">
                {block 'content'}
                    {$_modx->resource.content}
                {/block}
            </div>
            <div class="col-md-2">
                {block 'sidebar'}
                    Sidebar
                {/block}
            </div>
        </div>
        {block 'footer'}
                {include 'footer'}
        {/block}
    </div>
</body>
</html>

Он включает обычные чанки (в которых, кстати, обычные плейсхолдеры MODX от компонента Theme.Bootstrap) и определяет несколько блоков {block}, которые можно расширить в другом шаблоне.

Теперь пишем «Fenom Extended»:

{extends 'template:Fenom Base'}

{block 'content'}
    <h3>{$_modx->resource.pagetitle}</h3>
    <div class="jumbotron">
        {parent}
    </div>
{/block}

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

Точно также можно писать и расширять чанки, только обратите внимание, что для работы с modTemplate нужно указывать префикс template:, а для чанков нет — они работают по умолчанию во всех {include} и {extends}.

Важно! При наследовании Fenom требует обязательного объявления хотя бы одного блока в шаблоне. Т.е. просто унаследовать базовый шаблон строкой {extends 'template:Fenom Base'} нельзя, будет 502 ошибка на уровне PHP. Достаточно объявить любой блок либо переопределить из базового:

{extends 'template:Fenom Base'}
{block 'empty'}{/block}

 

Отключение

Парсер pdoTools хорошо протестирован и не замечен в каких-либо ошибках, но если вы в чём-то его подозреваете — с версии 2.8.1 можно легко включить родной парсер MODX.

Для этого вам нужно изменить изменить ровно одну системную настройку:

• parser_class — укажите в неё modParser.

Для включения pdoParser нужно указать его имя обратно в этой настройке.

Проблемы и решения

При работе с pdoParser, при использовании fenom шаблонизатора, разработчики часто встречаются с выводом белого экрана вместо страниц сайта. Сергей Шлоков в своей статье — Почему не работает тег ignore, подробно расписал механику работы pdo парсера и объяснил, что именно вызывает ошибку.

Если front-end вашего сайта лег (белая страница или ошибка 500), а в логах вы встречаете подобные ошибки:

(ERROR @ /public_html/core/components/pdotools/model/pdotools/pdotools.class.php : 582) Unexpected token 'm' in expression in file:chunks/metrika.tpl line 3, near '{(m' <- there

это значит, что парсер fenom пытается обработать тег в фигурных скобках и не находит его у себя. Чтобы такого не происходило можно использовать одно из решений, представленных ниже.

Пробелы вокруг фигурных скобок

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

function(){ //code }

Тег {ignore}

Часто не удобно проставлять пробелы вокруг скобок, так как кода может быть много, он может добавляться постоянно, очень просто пропустить какую-то скобку. В таких случаях удобно использовать тег {ignore}

{ignore}
    function(){ //code }
{/ignore}

Но надо помнить, что внутри этого тега fenom не работает. Тег {ignore} должен присутствовать в итерации, после которой больше не будет тегов Fenom. К сожалению, добиться этого не всегда получается. В новой версии pdoTools эта ошибка исправлена, но она всё равно возникает при использовании файловых элементов.

От автора сайта modzone

Если {ignore} не помог, то в статье по ссылке выше, есть два варианта решения.

1. Указать в шаблоне кэшируемый тег [[*content]] вместо {$_modx->resource.content}.
2. Перенести блок с тегом {ignore} в ресурс (зачастую такие теги размещают в чанках).

Встроенные модификаторы

Это удобно когда вы подключаете JS-код. Например можно воспользоваться модификатором jsToBottom. @iWatchYouFromAfar приводит в пример следующий код:

{'<script type="text/javascript" >
{Cкрипт Google аналитики или Яндекс.Метрики}</script>' 
| jsToBottom : true}

Свой модификатор ignore

Можно так же написать свой модификатор ignore с помощью события pdoToolsOnFenomInit. Это намного лучше, чем делать ради этого отдельно сниппет. Этот вариант удобен, когда вы используете {} вне JS кода, например в разметке элемента.

<?php
/** @var modX $modx */
switch ($modx->event->name) {
    case 'pdoToolsOnFenomInit':
        $fenom->addModifier('ignore', function ($input) {
            $output = '{ignore}' . $input . '{/ignore}';
            return $output;
        });
        break;
}

Использование:

<div data-attr='{'{"0":{"items":1,"nav":"false"},"100":{"items":2}}' | ignore}'>

Источник: docs.modx.pro

Примеры использования Fenom MODX (шпаргалка)

Запуск сниппетов в Fenom.

1 способ:

{'!pdoPage' | snippet : [
    'parents' => $_modx->resource.id, 
    'limit' => 7,
    'toPlaceholder' => 'result'
]}
{$_modx->getPlaceholder('result')}
{$_modx->getPlaceholder('page.total')}
{$_modx->getPlaceholder('page.nav')}

2 способ:

{$_modx->runSnippet('!pdoPage', [
    'parents' => $_modx->resource.id, 
    'limit' => 7,
    'toPlaceholder' => 'result'
])}

{$_modx->getPlaceholder('result')}
{$_modx->getPlaceholder('page.total')}
{$_modx->getPlaceholder('page.nav')}

Если необходимо вызвать pdopage без параметров:

#1 способ
{'!pdoPage' | snippet}

#2 способ
{$_modx->runSnippet('!pdoPage')}

Условие IF

#Устанавливаем id текущей страницы в переменную
{set $id = $_modx->resource.id}
#Условие
{if $id == '1'}
<p>Главная страница</p>
{else}
<p>Не главная</p>
{/if>

Условие IF с использованием тренарного оператора

#Устанавливаем id текущей страницы в переменную
{set $id = $_modx->resource.id}
#Условие
{$id == '1' ? '<p>Главная страница</p>' : '<p>Не главная</p>'}

Вывод чанка

{include 'myChank'}

Получение значения TV у произвольного ресурса:

{7 | resource: 'tv_name'}

*7 — id ресурса

Вывод MIGX через Fenom для текущего ресурса:

{set $rows = json_decode($_modx->resource.tv_images, true)}
{foreach $rows as $row}
    {$row.image}
{/foreach}

Информация о прозводителе в miniShop2

{$_modx->makeUrl($_pls['vendor.resource'])}
{$_pls['vendor.name']})
{$_modx->getPlaceholder('vendor.name')}

Получение изображения через переменную с точкой ($_pls)

{$_pls["tv.img"] | phpthumbon : "w=300&h=200&zc=1"}
//Без префикса
{$img | phpthumbon : "w=300&h=200&zc=1"}

Небольшой пример по выводу картинок с обрезкой при помощи $_pls и phpThumbOn.

[[pdoResources?
&limit=`4`
&includeTVs=`image`
&parents=`75`
&prepareTVs=`1`
&processTVs=`1`
&tpl=`newsbox-item`
]]

Чанк newsbox-item:

{var $image = 'phpThumbOn' | snippet : ['input' => $_pls['tv.image'],  'options' => 'w=250&h=160&zc=1']}
<div class="col-md-3 col-xs-3">
    <div class="thumbnail">
        <a href="{$uri}"><img src="{$image}"></a>
    </div>
    <i class="fa fa-calendar"></i>{$publishedon | date_format:"%d.%m.%Y"} <a href="{$uri}">{$longtitle}</a>
</div>

Но как по мне лучше указывать сразу при выводе: {$image | phpthumbon : "w=300&h=200&zc=1"} без $_pls.

Получение превью изображений в корзине

{if $product['120x90']?}
<img src="{$product['120x90']}" alt="{$product.pagetitle}" title="{$product.pagetitle}"/>
{else}
<img src="{'assets_url' | option}components/minishop2//web/ms2_small.png" 
srcset="{'assets_url' | option}components/minishop2/img/web/ms2_small@2x.png 2x" 
alt="{$product.pagetitle}" title="{$product.pagetitle}"/>
{/if}

Вывод текущего года

{'' | date : 'Y'}

Вывод полного URL адреса текущей страницы вместе с протоколом + canonical

{$_modx->makeUrl($_modx->resource.id, '', '', 'full')}
<link rel="canonical" href="{$_modx->makeUrl($_modx->resource.id, '', '', 'full')}">

Проверка авторизации

{$_modx->isAuthenticated()} {$_modx->hasSessionContext('web')} {$_modx->hasPermission('load')}

Вывод базового URL

<base href="{$_modx->config.site_url}">

meta robots

{if $_modx->resource.searchable}<meta name="robots" content="index, follow">
{else}<meta name="robots" content="noindex, nofollow">{/if}
За index / noindex отвечает галка в ресурсе: Доступен для поиска.

title

<title>{$_modx->resource.longtitle ?: $_modx->resource.pagetitle} | {$_modx->config.site_name}</title>
Выводим расширенный заголовок в title, если он не заполнен то выводим просто заголовок.

meta author

<meta name="author" content="{$_modx->user.fullname}">
Выводим имя автора контента.

Убираем циклическую ссылку с главной страницы

Многие SEO специалисты (в том числе я), считают к примеру что логотип на главной странице не должен вести на нее же, поэтому можно написать такое условие.

{if $_modx->resource.id != 1}
<a class="logo" href="{$_modx->makeUrl(1)}" title="Перейти на главную страницу" >
<img src="images/logotip.png" alt="{$_modx->config.site_name}, перейти на главную"></a>
{else}
<div class="lodo"><img src="images/logotip.png" alt="{$_modx->config.site_name}></div>
{/if}

Вывод чанка на определенном ресурсе

Часто карусели используются только на главной странице и чтобы не городить отдельный шаблон для главной, можно вынести слайдер в отдельный чанк и далее вызвать такой конструкцией:
{if $_modx->resource.id = 1}{include 'slider'}{/if}

Вывод чанков по ID шаблонов

{include ('tpl.' ~ $_modx->resource.template)}
Подробнее будем разбирать в уроке: Натяжка верстки на modx.

Вывод даты

{$_modx->resource.publishedon | date_format:"%d-%m-%Y %H:%M:%S"}

Вырезаем пробелы из телефона

Допустим у нас стоит ClientConfig и мы создали системную настройку phone со значение 8 800 7000 700 и нам нужно убрать пробелы из значения tel, тогда вызов будет следующим:
<a href="tel:{$_modx->config.phone | preg_replace : '/[^0-9+]/' : ''}"> {$_modx->config.phone}</a>
В следующих уроках мы начнем производить натяжку верстки на modx и я буду приводить код в обоих шаблонизаторах, делайте на том, к которому душа ближе лежи. Начнем с разбивки шаблона на чанки.