Чанки в MODX: что понять сразу перед первой настройкой

За 15–20 минут вы создадите первый чанк в MODX Revolution 3.x, вызовете его на странице и научитесь отличать ошибку синтаксиса от закешированного результата. Главное, что нужно понять сразу: чанк хранит разметку, но не выполняет PHP-код. Если смешать его со сниппетом или шаблоном, сайт начнёт отдавать не то, что вы ожидаете.

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

Инструкция рассчитана на MODX Revolution 3.x. В MODX Revolution 2.8 синтаксис тегов в основном тот же, но названия пунктов интерфейса и внешний вид панели управления могут отличаться.

• доступ к админке MODX с правом создавать и изменять элементы;
• тестовую страницу, на которой можно проверить результат;
• простой редактор кода, если вы будете вставлять HTML в чанк;
• понимание, где находится нужный контекст сайта, если у вас несколько контекстов.

Чанк — это сохранённый фрагмент HTML, текста или MODX-тегов, который можно вызвать в шаблоне, поле ресурса или другом элементе. Сниппет, напротив, предназначен для выполнения серверной логики. Тег ресурса вроде [[*pagetitle]] подставляет значение поля текущей страницы.

Плейсхолдер^[1] — именованное значение, которое MODX подставляет в нужное место во время обработки страницы.

Чанк отвечает на вопрос «какую разметку повторять», а сниппет — «какие данные получить или обработать».

Шаг 1. Создайте чанк с повторяемой разметкой

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

Вставьте в поле содержимого полный фрагмент:

<aside class="site-notice">
  <p>Доставка по России от 3000 ₽ — бесплатно</p>
</aside>

Сохраните элемент. На этом шаге PHP не нужен: MODX просто хранит текст и отдаёт его там, где чанк вызван.

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

Шаг 2. Вызовите чанк в шаблоне или ресурсе

Откройте шаблон страницы или поле содержимого тестового ресурса и добавьте тег:

[[SiteNotice]]

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

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

<footer class="page-footer">
  [[SiteNotice]]
  <p>© [[++site_name]]</p>
</footer>

Здесь [[++site_name]] — системная настройка MODX, а не поле текущего ресурса. Она берётся из настроек сайта.

Проверка: в браузере виден блок уведомления, а в HTML-источнике страницы нет текста [[SiteNotice]].

Шаг 3. Сделайте чанк зависимым от текущей страницы

Чанк может содержать стандартные MODX-теги. Например, создайте PageHeading:

<header class="page-heading">
  <h1>[[*pagetitle]]</h1>
  <p>[[*longtitle]]</p>
</header>

Тег со звёздочкой читает поле текущего ресурса. Если поле longtitle пустое, абзац останется пустым — это не ошибка чанка.

Для значения по умолчанию используйте условный вывод через модификатор:

<h1>[[*longtitle:default=`[[*pagetitle]]`]]</h1>

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

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

Шаг 4. Передайте параметры через плейсхолдеры

Один чанк не обязан быть привязан к одному тексту. Создайте Button с параметрами:

<a class="button [[+class]]" href="[[+url]]">[[+label]]</a>

Вызовите его в ресурсе или шаблоне:

[[Button? &class=`button-primary` &url=`/catalog/` &label=`Перейти в каталог`]]

После имени чанка стоит знак вопроса, а параметры отделяются пробелами. Значение каждого параметра заключено в обратные кавычки. Внутри чанка параметр доступен как плейсхолдер с плюсом: [[+label]].

Не передавайте таким способом непроверенный пользовательский HTML, JavaScript или URL из формы. Чанк не превращает входные данные в безопасные автоматически. Для данных посетителей нужны валидация, экранирование и понятная политика вывода.

Проверка: на странице отображается ссылка с текстом «Перейти в каталог», классом button-primary и адресом /catalog/.

Шаг 5. Добавьте модификатор вывода только там, где он нужен

MODX умеет менять значение после получения поля. Например:

<p class="phone">[[++contact_phone:escape]]</p>

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

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

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

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

• На странице виден текст [[SiteNotice]]. Проверьте точное имя чанка, регистр букв и место вызова. Затем очистите кэш MODX и обновите страницу без кэша браузера.
• Вместо параметров остаются [[+label]] и [[+url]]. Чанк вызван без нужных параметров или их имена не совпадают. Сравните &label с [[+label]] посимвольно.
• Показывается старый HTML. Сначала сохраните чанк, затем очистите кэш сайта. Если перед вами кэш CDN или серверный кэш хостинга, его нужно сбрасывать отдельно.
• На странице пусто, хотя тег написан правильно. Проверьте права доступа к ресурсу и чанк в нужном контексте. Также убедитесь, что фрагмент не скрыт CSS-правилом.
• HTML ломает соседний блок. Ищите незакрытый тег, кавычку или вложенный интерактивный элемент. Чанк вставляется в страницу как обычная разметка и может нарушить DOM.

Где чанки начинают мешать

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

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

Инвалидация кэша и настройка кэширования динамических элементов — отдельная тема; здесь важно помнить только одно: сохранение чанка не гарантирует, что уже закэшированная страница немедленно изменится.

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

Создайте на тестовом сайте три небольших элемента: SiteHeader, PageHeading и Button. Для каждого проверьте вызов, параметры и отображение на двух разных ресурсах. Затем откройте HTML-источник страницы и убедитесь, что в нём не осталось сырых тегов MODX. На рабочем проекте после публикации следите за временем ответа и количеством кэшированных страниц: слишком крупные или глубоко вложенные чанки усложняют разбор проблем, хотя сами по себе обычно не заменяют серверную логику.

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