Переменные шаблона в MODX: короткое руководство

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

Что подготовить

До начала выберите ресурс, на котором проверите результат, и шаблон, назначенный этому ресурсу. Убедитесь, что можете редактировать шаблон. Если у вас MODX Cloud или панель с ограниченными правами, нужные пункты меню могут быть недоступны — тогда попросите администратора выдать права.

TV (Template Variable, переменная шаблона) — дополнительное поле, значение которого можно задавать отдельно для каждого ресурса. В отличие от обычного поля ресурса, TV создаёт администратор и сам выбирает её тип и область применения.

Создайте переменную

1. В менеджере откройте раздел с элементами и выберите «Переменные шаблона» (Template Variables). Нажмите создание новой переменной. В MODX 2.x и 3.x расположение пунктов может различаться в зависимости от версии и настроек менеджера.

   Проверка: открылась форма новой TV с полями имени, подписи, типа ввода и вкладками настроек.

2. Задайте имя без пробелов, например subtitle. Для имени лучше использовать латиницу, цифры и подчёркивание. Подпись укажите понятную редактору — например, «Подзаголовок». Она нужна для формы ресурса, а не для вывода на сайте.

   Проверка: имя заполнено, а подпись позволяет отличить поле от других в менеджере.

3. Выберите тип ввода. Для короткого текста подойдёт текстовое поле; для длинного — текстовая область. Тип определяет, как редактор вводит значение в менеджере, но сам по себе не задаёт оформление на странице.

   Проверка: после выбора типа форма показывает настройки, подходящие этому элементу управления.

4. Откройте вкладку доступа к шаблонам (обычно Template Access) и отметьте шаблон, который назначен тестовому ресурсу. Сохраните переменную. Если связать TV не с тем шаблоном, поле не появится в форме редактирования ресурса.

   Проверка: у TV отмечен нужный шаблон, а после сохранения она появилась в списке переменных шаблона.

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

   Проверка: после повторного открытия ресурса введённое значение осталось в поле.

6. Откройте шаблон ресурса и добавьте тег [[*subtitle]] в место, где должен появиться текст. Например, сразу после заголовка страницы. Сохраните шаблон, затем очистите кэш MODX и откройте страницу сайта.

   Проверка: на странице рядом с заголовком появился текст из поля. Если ресурс ещё не опубликован, проверяйте результат с учётом его статуса и доступа.

Какие настройки важны

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

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

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

• Поле видно, но на странице пусто. Убедитесь, что значение внесено именно в этот ресурс и сохранено. Проверьте совпадение имени TV и имени в теге: subtitle отличается от subTitle.

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

• Вместо значения виден сам тег. Проверьте, что тег записан в синтаксисе MODX как [[*subtitle]], а не вставлен в визуальный редактор, который изменил скобки. Проверьте также, что вы редактируете шаблон, фактически назначенный ресурсу.

• Появляется ошибка сохранения. Это не обязательно проблема самой TV: проверьте обязательные поля формы и права пользователя. Точный текст зависит от версии менеджера и настроек сайта; ориентируйтесь на сообщение MODX и журнал ошибок, а не на универсальный перечень фраз.

Когда обычного вывода недостаточно

Тег [[*subtitle]] подходит, когда нужно вывести значение TV текущего ресурса. Для форматирования, обработки пустого значения или получения данных другого ресурса могут понадобиться дополнительные средства MODX. Не подставляйте пользовательский HTML без проверки: редактор может внести разметку, которая нарушит шаблон или создаст риск небезопасного вывода.

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

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

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