pdoTools в MODX: как собирать списки ресурсов без ошибок

Вызов pdoResources может выглядеть коротким, а результат — оказаться дорогим: страницы каталога загружаются медленно, TV-поля пустые, а пагинация показывает повторяющиеся ресурсы. В pdoTools для MODX Revolution 2.x и 3.x важно не только выбрать сниппет, но и ограничить выборку, правильно обработать TV и вынести разметку в управляемый шаблон. Ниже — рабочие приёмы для pdoResources; точную совместимость установленной версии пакета проверьте в документации.

Сначала определите, что именно должен вернуть список

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

Перед настройкой проверьте версию pdoTools в менеджере пакетов и убедитесь, что сниппет доступен. Примеры ниже используют синтаксис тегов MODX Revolution, знакомый по pdoTools 2.x. В разных выпусках и сборках могут отличаться детали: сверяйте параметры с документацией именно установленной версии.

• Запишите ID родительского ресурса и нужный лимит.
• Решите, какие поля попадут в карточку: например, заголовок, дату публикации и изображение.
• Подготовьте чанк карточки в Elements, если разметка должна повторно использоваться или редактироваться из менеджера.
• Проверьте, что тестовые ресурсы опубликованы, не удалены и доступны по заданным условиям.

Шаблон карточки: чанк или @INLINE

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

Пример вызова pdoResources с чанком catalog.row:

[[!pdoResources?
  &parents=`12`
  &tpl=`catalog.row`
  &limit=`12`
  &sortby=`publishedon`
  &sortdir=`DESC`
  &includeTVs=`image`
  &processTVs=`1`
]]

В чанке используйте плейсхолдеры ресурса, например [[+id]] и [[+pagetitle]], а для TV — имя поля, если оно включено в выборку. Перед публикацией проверьте итоговую разметку: если значение TV отсутствует у части ресурсов, задайте в шаблоне запасной вариант, а не рассчитывайте на то, что поле всегда заполнено.

Цена выбора: чанк проще сопровождать, но для одной короткой строки он добавляет отдельный элемент в структуру проекта. @INLINE быстрее написать, однако длинная HTML-разметка внутри вызова ухудшает читаемость и сложнее проверяется.

Не загружайте TV без необходимости

TV — дополнительные поля ресурсов. Их выборка и обработка увеличивают объём работы, особенно если список большой или на странице несколько вызовов сниппета. Указывайте в &includeTVs только те имена TV, которые реально нужны шаблону.

Параметр &processTVs нужен, когда требуется обработанное значение TV, например корректно подготовленный путь к изображению. Не включайте его автоматически для всех списков: сначала проверьте результат на конкретных данных. Если изображение хранится в TV с нестандартным типом или настройками, итоговое значение зависит от конфигурации поля.

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

Фильтры и пагинация: не смешивайте разные задачи

Условия выборки задавайте параметрами pdoResources, а не выводите все записи и не прячьте лишние карточки через CSS. Для простого списка с фиксированным лимитом хватит pdoResources. Если нужен постраничный каталог, используйте связку pdoPage и pdoResources, следуя документации установленной версии: pdoPage управляет страницами выдачи, а pdoResources формирует ресурсы.

Не копируйте готовый набор фильтров из чужого сайта без проверки. Параметры, которые меняют WHERE-условия, сортировку и глубину выборки, зависят от структуры ваших ресурсов и могут дать пустой результат, если ID родителей или значения полей отличаются.

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

Список пустой

Проверьте ID в &parents, публикацию ресурсов и параметры, ограничивающие выборку. Для диагностики временно упростите вызов: оставьте родителя, шаблон и небольшой лимит, затем возвращайте фильтры по одному. Так проще найти условие, которое исключает все записи.

TV не выводится или показывает не то

Сверьте точное имя TV, включено ли оно в &includeTVs, и что именно возвращает поле. Проверьте ресурс с заполненным значением и ресурс без него. Для изображений не предполагайте, что значение всегда является готовым URL: это зависит от типа и настроек TV.

Карточки повторяются или пагинация ведёт себя странно

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

Страница стала медленнее

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

Как выбирать подход

• Для одной простой подборки используйте pdoResources с явным родителем, лимитом и чанком.
• Если карточка должна выводить TV, включите только необходимые поля и проверьте обработанное значение.
• Если посетителю нужны страницы каталога, подключайте pdoPage и проверяйте навигацию вместе с фильтрами.
• Если список тормозит, сначала измерьте время ответа и сократите выборку; не добавляйте кеширование вслепую.

TV (Template Variable) — дополнительное поле ресурса MODX, например для изображения, цены или краткой подписи. Его значение не всегда готово к выводу без учёта типа поля и обработки.

Что проверить дальше

На тестовой странице сравните результат до и после изменения вызова: количество карточек, значения TV, порядок сортировки и переходы пагинации. Затем измерьте время ответа на каталоге с реальным объёмом ресурсов. Если проблема остаётся, проверьте запросы и настройки кеширования по документации вашей версии pdoTools, а не добавляйте параметры наугад.