Переменные шаблона в MODX: пошаговая инструкция

За 15 минут вы создадите переменную шаблона в MODX Revolution 3.x, добавите поле на страницу ресурса и выведете его значение в шаблоне. На примере разберём текстовое поле, а затем покажем, что меняется для изображения и списка.

Что подготовить до начала

Инструкция рассчитана на MODX Revolution 3.x. В MODX Revolution 2.x названия некоторых пунктов могут отличаться, но логика остаётся той же.

• доступ в админку MODX с правами на создание элементов и редактирование ресурсов;
• опубликованный или тестовый ресурс;
• шаблон, который назначен этому ресурсу;
• доступ к очистке кеша сайта.

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

Сноска. TV (Template Variable) — дополнительное поле ресурса в MODX. Это не отдельная колонка, которую вы вручную добавляете в базу данных, а элемент MODX, связанный с шаблонами и ресурсами.

Главная причина, по которой TV «не работает», — переменную создали, но не привязали к шаблону ресурса.

Шаг 1. Создайте переменную шаблона

1. Откройте в менеджере раздел Элементы и перейдите к списку Переменные шаблона. В MODX 3.x название пункта может отображаться в русской локализации немного иначе.

   Нажмите кнопку создания новой переменной.

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

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

   В поле Заголовок напишите понятную подпись для редактора: «Подзаголовок страницы». Описание можно использовать как короткую подсказку.

   Проверка: в форме есть уникальное имя subtitle, а редактору понятно, что вводить в это поле.

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

   Проверка: выбран тип, который соответствует содержимому: короткий текст не превращён в большое поле с редактором, а длинный текст не ограничен одной строкой.

4. Сохраните переменную. Если MODX предлагает заполнить дополнительные параметры, оставьте значения по умолчанию для первой проверки.

   Проверка: subtitle появилась в списке переменных шаблона.

Шаг 2. Привяжите TV к шаблону

1. Откройте созданную переменную и найдите раздел или вкладку, связанную с доступом шаблонов. Отметьте шаблон, который используется вашим ресурсом. В разных версиях и локализациях этот блок может называться Доступ шаблона, Template Access или Шаблоны.

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

2. Сохраните изменения. Затем откройте ресурс, которому назначен этот шаблон.

   Проверка: в форме редактирования ресурса появился блок с подписью «Подзаголовок страницы».

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

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

Шаг 3. Выведите значение в шаблоне

Откройте шаблон, назначенный ресурсу, и вставьте тег TV в нужное место:

[[*subtitle]]

Звёздочка означает, что MODX должен взять значение из текущего ресурса. Например, тег можно поставить сразу после заголовка страницы:

<h1>[[*pagetitle]]</h1>
<p class="subtitle">[[*subtitle]]</p>

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

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

[[*subtitle:notempty=`<p class="subtitle">[[*subtitle]]</p>`]]

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

Шаг 4. Добавьте значение по умолчанию

Если редактор часто вводит одно и то же значение, откройте настройки TV и найдите поле значения по умолчанию. Например, можно указать «Подробное руководство».

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

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

Другие типы переменных

Список вариантов

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

Пример применения — поле «Тип материала» со значениями «Новость», «Обзор» и «Инструкция». Такой TV лучше свободного текста, если вы планируете фильтровать ресурсы по этому признаку.

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

Изображение

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

[[*cover:notempty=`<img src="[[*cover]]" alt="[[*pagetitle]]">`]]

Перед использованием на рабочем сайте проверьте, как именно ваша версия и медиасource возвращают путь к файлу. Если в результате получается не URL, а внутреннее значение, обратитесь к документации установленного типа TV и настройкам источника медиа.

Проверка: после выбора изображения браузер загружает файл без ошибки 404, а в исходном HTML указан корректный путь.

Если переменная не отображается

• В ресурсе нет поля TV. Проверьте привязку переменной к шаблону и шаблон, назначенный ресурсу. Это самая частая причина.
• На странице остался текст [[*subtitle]]. Убедитесь, что тег находится в поле шаблона или чанке, который действительно вызывается страницей. Затем очистите кеш.
• Значение сохранено, но посетитель видит старую версию. Очистите кеш MODX и кеш браузера. Если перед сайтом стоит CDN или прокси, проверьте и его кеш.
• Вместо картинки появляется битая ссылка. Посмотрите итоговый HTML и значение TV. Проверьте медиасource, права на файл и реальный путь к изображению.
• Поле исчезло после смены шаблона. TV привязана к старому шаблону. Добавьте новый шаблон в доступ переменной и снова откройте ресурс.

Что проверить перед публикацией

1. Имя TV написано без пробелов и совпадает с именем в теге.
2. Переменная привязана к каждому шаблону, где она нужна.
3. Тег установлен в реально используемом шаблоне или чанке.
4. Пустое значение не создаёт лишний HTML-блок.
5. Для изображений проверены URL, атрибут alt и доступность файла.
6. После изменения настроек очищен кеш MODX.

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

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

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