Чанки в MODX: рабочие приёмы без лишней магии

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

Сначала определите роль чанка

Чанк — это элемент MODX, который обычно хранит повторяющийся фрагмент разметки: карточку товара, пункт меню, блок контактов или часть шаблона. Сам по себе он не обязан получать данные из базы. Это отличает его от сниппета: сниппет выполняет серверный код, а чанк в типичном сценарии формирует представление из уже переданных значений.

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

Хороший чанк отвечает за форму вывода. Чем больше в нём условий, запросов и скрытой логики, тем ближе он к плохо замаскированному контроллеру.

Три рабочих подхода

1. Чанк как переиспользуемый фрагмент

Это базовый вариант для одинаковой разметки. В чанке оставляют HTML и плейсхолдеры, а перед вызовом устанавливают значения. Например, элемент с именем tpl.card может выглядеть так:

<article class="card">
  <h3>[[+title]]</h3>
  <p>[[+description]]</p>
  <a href="[[+url]]">Подробнее</a>
</article>

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

2. Чанк как часть шаблона

Хедер, футер, блок cookie-уведомления и повторяющаяся навигация часто выносятся из шаблона документа. Вызов выглядит так:

[[tpl.header]]

<main>
  [[*content]]
</main>

[[tpl.footer]]

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

3. Чанк с параметрами вызова

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

[[tpl.notice?
  &title=`Важная информация`
  &text=`Проверьте адрес доставки перед оплатой`
]]

Внутри чанка эти значения доступны как плейсхолдеры [[+title]] и [[+text]]. Для коротких значений такой подход читабелен. Длинные тексты, JSON и вложенную разметку лучше хранить в ресурсах, TV-полях или отдельной структуре данных, а не превращать вызов чанка в многострочный конфиг.

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

Обычный тег MODX может использовать кешированный результат страницы. Вызов с восклицательным знаком — [[!element]] — просит выполнить элемент без использования кеша страницы. Это не означает, что любой результат мгновенно станет актуальным во всех слоях кеширования: браузер, CDN, серверный кеш и кеш запросов могут жить по своим правилам.

Для статичного чанка в шапке сайта обычно достаточно обычного вызова:

[[tpl.header]]

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

[[!tpl.personal-message]]

Но такой вызов не превращает обычный чанк в персональный компонент. Если внутри нет механизма, который получает данные пользователя, результат будет тем же самым. Некешируемый вызов также увеличивает работу сервера на каждом обращении, поэтому ставить ! «на всякий случай» — плохая практика.

Как передавать данные без путаницы

Разделяйте источники значений

В MODX встречаются разные типы плейсхолдеров. [[*pagetitle]] обращается к полю текущего ресурса, [[+title]] — к обычному плейсхолдеру, который установил сниппет или другой элемент. Если перепутать эти формы, чанк может быть технически исправен, но получить пустое значение.

Для одного чанка заранее определите контракт: какие значения он ожидает, обязательны ли они и что показывать при отсутствии данных. Например, карточка может требовать title и url, а описание считать необязательным. Это стоит записать в комментарии элемента или в документации проекта, а не держать в памяти команды.

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

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

Статические чанки: когда они оправданы

Статический чанк связан с файлом, а не только с содержимым в базе. Это полезно, когда разметку нужно хранить в Git и менять через привычный процесс ревью. Особенно хорошо такой режим подходит для больших шаблонных фрагментов, которые редактируют разработчики.

Перед включением статического режима проверьте путь к файлу, права веб-сервера и поведение окружений. Локальный путь может работать на компьютере разработчика и не существовать на тестовом сервере. Если редактор меняет чанк в админке, а файл остаётся прежним, команда получает две версии одного элемента — это источник трудноуловимых расхождений.

Что ломается чаще всего

• На странице виден текст [[+name]]. Плейсхолдер не был установлен, назван иначе или вызывается вне области видимости, где он создаётся.
• Чанк выводит пустой блок. Проверьте имя элемента, активность чанка, выбранный контекст и наличие обязательных значений.
• Изменения не видны. Очистите кеш MODX и отдельно проверьте кеш браузера, CDN или reverse proxy. Некешируемый вызов не отменяет все остальные кеши.
• HTML ломается после подстановки. В значении может быть кавычка, перенос строки или неэкранированный пользовательский ввод. Проверьте, где и как формируется значение.
• Один чанк показывает разные данные в разных местах. Ищите совпадающие имена плейсхолдеров и порядок их установки. Переименуйте слишком общие значения вроде title, если на странице несколько независимых источников.

Когда какой вариант выбирать

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

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

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

Возьмите один повторяющийся блок проекта и опишите его контракт: имя чанка, обязательные плейсхолдеры, источник каждого значения, режим кеширования и ожидаемый HTML. Затем проверьте страницу с очищенным кешем и без него, а в продакшене измерьте время ответа после добавления некешируемых вызовов. Инвалидация кеша и настройка Fenom — отдельные темы; здесь важнее сначала убрать неявные зависимости.

Плейсхолдер — специальная метка MODX, которую система или сниппет заменяет значением во время обработки страницы. Символ * обычно указывает на поле текущего ресурса, а + — на временное значение, переданное в контекст выполнения.