Переменные в MODX: короткий гайд для первой TV

За 10–15 минут вы добавите в MODX Revolution переменную шаблона, заполните её для ресурса и выведете значение на странице. Для этого понадобятся доступ в менеджер MODX с правом создавать элементы и редактировать ресурсы, а также шаблон, который использует нужная страница. Примеры ниже — для MODX Revolution 2.x и 3.x: названия пунктов меню могут немного отличаться между версиями и сборками.

Что в MODX называют переменной

В коротких гайдах под переменными обычно имеют в виду переменные шаблона, или TV (от Template Variable). Это дополнительное поле ресурса: например, «Подзаголовок», «Цена» или «Изображение для карточки». Значение можно задать отдельно для каждой страницы и вывести в шаблоне MODX.

TV не то же самое, что системная настройка MODX или плейсхолдер сниппета. Если вам нужно хранить общее значение для сайта либо передать результат работы сниппета, это другие механизмы. Здесь создаём именно поле, которое редактор заполняет у ресурса.

TV хранит значение у конкретной страницы, а шаблон решает, где это значение появится на сайте.

Перед началом: выберите страницу и шаблон

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

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

Создаём и выводим переменную

1. Откройте раздел элементов. В менеджере найдите «Элементы» (Elements), затем «Переменные шаблона» (Template Variables). Нажмите создание новой TV. Проверка: открылась форма, где можно задать имя и тип ввода.
2. Задайте имя и тип. Назовите TV, например, subtitle, без пробелов. Выберите тип ввода «Текст» (обычно Text). Название станет частью тега в шаблоне, поэтому используйте латинские буквы и не меняйте его после того, как добавили в шаблон. Проверка: имя сохранено, тип ввода текстовый.
3. Свяжите TV с шаблоном. В форме TV найдите вкладку или раздел доступа к шаблонам и отметьте шаблон нужной страницы. Названия и расположение настроек могут отличаться. Сохраните TV. Проверка: в списке назначенных шаблонов есть тот, который использует выбранный ресурс.
4. Добавьте тег в шаблон. Откройте связанный шаблон и вставьте в нужное место [[*subtitle]]. Сохраните изменения. Это тег MODX для вывода значения TV текущего ресурса. Проверка: тег остался в сохранённом шаблоне и не оказался внутри HTML-комментария.
5. Заполните поле у ресурса. Откройте страницу, назначенную этому шаблону. Найдите вкладку или блок с TV, введите, например, «Материалы для вашего проекта» и сохраните ресурс. Проверка: после повторного открытия ресурса введённый текст остался в поле.
6. Проверьте страницу на сайте. Откройте страницу публично и найдите добавленный текст. Если сайт показывает закешированную версию, очистите кэш MODX и обновите страницу. Проверка: вместо тега выводится введённое значение.

Тег [[*subtitle]] выводит TV с именем subtitle у текущего ресурса. Звёздочка здесь важна: это указание на поле текущей страницы. Для данного примера не нужны PHP-код, сниппеты или отдельный пакет.

Если значение не появилось

• Поля TV нет в форме ресурса. Чаще всего TV не связана с шаблоном ресурса. Проверьте назначение шаблона и настройки доступа TV, затем сохраните изменения и снова откройте страницу в менеджере.
• На сайте виден буквальный тег. Проверьте, что тег вставлен в шаблон MODX, а не в обычный текстовый блок, который не обрабатывается парсером. Убедитесь, что имя после звёздочки совпадает с именем TV.
• Тег исчез, но текста нет. Проверьте, заполнено ли поле именно у этого ресурса. Если TV пустая, показывать нечего. Также убедитесь, что вы открыли нужную страницу, а не соседний ресурс с тем же шаблоном.
• Изменения не видны после сохранения. Очистите кэш сайта через менеджер MODX и обновите страницу без использования старой закешированной копии браузера. Если результат всё ещё прежний, проверьте, тот ли шаблон редактировали.

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

Что сделать дальше

Когда базовая TV заработала, проверьте её на двух ресурсах: заполните поле у одного и оставьте пустым у другого. Так вы увидите, как шаблон ведёт себя при отсутствии значения. Затем определите, что должно показываться в этом случае, и настройте вывод под свою версию MODX по официальной документации. Для изображений, выпадающих списков и прав доступа используйте отдельные настройки TV: не переносите параметры текстового поля на другие типы.

Термин: ресурс в MODX — страница или другой объект сайта, который редактируется в дереве ресурсов менеджера.