Как устроен MODX: ресурсы, шаблоны, чанки, сниппеты и файлы

Как MODX собирает страницу из ресурса, шаблона, чанков и сниппетов MODX Revo
В MODX содержание страницы хранится в ресурсе, оформление задается шаблоном, повторяемая разметка выносится в чанки, а PHP-логику выполняют сниппеты и плагины. Дополнительные поля TV позволяют хранить данные, которых нет в стандартных полях ресурса. Файлы оформления и дополнений находятся в каталогах проекта, а журнал ошибок при стандартной конфигурации - в core/cache/logs/error.log.

В MODX часто встречаются слова «ресурс», «шаблон», «чанк», «сниппет» и «TV». Если пока не работали с системой, они могут выглядеть как набор непонятных названий. Проще разобраться на одной странице: где хранится ее текст, откуда берется оформление и как подключаются общие блоки.

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

Основной маршрут и примеры интерфейса этого раздела подготовлены на MODX Revolution 2. Описанные базовые понятия применимы и к MODX 3. Значимые различия в расположении файлов отмечены отдельно.

Как MODX собирает страницу сайта

Представим обычный сайт услуг. На нем есть страница «Ремонт автомобилей»: заголовок, описание, изображение, меню, шапка и подвал.

В MODX эти части не обязательно хранить одним большим HTML-файлом. Система позволяет отделить содержание страницы от ее оформления и повторяемых блоков.

  1. Посетитель открывает адрес страницы. MODX определяет, какой ресурс нужно показать.
  2. У ресурса есть заголовок, содержание и другие поля. Для него назначен шаблон.
  3. Шаблон задает HTML-структуру и места, в которые подставляются данные ресурса.
  4. Через чанки подключаются повторяемые блоки, например шапка и подвал. Если нужен динамический вывод, используются сниппеты.
  5. MODX обрабатывает теги и отдает браузеру результат. Браузер загружает подключенные стили, скрипты и изображения.

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

Часть страницы Где ее описать
Название услуги и основной текст В полях ресурса
Общая HTML-структура страницы услуги В шаблоне
Повторяемая разметка шапки и подвала В чанках
Дополнительное изображение или отдельное значение для услуги В TV, если подходящего стандартного поля нет
Выборка страниц для списка услуг В сниппете
Действие при определенном событии, например после сохранения ресурса В плагине

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

Ресурсы: страницы и структура сайта

Ресурс — объект MODX, который представляет страницу или другой доступный по адресу объект. Самый распространенный тип ресурса — документ, то есть обычная страница сайта.

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

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

Основные поля ресурса

Поле Назначение
pagetitle Основной заголовок ресурса
longtitle Расширенный заголовок, который можно использовать отдельно от основного
introtext Аннотация или вводный текст
content Основное содержание
alias Псевдоним, используемый при формировании адреса
parent ID родительского ресурса
template ID назначенного шаблона

Заполнение поля еще не означает, что его значение появится на странице. Шаблон или другой используемый элемент должен вывести эти данные.

Например, заголовок выводится тегом [[*pagetitle]], а содержание — [[*content]]. Звездочка обозначает обращение к полю текущего ресурса или его TV.

Подробности разобраны в уроках о полях ресурсов и о создании страниц и разделов.

Другие типы ресурсов

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

Для первого обычного сайта чаще всего достаточно документов. Остальные типы используйте, когда для них появилась конкретная задача.

Элементы: оформление и логика

В отличие от ресурсов, элементы помогают собирать страницы и выполнять действия. Основные элементы находятся на вкладке «Элементы» в админке.

Шаблон

Шаблон задает оформление страницы: HTML-разметку, подключение стилей и скриптов, расположение общих блоков и места вывода данных.

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

Простейший фрагмент шаблона с выводом данных ресурса выглядит так:

<main>
  <h1>[[*pagetitle]]</h1>
  <div class="page-content">
    [[*content]]
  </div>
</main>

Это пример связи шаблона и ресурса, а не полный готовый шаблон сайта. В реальном проекте понадобятся остальная HTML-структура и подключение оформления.

Не путайте шаблоны страниц сайта с внутренними шаблонами админки. Использование Smarty внутри менеджера не означает, что обычный сайт на MODX обязательно нужно писать на Smarty.

Чанк

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

Если чанк называется Header, его можно подключить тегом [[$Header]]. Имя в вызове должно совпадать с именем созданного чанка.

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

Создание, вызов и свойства разобраны в уроке по чанкам.

Сниппет

Сниппет — PHP-код, который вызывается при обработке страницы или из другого кода. Например, он может выбрать ресурсы из базы данных, сформировать список материалов или обработать отправленную форму.

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

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

Подробные примеры находятся в уроке по сниппетам.

TV — дополнительное поле

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

TV связывается с шаблоном. В ресурсе с этим шаблоном заполняется значение поля, а в разметке оно выводится по имени TV.

Например, для TV с именем service_image используется тег [[*service_image]]. Само поле и его привязку нужно предварительно создать.

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

Плагин

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

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

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

Теги MODX: как распознать обращение

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

Пример Что означает
[[*pagetitle]] Поле текущего ресурса
[[*service_image]] TV с указанным именем, если оно создано и доступно для шаблона
[[$Header]] Вызов чанка
[[SnippetName]] Кешируемый вызов сниппета с указанным именем
[[!SnippetName]] Некешируемый вызов сниппета
[[++site_name]] Значение настройки
[[+value]] Плейсхолдер, значение которого предварительно задается кодом или вызываемым компонентом
[[~ID]] Ссылка на ресурс; вместо ID указывается его реальный числовой идентификатор
[[%lexicon_key]] Строка лексикона из загруженной темы

Имена Header, SnippetName, service_image и value здесь приведены для объяснения. Наличие примера в таблице не создает соответствующий элемент на сайте.

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

Подробности параметров, модификаторов и обработки тегов находятся в уроке по основному синтаксису MODX.

Где хранятся содержание и код

При обычной работе через админку данные ресурсов и код элементов хранятся в базе данных. Изображения, CSS, JavaScript и другие загруженные файлы находятся в файловой системе проекта.

Поэтому страница, которую вы видите в дереве ресурсов, не обязательно существует на сервере в виде отдельного HTML-файла. Ее ответ собирается из данных и элементов MODX.

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

Не путайте статический элемент со статическим ресурсом. В первом случае речь о хранении кода элемента в файле, во втором — о типе ресурса.

Место хранения кода и синтаксис также не одно и то же. Файловые элементы можно использовать со стандартными тегами MODX. Fenom — дополнительный вариант синтаксиса, а не обязательное условие работы с файлами.

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

Настройки, контексты и лексиконы

Системные настройки

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

Настройка — это пара «ключ — значение». Например, значение site_name можно вывести через тег [[++site_name]].

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

Контексты

Контекст объединяет ресурсы и настройки отдельной части проекта. По умолчанию сайт обычно работает в контексте web, а админка — в mgr.

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

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

Лексиконы

Лексикон — набор текстовых строк по ключам. Он используется для перевода интерфейса и текстов компонентов, а при необходимости — отдельных строк сайта.

Лексиконы группируются по языку, пространству имен и теме. Пространство имен помогает организовать данные компонента; его не следует путать с PHP-пространством имен классов.

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

Основные каталоги и файлы MODX

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

Структура каталогов MODX Revo

Путь Для чего нужен Что важно знать
index.php Точка входа для обработки запросов сайта Это не файл с HTML-разметкой всех страниц
assets/ Изображения, стили, скрипты и другие публичные файлы проекта Файлы оформления могут находиться и в других выбранных каталогах
assets/components/ Публичные файлы дополнений, например JavaScript, CSS и изображения Правки файлов пакета могут быть перезаписаны при его обновлении
core/ Ядро, конфигурация, кеш и служебные данные Не используйте его как место для публичной разметки и изображений
core/config/config.inc.php Конфигурация подключения к базе и другие параметры установки Содержит секретные данные; не публикуйте его содержимое
core/cache/ Файлы кеша MODX Не редактируйте их вместо исходных данных и элементов
core/cache/logs/error.log Стандартный файл журнала ошибок MODX Помогает диагностировать проблемы; фактическое расположение может быть настроено иначе
core/components/ Служебная часть дополнений: PHP-код, модели, процессоры и другие файлы Это не то же самое, что публичный каталог assets/components/
core/packages/ Транспортные пакеты установки и дополнений Не удаляйте содержимое массово только ради очистки места
core/lexicon/ Языковые файлы ядра Для собственных строк используйте предусмотренный механизм лексиконов, а не переписывайте файлы ядра
manager/ Файлы административной панели Название и адрес входа могут отличаться от стандартных
connectors/ Точки входа для запросов админки и других служебных операций Для создания обычных страниц редактировать их не требуется
setup/ Установщик и обновление CMS После завершения установки или обновления удалите каталог установщика
_build/ Материалы для сборки дистрибутива Для обычного создания страниц и шаблонов не нужны

Что отличается в MODX 3

В MODX 2 классы ядра обычно находятся в core/model/modx/. В MODX 3 основная кодовая база перенесена в core/src/Revolution/, а зависимости находятся в core/vendor/.

Кроме того, в MODX 3 каталог core должен оставаться в корне проекта и не переименовываться. Поэтому инструкции MODX 2 по переносу ядра нельзя автоматически повторять в третьей ветке.

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

Какие файлы не нужно править для оформления сайта

Для изменения внешнего вида обычных страниц работайте со своими шаблонами, чанками, CSS и JavaScript. Правка классов ядра, внутренних шаблонов менеджера или библиотек админки для этого не нужна.

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

Категории на вкладке «Элементы» помогают организовать элементы в админке. Они не создают автоматически каталоги на сервере и не являются разделами дерева ресурсов.

Где найти логи MODX и журнал ошибок

В стандартной конфигурации файлового логирования основной журнал MODX находится по пути:

core/cache/logs/error.log

Это путь относительно каталога проекта при стандартном расположении ядра. Если ядро MODX 2 перенесено или настройки логирования изменены, фактический путь может отличаться.

Просмотр журнала в админке

  1. Войдите в административную панель.
  2. В MODX 2 откройте «Управление» → «Отчеты» → «Журнал ошибок».
  3. Посмотрите последние записи, прежде всего соответствующие времени возникновения проблемы.
  4. Повторите действие, которое вызывает ошибку, и обновите журнал.
  5. Сравните новые записи с предыдущими: важен текст ошибки, время, указанный файл и строка.

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

Не пытайтесь открыть журнал по публичному адресу сайта. Служебные логи не должны быть доступны посетителям.

Что можно узнать из error.log

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

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

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

Почему журнал пустой, хотя ошибка есть

error.log MODX — не единственный журнал на сервере. Если PHP завершил выполнение до нормального запуска CMS, сведения могут оказаться в журнале PHP или веб-сервера. Ошибка JavaScript в браузере также не обязана записываться в журнал MODX.

Если ожидаемой записи нет, проверьте:

  • Возникает ли проблема повторно и когда именно.
  • Не изменены ли цель, уровень или расположение журнала MODX.
  • Есть ли у процесса PHP доступ на запись в нужный каталог.
  • Есть ли сообщения в журнале ошибок PHP или веб-сервера на хостинге.
  • Не относится ли проблема к JavaScript или загрузке файлов в браузере.

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

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

Что изучать дальше

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

Следующий вводный материал — FAQ по MODX перед началом работы. Он поможет определиться с версией системы и окружением. Если эти вопросы уже решены, переходите к скачиванию MODX и установке.

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

MODX Revolution для создания сайтов компаний, каталогов и разделов статей
← Предыдущая статьяЧто такое MODX Revolution и для каких сайтов она подходит
Следующая статья →FAQ по MODX: что нужно знать перед созданием сайта
Маршрут создания сайта на MODX: установка, шаблон, страницы, форма и запуск
Поделиться с друзьями
Алексей

Веб-дизайнер и SEO оптимизатор. Занимаюсь созданием сайтов с 2010 года и их продвижение с 2012 года!

Оцените автора
( 5 оценок, среднее 4.2 из 5 )
Web-Revenue.ru