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

В MODX Revolution 3.x переменная шаблона (TV) может не показываться по четырём причинам: её не привязали к шаблону ресурса, в теге указали не то имя, перепутали плейсхолдер с TV или забыли передать значение в списке ресурсов. Ниже — короткая инструкция для новичка: за 15–20 минут вы создадите TV, выведете её на странице и проверите типичные места, где всё ломается.

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

• MODX Revolution 3.x с доступом в Manager.
• Шаблон, который назначен тестовой странице.
• Доступ к редактированию элементов и ресурсов.
• Название TV латиницей, например subtitle, без пробелов и кириллицы.

Проверяйте результат на опубликованном ресурсе. Внутри Manager значение может быть заполнено, но это ещё не означает, что тег попал в HTML страницы.

TV — это не отдельная страница и не переменная PHP. Это поле ресурса, которое MODX показывает только там, где знает текущий ресурс и правильное имя TV.

Пошаговая настройка TV

1. Создайте переменную. Откройте в Manager раздел «Элементы» → «Переменные шаблона» и создайте TV с именем subtitle. В поле «Тип ввода» выберите «Текстовая строка». В «Значении по умолчанию» можно указать резервный текст, но для первой проверки оставьте поле пустым.
   Проверка: TV появилась в списке, а её имя отображается как subtitle, без пробелов в начале и конце.
2. Привяжите TV к шаблону. Откройте вкладку доступа к шаблонам у созданной переменной и отметьте шаблон, который назначен вашей тестовой странице. Сохраните TV.
   Проверка: при повторном открытии ресурса в Manager появилось поле subtitle. Если поля нет, почти всегда выбран другой шаблон или TV не была привязана.
3. Заполните поле у ресурса. Откройте тестовую страницу, впишите текст в TV и сохраните ресурс. Не проверяйте результат только в форме редактирования — откройте страницу на сайте.
   Проверка: значение сохранилось после перезагрузки формы ресурса.
4. Выведите TV в шаблоне. Вставьте в HTML-шаблон или нужный чанк тег:

[[*subtitle]]

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

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

Пять ошибок, из-за которых TV не работает

1. Использован неправильный тип тега

Для значения текущего ресурса нужен тег с *:

[[*subtitle]]

Запись [[+subtitle]] обращается к плейсхолдеру, а не к TV текущей страницы. Она сработает только в контексте сниппета или чанка, который действительно передал такой плейсхолдер.

2. TV создана, но не привязана к шаблону

Создание переменной само по себе не добавляет её во все ресурсы. MODX показывает TV в форме редактирования только после привязки к назначенному шаблону. Проверьте обе стороны: какой шаблон установлен у ресурса и к какому шаблону подключена TV.

3. В теге указано имя поля, а не его системное имя

Название «Подзаголовок» в поле описания и системное имя subtitle — разные вещи. В вызове используется системное имя. Кавычки, пробелы и русские буквы в имени TV часто становятся источником незаметных ошибок, поэтому для новых переменных используйте латиницу, цифры и нижнее подчёркивание.

4. Вывод проверяют внутри списка ресурсов

На странице ресурса [[*subtitle]] знает, чьё поле нужно взять. В списке, который строит getResources, данные передаются через плейсхолдеры чанка. Минимальный вариант выглядит так:

[[getResources?
  &parents=`0`
  &includeTVs=`1`
  &tpl=`article-row`
]]

В чанке article-row значение обычно выводят так:

<h2>[[+pagetitle]]</h2>
<p>[[+tv.subtitle]]</p>

Свойства includeTVs и формат плейсхолдера относятся именно к выводу ресурсов через getResources; в обычном шаблоне страницы они не нужны.

5. Значение изменили, но видите старую страницу

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

Если не получилось

• На странице виден текст [[*subtitle]]. MODX не обработал тег. Проверьте, что он находится в шаблоне или чанке, который реально используется ресурсом, а не в обычном текстовом поле без обработки тегов.
• Страница открывается, но значение пустое. Проверьте системное имя TV, привязку к шаблону и сохранённое значение у ресурса. Затем очистите кэш.
• В Manager нет поля TV. У ресурса выбран другой шаблон либо переменная не привязана к текущему шаблону.
• В списке ресурсов пусто, а на самой странице TV работает. Для getResources добавьте &includeTVs=1 и используйте плейсхолдер [[+tv.subtitle]] в чанке.
• Вместо текста появляются HTML-теги. Значение содержит разметку, а шаблон выводит её как текст, либо TV настроена не тем типом ввода. Сначала проверьте значение в исходном HTML и не передавайте в TV код, если поле должно хранить обычный текст.

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

• Имя TV уникально и совпадает с именем в теге.
• TV привязана к нужному шаблону.
• У ресурса действительно выбран этот шаблон.
• Для одиночной страницы используется [[*имя_tv]].
• Для getResources включена передача TV и выбран правильный плейсхолдер.
• После изменения очищен кэш MODX.

Сноска: TV (Template Variable, «переменная шаблона») — дополнительное поле ресурса в MODX. Она хранит данные вроде подзаголовка, цены, изображения или цвета, но сама по себе не определяет, где это значение появится в HTML.

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

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