Синтаксис MODX: теги, параметры и кеширование

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

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

Упражнения выполняем стандартным синтаксисом. Варианты Fenom в конце приведены для сравнения: устанавливать и включать его ради этого урока не нужно.

Как выглядит тег MODX

Обычный тег начинается с двух открывающих квадратных скобок и заканчивается двумя закрывающими:

[[*pagetitle]]

Звездочка обозначает поле текущего ресурса или TV, а pagetitle — имя поля основного заголовка.

Например, в HTML можно написать:

<h1>[[*pagetitle:htmlent]]</h1>

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

Сами теги посетитель обычно не видит: браузер получает уже сформированный HTML.

Основные теги MODX

Тип вызова определяется символом после открывающих скобок.

header, snippetName, result и tags — примеры имен. Соответствующие элементы должны существовать, а плейсхолдер — получить значение. ID 15 заменяется идентификатором нужной страницы.

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

Поле ресурса, TV и плейсхолдер

Стандартные поля и дополнительные TV вызываются через звездочку:

[[*description]]
[[*tags]]

description уже предусмотрен системой. tags в этом примере — дополнительное поле, которое нужно создать и назначить используемому шаблону. Подробно это разберем в уроке TV.

Плюс обращается к плейсхолдеру:

[[+pagetitle]]

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

Плейсхолдер сам не получает данные: их передает чанк-параметр, сниппет, компонент или другой код.

Настройки и ссылки

Для настроек используются два плюса:

[[++site_name]]
[[++site_url]]
[[++site_start]]

• site_name — название сайта.
• site_url — базовый адрес.
• site_start — ID главной страницы, а не готовая ссылка.

Ссылку на ресурс формирует тег с тильдой:

<a href="[[~15]]">О компании</a>

Для полного адреса с протоколом и доменом можно передать параметр scheme:

[[~15? &scheme=`full`]]

Вместо 15 укажите ID своего ресурса. Такой вызов формирует адрес по данным и настройкам MODX, а не хранит вручную записанный alias страницы.

Вложенные теги

Внутренний тег может передать значение внешнему. Например, полный URL текущей страницы:

[[~[[*id]]? &scheme=`full`]]

Сначала определяется ID, затем формируется ссылка.

Ссылка на главную из настройки site_start:

<a href="[[~[[++site_start]]]]">Главная</a>

Так не нужно предполагать, что главная всегда имеет ID 1.

Параметры вызова

Параметры записываются после вопросительного знака. Каждый начинается с амперсанда, а значение заключается в обратные кавычки.

[[snippetName?
    &parameter=`value`
    &anotherParameter=`anotherValue`
]]

Это схема записи, а не готовое задание: snippetName и параметры нужно заменить существующим элементом и его настройками.

Тот же вызов в одну строку:

[[snippetName? &parameter=`value` &anotherParameter=`anotherValue`]]

Переносы строк нужны для читаемости. Обратные кавычки не заменяем обычными одинарными или типографскими.

Как параметр используется внутри чанка

Предположим, есть чанк zdravstvujte с таким текстом:

Здравствуйте, [[+name:htmlent]]!

Вызов передает ему значение name:

[[$zdravstvujte? &name=`Василий`]]

Результат:

Здравствуйте, Василий!

Сейчас пример нужен для чтения записи: параметр name подставляется в одноименный плейсхолдер. Создание чанков и другие варианты передачи данных разберем в отдельном уроке.

Модификаторы: обработка результата

Модификатор указывается через двоеточие. Он меняет результат вывода, а не сохраненное значение поля.

[[*pagetitle:htmlent]]

htmlent преобразует специальные символы в HTML-сущности. Это подходит для заголовка, который должен отображаться как текст.

Для content, содержащего нужную HTML-разметку, такое экранирование всего поля покажет теги вместо оформленных абзацев.

Модификаторы могут иметь значение и объединяться в цепочку:

[[*longtitle:default=`[[*pagetitle]]`:htmlent]]

При пустом longtitle выбирается pagetitle, затем результат обрабатывается htmlent. Цепочка выполняется слева направо.

У сниппета модификатор располагается перед вопросительным знаком:

[[snippetName:default=`Результат не получен`?
    &parameter=`value`
]]

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

[[!snippetName@propertySet:modifier=`value`?
    &parameter=`value`
]]

Кешируемые и некешируемые вызовы

Вызов без восклицательного знака считается кешируемым:

[[snippetName]]

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

[[!snippetName]]

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

Так можно вызывать и другие теги:

[[!$chunkName]]
[[!+placeholderName]]
[[!*tvName]]

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

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

Плейсхолдер от некешируемого сниппета

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

[[!snippetName]]
[[!+result]]

Здесь предполагается, что snippetName устанавливает result. Самих этих имен в чистой установке может не быть.

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

Комментарии

Комментарий MODX начинается с дефиса и удаляется из вывода:

[[- Пояснение к этому участку кода. ]]

HTML-комментарий остается в исходном коде ответа:

<!-- Пояснение, которое можно увидеть в исходном HTML. -->

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

Проверяем теги на учебном ресурсе

Откройте «Первый материал» или другой документ, созданный в предыдущем уроке. Сохраните копию его содержимого.

В режиме исходного HTML временно добавьте в content:

<p>Страница: [[*pagetitle:htmlent]]</p>
<p>ID ресурса: [[*id]]</p>
<p>Сайт: [[++site_name:htmlent]]</p>
<a href="[[~[[++site_start]]]]">На главную</a>

1. Сохраните ресурс и откройте его на сайте.
2. Сравните выведенные заголовок и ID с данными документа.
3. Проверьте название сайта и ссылку на главную.
4. Измените заголовок ресурса, сохраните и снова проверьте результат.
5. После упражнения удалите временный блок или восстановите сохраненное содержимое.

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

В само поле content не добавляйте вызов этого же поля [[*content]]. Его место — в шаблоне, который выводит содержимое страницы.

Если тег не дает ожидаемого результата

Ace помогает читать код, но подсветка не подтверждает существование элемента или правильность его параметров. Ошибки выполнения проверяют по журналу MODX и документации компонента.

Fenom: другой способ записи

В pdoTools есть шаблонизатор Fenom. В следующих материалах буду показывать его рядом со стандартными тегами, чтобы вы постепенно замечали соответствия.

Обратите внимание: переменная, переданная в чанк, и глобальный плейсхолдер MODX в Fenom получаются по-разному. Это не простая замена квадратных скобок фигурными.

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

Сейчас выполняем задания стандартным синтаксисом. Настройку и возможности второго варианта разберем в уроке Fenom, а рабочий сайт в практической части будем собирать уже на нем.

Следующий урок

Переходим к шаблонам MODX: создадим небольшую HTML-заготовку, назначим ее ресурсам и проверим, как одинаковое оформление выводит разные данные страниц.

Полная справочная запись тегов находится в официальной документации MODX.

← Предыдущая статьяРесурсы MODX: страницы, поля, настройки и работа с деревом

Следующая статья →Шаблоны MODX: создание, назначение и редактирование