- Чем отличаются @FILE, file: и статические элементы
- Что нужно перед началом
- Настраиваем путь к файловым элементам
- Если нужен другой каталог
- Создаем каталоги и проверяем расположение файлов
- Файловый чанк со стандартными тегами MODX
- Подключение файлового чанка через Fenom
- Вызов через getChunk
- Вызов через include и file:
- Чанк из базы данных
- Вызов файлового сниппета
- Загрузка чанков и сниппетов из PHP
- MODX 2 и pdoTools 2.x
- MODX 3 и pdoTools 3.x
- Общая часть примера
- Как подключить файловый шаблон к ресурсу
- Наследование файловых шаблонов Fenom
- Файловые плагины и системные события
- Кеширование файловых элементов
- Что оставить в начале разработки
- Где находится кеш
- Если файловый элемент не загружается
- В журнале Could not find the element file
- Выводится код Fenom или возникает ошибка компиляции
- После изменения файла на странице старый результат
- Ошибка о недопустимом расширении
- Что делать дальше
В pdoTools можно хранить разметку чанков и код сниппетов в файлах, а затем подключать их из шаблонов и PHP-кода. Это удобно, если редактируете проект в IDE, используете поиск по файлам или сохраняете изменения в Git.
Ниже разберем два способа: загрузку через @FILE в pdoTools и файловый провайдер file: в Fenom. Покажу настройку каталога, передачу параметров, подключение шаблона к ресурсу и наследование.
Инструкция относится к MODX Revolution 2 и 3 с совместимой версией pdoTools. Файлы не требуют обязательного перехода на Fenom. Например, файловый чанк для pdoResources может содержать обычные теги MODX.
Чем отличаются @FILE, file: и статические элементы
У MODX и pdoTools есть несколько способов связать элемент с файлом. Они решают похожие задачи, но настраиваются и вызываются по-разному.
| Способ | Как работает | Где используется |
|---|---|---|
| Статический элемент MODX | В админке создается элемент, для которого включается хранение содержимого в файле. | Встроенный механизм MODX. Не требует Fenom только ради хранения кода в файле. |
@FILE |
pdoTools получает содержимое указанного файла и использует его как чанк или сниппет. | Методы pdoTools и параметры поддерживающих этот способ сниппетов, например tpl в pdoResources. |
file: |
Fenom загружает файл через свой файловый провайдер. | Конструкции include и extends в Fenom. |
В этой статье работаем с прямыми файловыми подключениями pdoTools. Для каждого подключаемого чанка не нужно дополнительно создавать одноименный чанк в админке.
Однако полностью отказаться от элементов в базе не получится. Шаблон назначается ресурсу по ID, а плагину нужны выбранные системные события. Ниже отдельно разберем эти ограничения.
Подробное сравнение способов организации кода есть в статье «Разработка на MODX: админка, файловые элементы и Fenom».
Что нужно перед началом
- Установленный pdoTools подходящей для вашей ветки MODX версии.
- Доступ к файлам проекта через файловый менеджер, SFTP или редактор.
- Тестовый ресурс и возможность редактировать его шаблон.
- Сохраненная копия изменяемого кода. Для работающего сайта — резервная копия файлов и базы.
Если используете только @FILE в параметре tpl у pdoResources и обычные теги MODX внутри файла, глобально включать Fenom не требуется.
Для конструкций {include ...}, {extends ...} и вызовов через $_modx понадобится настроенный Fenom. Если код находится непосредственно в шаблоне страницы, должна работать обработка страницы через pdotools_fenom_parser.
Расширенный доступ через pdotools_fenom_php и pdotools_fenom_modx для примеров этой статьи не нужен. Не включайте их только ради работы с файлами.
Настраиваем путь к файловым элементам
Откройте системные настройки MODX и найдите ключ pdotools_elements_path. Он задает базовый каталог, относительно которого pdoTools ищет файлы элементов.
Для основного примера оставим значение:
{core_path}elements/
При стандартном расположении ядра это каталог core/elements/. Если ядро находится в другом месте или переименовано, {core_path} указывает на его фактическое расположение.
Это серверный путь, а не публичный URL. В настройку не нужно записывать адрес вида https://example.ru/core/elements/.

Если на работающем сайте уже указан другой каталог, не меняйте его автоматически. От этого пути могут зависеть существующие вызовы. Сначала посмотрите, где лежат используемые файлы.
Если нужен другой каталог
Хранить элементы именно в core/elements/ необязательно. Например, для каталога template/tpl/ внутри корня установки можно явно указать:
{base_path}template/tpl/
Используйте завершающий слеш. Не путайте корень установки MODX с корнем всего хостинг-аккаунта.
В старых проектах встречается относительная запись template/tpl/. Ее разрешение зависит от реализации пакета. Для переноса конфигурации между проектами понятнее использовать явный путь с {base_path} или {core_path}.
Для этой инструкции путь не меняем: все следующие примеры рассчитаны на {core_path}elements/. На новом проекте сначала выберите одну структуру и используйте ее последовательно.
Создаем каталоги и проверяем расположение файлов
Откройте фактический каталог ядра MODX. Если папки elements нет, создайте ее. Внутри подготовьте каталоги:
chunks— разметка отдельных блоков.templates— файловые шаблоны страниц.snippets— PHP-код файловых сниппетов.plugins— PHP-код плагинов, если будете выносить его в файлы.
При обычном расположении ядра получится такая структура:
core/
└── elements/
├── chunks/
├── templates/
├── snippets/
└── plugins/
Папка plugins сама по себе не регистрирует плагины и не подписывает их на события. Пока это только место хранения кода.

Файлы создавайте в UTF-8. Включите отображение расширений и проверяйте, что файл называется my_chunk.tpl, а не my_chunk.tpl.txt.
Каталог ядра должен быть закрыт от HTTP-доступа. Для подключения файлов через pdoTools открывать его посетителям не нужно: PHP читает файлы на сервере. Проверка защиты разобрана в инструкции по безопасности MODX.
Изображения, CSS и JavaScript, которые должен получать браузер, в этот закрытый каталог не переносим. Серверные элементы и публичные файлы оформления выполняют разные задачи.
Файловый чанк со стандартными тегами MODX
Начнем без Fenom. В каталоге core/elements/chunks/ создайте файл resource_row.tpl и вставьте:
<p>
<a href="[[~[[+id]]]]">[[+pagetitle:htmlent]]</a>
</p>
Сохраните файл. Теперь в шаблоне тестовой страницы можно вызвать pdoResources:
[[!pdoResources?
&parents=`15`
&limit=`5`
&tpl=`@FILE chunks/resource_row.tpl`
]]
Замените 15 реальным ID раздела с опубликованными дочерними ресурсами. Если подходящего раздела нет, создайте на учебном сайте тестовый раздел и одну опубликованную страницу внутри него.
В параметре tpl записан путь относительно pdotools_elements_path. При выбранной настройке файл ищется здесь:
core/elements/chunks/resource_row.tpl
Создавать чанк resource_row в админке не нужно. Откройте тестовую страницу: должны появиться ссылки на найденные ресурсы.
Чтобы проверить именно загрузку файла, добавьте в resource_row.tpl короткий текст перед ссылкой, сохраните файл, очистите кеш MODX и обновите страницу.
@FILE поддерживается не любым вызовом чанка в MODX. В этом примере файл загружает pdoResources через pdoTools. Нельзя автоматически считать, что обычный вызов [[$@FILE ...]] или параметр стороннего дополнения работает так же.
Подключение файлового чанка через Fenom
Теперь создадим отдельный файл core/elements/chunks/my_chunk.tpl:
<p>Значение параметра: {$placeholder | escape}</p>
Он использует синтаксис Fenom. Для его обработки через pdoTools проверьте включение pdotools_fenom_default.
Вызов через getChunk
В шаблоне, обрабатываемом Fenom, вставьте:
{$_modx->getChunk('@FILE chunks/my_chunk.tpl', [
'placeholder' => 'value'
])}
Альтернативный вариант через модификатор:
{'@FILE chunks/my_chunk.tpl' | chunk : [
'placeholder' => 'value'
]}
Выберите один вызов. Если вставить оба, блок появится дважды. Ожидаемый результат:
Значение параметра: value
Вызов через include и file:
Для прямого подключения из Fenom используйте файловый провайдер:
{include 'file:chunks/my_chunk.tpl' placeholder='value'}
Он загрузит тот же файл. Для частей оформления и наследования внутри Fenom удобно использовать именно include и extends с file:.
Не путайте их с @FILE: file: — имя провайдера Fenom, а @FILE — указание pdoTools загрузить содержимое из файла.
Если в файле нужен обычный локальный параметр Fenom, обращайтесь к нему как к {$placeholder}. Не рассчитывайте, что include обрабатывает локальные плейсхолдеры [[+placeholder]] точно так же, как getChunk.
Чанк из базы данных
Если источник не указан, имя относится к обычному чанку:
{include 'my_chunk' placeholder='value'}
В таком случае чанк my_chunk должен существовать в админке. Наличие файла chunks/my_chunk.tpl не создает одноименный элемент в базе автоматически.
Вызов файлового сниппета
В каталоге core/elements/snippets/ создайте файл my_snippet.php. Вставьте в него:
<?php
$param = (string) $modx->getOption('param', $scriptProperties, '');
return 'Значение параметра: ' . htmlspecialchars(
$param,
ENT_QUOTES,
'UTF-8'
);
Это содержимое PHP-файла, поэтому здесь показан открывающий тег <?php. Закрывающий тег в конце не добавляем.
Сниппет получает параметр param и возвращает строку через return. Для такого прямого вызова отдельно создавать сниппет в админке не требуется.
В Fenom вызовите его методом microMODX:
{$_modx->runSnippet('@FILE snippets/my_snippet.php', [
'param' => 'value'
])}
Или через модификатор:
{'@FILE snippets/my_snippet.php' | snippet : [
'param' => 'value'
]}
Используйте один вариант. На странице должна появиться строка «Значение параметра: value».
Файловый PHP-код запускается через метод pdoTools. Не подключайте его как разметку через {include 'file:snippets/my_snippet.php'}: подключение шаблона и выполнение PHP-сниппета — разные операции.
Возможность вызвать доверенный файловый сниппет через $_modx не требует включать произвольные PHP-функции в Fenom. Но сам файл содержит исполняемый код. Право его редактировать должно быть только у доверенных разработчиков.
Загрузка чанков и сниппетов из PHP
Те же методы можно использовать внутри обычного сниппета или плагина MODX. Различается получение сервиса, а сами вызовы getChunk и runSnippet сохраняют знакомую форму.
MODX 2 и pdoTools 2.x
Для стандартной установки сервис можно получить так:
$pdoTools = $modx->getService('pdoTools');
Если проект использует собственный класс pdoTools, учитывайте принятый в нем способ инициализации. Не заменяйте его коротким примером автоматически.
MODX 3 и pdoTools 3.x
В проверенной реализации pdoTools 3 сервис зарегистрирован в контейнере MODX:
$pdoTools = $modx->services->get('pdotools');
Не копируйте в MODX 3 старые имена классов и пути model/ из инструкции для MODX 2. Сначала проверьте установленный выпуск пакета.
Общая часть примера
После строки получения сервиса используйте:
if (!$pdoTools) {
return '';
}
$chunk = $pdoTools->getChunk('@FILE chunks/my_chunk.tpl', [
'placeholder' => 'value'
]);
$snippet = $pdoTools->runSnippet('@FILE snippets/my_snippet.php', [
'param' => 'value'
]);
return $chunk . $snippet;
Если проверяете этот код в сниппете из админки, создайте отдельный тестовый сниппет. Вставьте строку получения сервиса для своей версии, затем общую часть, без открывающего PHP-тега. Сохраните и вызовите сниппет на тестовой странице.
Метод $modx->getChunk() и метод $pdoTools->getChunk() не взаимозаменяемы во всех возможностях. Поддержку @FILE в приведенном примере обеспечивает pdoTools.
Как подключить файловый шаблон к ресурсу
Шаблон ресурса остается элементом MODX. В админке он может содержать одну строку, которая передает оформление в файл.
- В каталоге
core/elements/templates/создайте файлbase.tpl. - Вставьте приведенный ниже код и сохраните файл.
- В админке создайте шаблон с названием
FileBase. - В его содержимое вставьте строку подключения файла.
- Назначьте шаблон
FileBaseтестовому ресурсу и сохраните ресурс. - Очистите кеш MODX и откройте тестовую страницу.
Содержимое файла templates/base.tpl:
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<title>{$_modx->resource.pagetitle | escape}</title>
</head>
<body>
<h1>{$_modx->resource.pagetitle | escape}</h1>
<main>
{block 'content'}
{$_modx->resource.content}
{/block}
</main>
</body>
</html>
Содержимое шаблона FileBase в админке:
{include 'file:templates/base.tpl'}
Для обработки этой строки в шаблоне страницы нужна настройка pdotools_fenom_parser = Да и работающий парсер pdoTools.
В результате должны появиться заголовок и содержимое тестового ресурса. Если поменять текст или разметку в base.tpl, после сохранения и проверки кеша изменения должны отобразиться на странице.
Файл не заменяет ID шаблона в базе. Именно элемент FileBase назначен ресурсу, а его оформление загружается с диска.
Это минимальная проверка подключения, а не готовая верстка сайта. Перенос CSS, JavaScript, изображений и создание полного каркаса разберем в уроке файловых шаблонов.
Наследование файловых шаблонов Fenom
Если общий каркас уже находится в templates/base.tpl, можно создать дочерний файл, который заменяет только нужные блоки.
Создайте core/elements/templates/page.tpl:
{extends 'file:templates/base.tpl'}
{block 'content'}
<p>Этот текст добавлен дочерним шаблоном.</p>
{parent}
{/block}
extends указывает родительский файл. Блок content заменяет одноименный блок родителя, а parent добавляет его исходное содержимое.
Для проверки создайте еще один шаблон MODX с названием FilePage и подключите в нем дочерний файл:
{include 'file:templates/page.tpl'}
Назначьте FilePage тестовому ресурсу. На странице должны появиться добавленный абзац и содержимое ресурса.
Не дублируйте в дочернем файле весь HTML-каркас только ради одного измененного блока. Шапку, подвал и общие подключения можно хранить в базовом шаблоне или отдельных файловых чанках.
Порядок конструкций имеет значение. В данном примере сначала указывается extends, затем определяются заменяемые блоки.
Файловые плагины и системные события
Сниппет можно вызвать напрямую из файла через pdoTools. Плагин отличается тем, что должен запускаться на определенных событиях MODX.
Поэтому размещение my_plugin.php в каталоге plugins само по себе не включает плагин. В админке нужно создать элемент плагина, включить его и назначить нужные события.
Дальше код можно связать с файлом через статический элемент MODX или оставить в элементе небольшую обертку, которая вызывает файловый код через pdoTools. Выбор зависит от организации проекта.
Не переносите все плагины в файлы автоматически. Сначала проверьте, какие события, параметры и зависимости использует конкретный плагин. Каталог plugins в нашей структуре пока только подготовлен для такого сценария.
Кеширование файловых элементов
Здесь важно разделять несколько механизмов:
- Кеш ресурса MODX может хранить уже собранный результат страницы.
pdotools_fenom_cacheуправляет кешированием скомпилированных чанков в интеграции pdoTools.- При использовании
file:Fenom также работает со своим файловым кешем компиляции и проверкой изменений. - Серверный кеш и CDN могут сохранять HTTP-ответ независимо от настроек MODX.
Файловый PHP-сниппет и скомпилированный шаблон Fenom — разные вещи. Не воспринимайте pdotools_fenom_cache как общий переключатель кеширования всего проекта.
Что оставить в начале разработки
Для первой проверки можно оставить pdotools_fenom_cache = Нет, а pdotools_fenom_options не менять. Сначала убедитесь, что пути, подключения и передача параметров работают правильно.
После изменения файла очистите кеш MODX и проверьте страницу. Не начинайте диагностику с удаления всего каталога core/cache.
Кешировать файлы Fenom с проверкой изменений
В документации pdoTools приведен вариант, при котором pdotools_fenom_cache остается выключенным, а файловый кеш Fenom настраивается отдельно через pdotools_fenom_options:
{
"force_compile": false,
"disable_cache": false,
"force_include": false,
"auto_reload": true
}
Эти параметры разрешают использование кеша Fenom и проверку изменений файлов. Но они не отменяют кеш готовой страницы MODX.
Если в pdotools_fenom_options уже есть другие параметры, не заменяйте весь JSON этим примером. Сначала разберитесь с существующими значениями и требованиями своей версии Fenom.
Это дополнительная настройка, а не обязательный шаг перед первым файловым чанком.
Где находится кеш
В рассмотренной реализации pdoTools 2.x базовый файловый кеш по умолчанию находится в core/cache/default/pdotools/. В проверенной реализации pdoTools 3.x используется другой базовый путь — core/cache/pdotools/. Настройка pdotools_cache_path и конфигурация проекта могут изменить расположение.
Поэтому не удаляйте каталог из чужого примера, не проверив фактический путь. Сначала используйте очистку кеша через админку. Если требуется отдельная очистка кеша Fenom, определите его каталог и удаляйте только соответствующие файлы кеша, а не исходники элементов.
Использование файлов, IDE или Fenom само по себе не гарантирует ускорение сайта. Эти инструменты в первую очередь меняют способ разработки и сопровождения.
Если файловый элемент не загружается
В журнале Could not find the element file
Проверьте:
- Значение
pdotools_elements_path. - Фактическое расположение файла на сервере.
- Путь после
@FILEилиfile:. - Регистр букв в имени каталога и файла.
- Расширение файла и завершающий слеш базового пути.
- Возможность чтения файла пользователем, от которого работает PHP.
Для вызова @FILE chunks/my_chunk.tpl при базовом пути {core_path}elements/ не нужно повторять core/elements/ внутри самого вызова.
Выводится код Fenom или возникает ошибка компиляции
Проверьте, где расположен вызов. Для кода в шаблоне страницы нужна обработка страницы, для чанков pdoTools — соответствующая обработка чанков. Также проверьте синтаксис и возможные конфликты фигурных скобок в inline JavaScript, CSS и JSON.
Подробная диагностика и сохранение исходников при ошибках разобраны в статье о Fenom. Не включайте расширенный доступ к PHP или MODX только ради устранения неизвестной ошибки.
После изменения файла на странице старый результат
Убедитесь, что редактируете файл именно этой установки и вызываете его из текущего шаблона. Затем проверьте кеш ресурса, настройки Fenom и внешнее кеширование.
Очистите кеш MODX и повторите запрос. Наличие файла на сервере не доказывает, что страница использует именно его: ресурс мог остаться на другом шаблоне.
Ошибка о недопустимом расширении
Для разметки в примерах используем .tpl, для PHP-сниппета — .php. pdoTools проверяет допустимые расширения с учетом типа элемента.
Не расширяйте список разрешенных файлов наугад. Убедитесь, что PHP-файл вызывается как сниппет, а не как чанк. Разрешение загрузить файл через медиаисточник и разрешение выполнить его как элемент — разные настройки.
Что делать дальше
После проверки у вас есть базовый каталог элементов, файловый чанк, пример PHP-сниппета и шаблон MODX, подключающий оформление из файла.
Дальше можно подготовить удобную работу с файлами проекта в редакторе или через админку. После этого переходите к созданию полного файлового каркаса и подключению оформления.
Эти механизмы можно использовать в разных проектах на MODX, а не только в одном курсе. При переходе между MODX 2 и MODX 3 сохраняйте понятную структуру, но отдельно проверяйте совместимость пакетов и PHP-кода.
Официальная документация компонента: файловые элементы pdoTools и парсер и интеграция Fenom.











