Ресурсы, шаблоны и чанки в MODX: живой пример

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

Сначала договоримся о структуре

Представим небольшой сайт с каталогом товаров. У него есть главная страница, страница каталога и несколько карточек товаров. В MODX это не три вида HTML-файлов, а ресурсы в дереве сайта. Каждый ресурс получает шаблон, а при необходимости — собственные поля и содержимое.

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

• Создайте шаблон «Каталог» и назначьте его ресурсу каталога.
• Создайте чанки «SiteHeader», «SiteFooter» и «ProductCard».
• Добавьте дочерние ресурсы каталога для отдельных товаров.
• Проверьте страницу на опубликованном ресурсе, а не только в поле редактирования шаблона.

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

Чем отличаются ресурс, шаблон и чанк

Ресурс — запись в дереве сайта. Он хранит заголовок, псевдоним для адреса, содержимое и настройки публикации. Например, ресурс «Каталог» может открываться по адресу /catalog/, а ресурс «Кофемашина» — быть его дочерней страницей. Сам по себе ресурс не определяет весь внешний вид сайта.

Шаблон — каркас, который связывает разметку страницы с данными ресурса. В нём обычно размещают общую структуру документа, место для контента и вызовы повторно используемых блоков. Один шаблон можно назначить нескольким ресурсам.

Чанк — сохранённый фрагмент разметки или текста. Чанк не является отдельной страницей и сам по себе не получает адрес. Его вставляют в шаблон или другой элемент MODX тегом вида [[ChunkName]].

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

Плейсхолдер — место, куда MODX подставляет значение, например заголовок текущего ресурса. Тег [[*pagetitle]] означает «покажи pagetitle этого ресурса». Звёздочка здесь важна: без неё тег не обращается к полю текущего ресурса.

Собираем страницу каталога

1. Общая шапка и подвал

В чанке SiteHeader храните разметку шапки, которая повторяется на страницах. Например:

<header class="site-header">
  <a href="[[++site_url]]">Магазин</a>
  <nav aria-label="Основная навигация">
    <a href="[[~[[*id]]]]">[[*pagetitle]]</a>
  </nav>
</header>

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

Важно не путать системные настройки с полями ресурса. В примере [[++site_url]] обращается к системной настройке адреса сайта, а [[*pagetitle]] — к полю текущего ресурса.

2. Шаблон страницы

В шаблоне «Каталог» разместите общий каркас и вызовы чанков. Для примера достаточно такой разметки:

<!doctype html>
<html lang="ru">
<head>
  <meta charset="utf-8">
  <title>[[*pagetitle]] — Магазин</title>
</head>
<body>
  [[SiteHeader]]
  <main>
    <h1>[[*pagetitle]]</h1>
    [[*content]]
  </main>
  [[SiteFooter]]
</body>
</html>

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

Не вставляйте в ресурс целую HTML-страницу с собственными <html>, <head> и <body>, если шаблон уже задаёт каркас. Иначе получите вложенную разметку, которую браузер будет исправлять по собственным правилам.

3. Повторяемый блок товара

Создайте чанк ProductCard с разметкой одной карточки:

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

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

Сам чанк можно вызвать с параметрами так:

[[ProductCard?
  &title=`Кофемашина`
  &description=`Компактная модель для дома.`
  &url=`/catalog/coffee-machine/`
]]

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

Где хранить разметку: цена трёх подходов

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

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

Что ломается при сборке

• На странице показан тег вроде [[SiteHeader]]. Проверьте, что чанк существует, его имя написано без ошибки и вызов находится в области, которую обрабатывает MODX. Если на сайте подключён альтернативный парсер, сверяйтесь с его документацией.
• Изменения не видны после сохранения. Сначала проверьте, что вы редактировали элемент, используемый нужным ресурсом, и что ресурс опубликован. Затем очистите кэш средствами менеджера: кешированная страница может показывать прежний результат.
• Вместо значения виден плейсхолдер. Проверьте контекст. [[*pagetitle]] читает поле текущего ресурса, а [[+title]] ждёт установленный плейсхолдер или параметр вызова. Это не взаимозаменяемые формы.
• Карточка есть, но не ведёт на товар. Убедитесь, что в &url передан правильный адрес и соответствующий ресурс опубликован. Вручную заданный URL не обновится автоматически при смене псевдонима.
• На сайте включён Fenom. Не переносите примеры в Fenom-шаблон, не проверив синтаксис и настройки парсера: правила обработки тегов могут отличаться от стандартного синтаксиса MODX.

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

Создайте один тестовый ресурс и пройдите цепочку целиком: назначьте ему шаблон, вставьте в шаблон чанк, выведите заголовок через [[*pagetitle]], затем измените заголовок ресурса и проверьте результат на сайте. После этого добавьте второй ресурс с тем же шаблоном. Если обе страницы выглядят ожидаемо, общая структура отделена от содержимого правильно.

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