Синтаксис тегов

Варианты тегов MODX¶

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

Деконструкция тега MODX¶

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

Построение тега MODX¶

Используя и комбинируя всю вышеуказанную информацию, мы можем создать сложный тег MODX, который будет выглядеть следующим образом:

[[!MySnippet@myPropSet:filter1:filter2=`modifier`? &prop1=`x` &prop2=`y`]]

Однако, хотя MODX позволяет использовать сложные условные фильтры, пользователи должны быть осторожны при построении сложной логики тегов. В отличие от PHP, если у вас недопустимый синтаксис тега MODX, нет полезных сообщений с номерами строк, указывающими местоположение ошибки.

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

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

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

[[!getResources?
  &parents=`123`
  &limit=`5`
]]

Одинарные квадратные скобки внутри тегов¶

В MODX 3 внутри значений свойств тега (например в output filter) можно оставлять литеральные [ и ], не ломая сбор тегов. #13904

[[+label:notempty=`[required]`]]

Сами теги по-прежнему пишутся в двойных скобках: [[ ... ]].

Значения-массивы в свойствах элементов (extras / кастомные парсеры)¶

Если сниппет, чанк или другой элемент получает свойства-массивы (часто через PHP API, а не строку тега), MODX строит стабильную cache/tag-подпись через serialize этих массивов. Кастомные парсеры и подклассы элементов, которые сами собирают подпись тега, должны обрабатывать array-свойства так же, чтобы ключи кеша оставались сортируемыми и согласованными. #14689

Свойства¶

Все теги MODX могут принимать свойства, не только Сниппеты.

В приведенном ниже примере у нас есть простой блок с именем «Hello».

Hello [[+name]]!

Внутри этого чанка у нас есть настройка плейсхолдера [[+name]] для значения, которое будет отображаться. Мы можем передать это значение непосредственно в наш блок с помощью следующего кода:

[[$Hello? &name=`George`]]

Этот вызов будет выглядеть следующим образом:

Hello George!

Кеширование¶

Любой тег можно вызвать некэшированным, вставив восклицательный знак сразу после открывающей двойной скобки:

[[!snippet]], [[!$chunk]], [[!+placeholder]], [[!*template_var]], и так далее.

Если у вас есть какая-то расширенная настройка, в которой параметр site_url устанавливается для каждого запроса, но ваш [[~[[*id]]]] ссылки не генерируются должным образом, помните, что любой тег можно вызвать некэшированным, включая тег ссылки или якоря: [[!~[[*id]]]]

Тем не менее, вам понадобится это только тогда, когда site_url устанавливается динамически, может отличаться для каждого запроса, и вы генерируете полные URL-адреса вместо относительных. Любое нормальное использование можно кэшировать.

Когда кэшировать¶

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

Оставляйте тег некэшированным, когда:

1. Вывод зависит от пользователя (Login, данные профиля, [[!+modx.user.id]], меню только для участников).
2. Вывод зависит от GET/POST или других данных запроса (поиск, постраничность getPage, ответ формы).
3. Задача сниппета: редирект или другое действие по запросу, даже если он ничего не печатает.
4. Нужен свой срок жизни кэша для данных, которые меняются вне MODX (делайте это внутри сниппета или через Extra для кэша).

Типичные ошибки: вызывать Wayfinder или getResources с !, «чтобы меню обновлялось» (сохранение контента и так пересобирает кэш), и вызывать If некэшированным, когда условие опирается на статичное поле ресурса.

Порядок разбора¶

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

1. Вложенный кэшированный тег
2. Кэшированный тег
3. Вложенный некэшированный тег
4. Некэшированный тег

После кэшированного прохода оставшиеся некэшированные теги попадают в файл кэша страницы и выполняются на каждом запросе.

Если вы вызываете некэшированный сниппет, который ставит плейсхолдеры, пометьте эти плейсхолдеры тоже как некэшированные:

[[!Profile]]
Hello [[!+username]],

Иначе кэшированный [[+username]] может показать прошлое (или пустое) значение.

Вложенные теги и «москитные» условия¶

Вложенные теги здесь обычны. Условия, в которые в :then= / :else= вставлены полные теги, опасны: обе ветки разбираются до проверки условия. Сниппет с редиректом в неиспользуемой ветке всё равно сработает.

Собирайте следующий тег из результата условия (стиль mosquito), затем оберните выражение во внешние [[ ]]:

[[[[*id:is=`1`:then=`$homeChunk`:else=`$defaultChunk`]]]]

Кратко и с примерами: Вложенные теги, кэш и mosquito-условия.

Тайминг¶

В MODX есть несколько тегов синхронизации:

• [^qt^] - Время запроса - показывает, сколько времени MODX потратил на общение с базой данных
• [^q^] - Количество запросов - Показывает, сколько запросов к базе данных выполнено MODX
• [^p^] - Время разбора - показывает, сколько времени понадобилось MODX для разбора страницы
• [^t^] - Общее время - показывает общее время, затраченное на анализ / рендеринг страницы.
• [^s^] - Источник - показывает источник страницы, является ли база данных или кеш
• [^m^] - Использование памяти - Показывает общий объем памяти, занятый для анализа / рендеринга страницы.

Дополнительная помощь¶

Поскольку синтаксис тегов проблематичен для многих новичков, существуют инструменты, которые помогут выделить проблемы. Проверьте плагином SyntaxChecker.