Общие параметры pdoTools

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

Параметры выборки ресурсов

Эти параметры определяют какие именно объекты будут получены из базы данных и по каким критериям будет производиться фильтрация.

Базовые параметры фильтрации

Параметр	По умолчанию	Назначение и советы
&class	modResource	Класс объектов. Можно указывать modUser, Ticket, msProduct и любые кастомные классы xPDO.
&parents	Текущий	ID родителей через запятую. 0 — весь сайт. -id исключает ветку. Совет: для скорости всегда ограничивайте родителей, если это возможно.
&depth	10	Глубина поиска. Если вам нужны только прямые потомки, ставьте 0.
&resources	—	Список ID через запятую. -id исключает ресурс. Приоритет выше, чем у &parents.
&templates	—	Фильтр по ID шаблонов. -id исключает ресурсы с этим шаблоном.
&context	—	Фильтрация по контексту (web, catalog и т.д.).

Если поставить &parents=0, выборка не будет ограничиваться конкретными родителями и возьмет ресурсы со всего сайта. Когда ID родителя или ресурса начинается с дефиса (минуса), такой элемент и его потомки исключаются из выборки.

Управление видимостью контента

Параметр	По умолчанию	Назначение и советы
&showHidden	0	Показывать ресурсы со снятой галочкой «Показывать в меню».
&showUnpublished	0	Показывать неопубликованные (для режимов предпросмотра).
&showDeleted	0	Показывать удаленные ресурсы
&hideContainers	0	Скрывать папки (isfolder = 1).
&hideUnsearchable	—	Отключает вывод ресурсов спрятанных от поиска

Эти параметры критически важны при работе с закрытыми разделами сайта или при выводе определенных типов контента.

Расширенные SQL-параметры

Параметр	По умолчанию	Назначение и советы
&select	—	Киллер-фича. Список полей для выборки. Пример: {"modResource":"id,pagetitle"}. Экономит память, не выбирая тяжелый content, если он не нужен .
&leftJoin,&rightJoin, &innerJoin	—	Аналоги SQL операторов LEFT JOIN, RIGHT JOIN и INNER JOIN. Позволяет делать сложные связи без написания PHP кода.
&joinSequence	innerJoin,leftJoin,rightJoin	Порядок подключения таблиц через запятую

Параметр &where позволяет создавать сложные условия фильтрации, включая работу с TV-параметрами. Например, для фильтрации по нескольким ТВ одновременно используется JSON-формат с логическими операторами. Пример: {"Data.price:>":100, "OR:Data.favorite:=":1}.

Сортировка и группировка

Параметр	По умолчанию	Назначение и советы
&sortby	pagetitle	Поле сортировки. Можно указывать JSON массив {"publishedon":"DESC", "pagetitle":"ASC"}. Поддерживает сортировку по TV (автоматически джойнит их).
&sortdir	ASC	Направление сортировки: ASC (по возрастанию) или DESC (по убыванию)
&groupby	—	Поле по которому группируются результаты
&having	—	Условие для ограничения выборки сгруппированных строк
&limit	0	Лимит выборки. 0 — без лимита (будьте осторожны на больших базах).
&offset	0	Пропуск результатов от начала выборки

В параметре &sortby можно указать JSON строку с массивом нескольких полей для многоуровневой сортировки. Для случайной сортировки укажите значение RAND().

Работа с TV-параметрами

Параметр	Значение по умолчанию	Описание
&includeTVs	—	Список названий TV параметров через запятую для выборки
&includeTVList	—	Псевдоним параметра &includeTVs
&prepareTVs	1	Подготовка ТВ с файлами для генерации полных путей
&processTVs	—	Обработка ТВ согласно их настройкам в админке
&tvPrefix	tv.	Префикс для ТВ параметров в плейсхолдерах

Если установить &prepareTVs=1, будут подготовлены все ТВ указанные в &includeTVs. Параметр &processTVs замедляет работу, поэтому используйте его только когда действительно нужна обработка значений согласно типу ТВ.

Фильтрация по TV-параметрам

Параметр	Значение по умолчанию	Описание
&tvFilters	—	Список фильтров по ТВ с разделителями AND и OR. Пример: tvname==value. Очень мощный инструмент, но требовательный к ресурсам БД.
&tvFiltersAndDelimiter	,	Разделитель для условий AND в &tvFilters
&tvFiltersOrDelimiter	|	Разделитель для условий OR в &tvFilters
&sortbyTV	—	Дополнительное поле ТВ для сортировки. Можно напрямую указать в параметре &sortby
&sortdirTV	—	Направление сортировки по TV полю. Можно напрямую указать в параметре &sortby
&sortbyTVType	—	Тип сортировки: string, integer, decimal или datetime. Если пусто, то ТВ будет отсортирован в зависимости от его типа: как текст, число или дата.

Параметр &tvFilters позволяет создавать сложные фильтры с логическими операторами. Разделитель из &tvFiltersOrDelimiter группирует условия в первую очередь, затем внутри каждой группы работает разделитель из &tvFiltersAndDelimiter. При сортировке по числовому ТВ нужно явно указать тип через &sortbyTVType для корректной работы.

Дополнительные параметры

Параметр	Значение по умолчанию	Описание
&first	1	Номер первой итерации вывода результатов
&last	Автоматически	Номер последней итерации по формуле (total + first — 1)
&loadModels	—	Загрузка пакетов xPDO (например, ms2gallery) для использования их таблиц в &where или &leftJoin.
&checkPermissions	—	Проверка разрешений пользователя при выводе объектов.
&disableConditions	—	Отключает специфичные для modResource параметры выборки
&fenomModifiers	—	Список сниппетов-модификаторов через запятую для Fenom. Подробности в соответствующем разделе.

Параметр &loadModels используется когда нужно работать с данными сторонних компонентов, например &loadModels=ms2gallery,msearch2.

Параметры шаблонов

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

Основные шаблоны

Параметр	Описание
&tpl	Имя чанка для оформления каждого ресурса в результатах. Если не указан, то содержимое полей ресурса будет распечатано на экран.
&tplFirst / &tplLast	Уникальные шаблоны для первого и последнего элемента (полезно для CSS классов границ).
&tplOdd	Имя чанка для каждого четного ресурса (несмотря на название «odd»)
&tpl_N	Имя чанка для N-го ресурса, например &tpl_5=`tpl5th`. Идеально для вставки баннеров в списки.
&tpl_nN	Имя чанка для каждого N-го ресурса, например &tpl_n4=`tplEvery4th`
&outputSeparator	Необязательная строка для разделения результатов работы (например, <hr>).

Если параметр &tpl не указан, содержимое полей ресурса будет распечатано на экран в виде массива.

Условные шаблоны

Параметр	Описание
&tplCondition	Поле ресурса из которого берется значение для выбора чанка по условию в &conditionalTpls.
&tplOperator	Необязательный оператор для сравнения поля ресурса в &tplCondition с массивом значений и чанков в &conditionalTpls.
&conditionalTpls	JSON строка с массивом, у которого в ключах указано то, с чем будет сравниваться &tplCondition, а в значениях — чанки, которые будут использованы для вывода, если сравнение будет успешно. Оператор сравнения указывается в &tplOperator. Для операторов типа isempty можно использовать массив без ключей.

Параметр &conditionalTpls позволяет использовать разные шаблоны в зависимости от значения определенного поля ресурса. Это удобно когда нужно выводить элементы разных типов в одном списке.

Параметры результатов

Эти параметры дополнительно определяют какие данные и каким способом будут выводиться на страницу.

Настройки вывода данных

Параметр	Значение по умолчанию	Описание
&return	chunks	Формат возврата: chunks (HTML), json (для API), data (PHP массив), sql (только запрос для отладки).
&fastMode	0	Быстрый режим обработки чанков с вырезанием необработанных тегов.
&nestedChunkPrefix	pdotools_	Префикс для быстрых плейсхолдеров при включенном &fastMode.
&idx	—	Стартовый номер итерации вывода результатов.
&totalVar	total	Имя плейсхолдера для сохранения общего количества результатов.

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

Работа с контентом

Параметр	Значение по умолчанию	Описание
&includeContent	0	Включаем поле content в выборку.
&prepareSnippet	—	Сниппет который принимает данные перед выводом в чанки может их менять или добавлять.
&decodeJSON	—	Разбирает поля типа JSON вместо вывода строкой.
&scheme	-1	Схема формирования URL передается в modX::makeUrl(). Возможные варианты смотрете здесь.
&useWeblinkUrl	—	Генерировать ссылку с учетом класса ресурса.

Параметр &prepareSnippet очень полезен когда нужно изменить или добавить данные перед их выводом. Сниппет-обработчик получает массив данных, может его модифицировать и должен вернуть результат в виде сериализованного массива.

Дополнительные плейсхолдеры

Параметр	Описание
&toSeparatePlaceholders	Выставляет результаты в разные плейсхолдеры с указанным префиксом
&additionalPlaceholders	Устанавливает дополнительные плейсхолдеры для использования

Если указать слово в параметре &toSeparatePlaceholders, все результаты будут выставлены в отдельные плейсхолдеры начинающиеся с этого слова и заканчивающиеся порядковым номером от нуля. Например &toSeparatePlaceholders=myPl создаст плейсхолдеры [[+myPl0]], [[+myPl1]] и так далее.

Настройки кеширования

Параметр	Значение по умолчанию	Описание
&cache_key	resource или default	Ключ кеширования из системных настроек
&cache_handler	xPDOFileCache	Обработчик кеша из системных настроек
&cacheTime	0 (вечный)	Время жизни кеша в секундах

Правильная настройка кеширования существенно повышает производительность сайта на MODX Revo.

Возвращаемые значения

PdoTools умеет возвращать данные в разном виде в зависимости от параметра &return. Это используют сами сниппеты для внутренних нужд, но можно указывать вручную в pdoResources и pdoUsers.

Типы возвращаемых значений

Значение	Описание
chunks	Оформленные чанки по умолчанию.
sql	Подготовленный сырой SQL для отладки без выполнения запроса.
data	Готовый массив данных для использования в своих сниппетах.
ids	Только идентификаторы документов через запятую.
json	Массив данных в формате JSON строки.
serialize	Массив данных сериализованной строкой.

Значение data имеет смысл использовать только при прямом вызове pdoFetch::run() из своего сниппета, иначе вы получите строку Array. Значение serialize иногда может вызвать нехватку памяти, лучше использовать json.

[[!pdoResources? &parents=`0` &return=`json` ]]

Совместимость сниппетов

Все значения параметра &return понимают только pdoResources (pdoPage в связке с pdoResources) и pdoUsers. Значения chunks и data понимают pdoMenu и pdoCrumbs. Остальные сниппеты из пакета понимают в основном лишь chunks.

Параметр &returnIds автоматически использует тип ids для возврата списка идентификаторов. Это удобно для подстановки в качестве параметра другим сниппетам модекса.

Способы вызова чанков

Все чанки в PdoTools могут использоваться с различными префиксами для гибкости работы.

Инлайн-чанки (@INLINE или @CODE)

В качестве шаблона используется код указанный непосредственно после префикса. В INLINE чанках нельзя использовать обычные теги MODX [[+]] для сниппетов и других чанков, потому что парсер обработает их в первую очередь. Вместо этого используйте синтаксис {{+}} который pdoTools конвертирует автоматически.

[[!pdoResources? &parents=`0` &tpl=`@INLINE <li>{{+pagetitle}}</li>` ]]

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

Файловые чанки (@FILE)

Вместо чанка из базы данных используется содержимое файла с расширением .tpl или .html. Путь до файла указывается в системной настройке pdotools_elements_path.

[[!pdoResources? &tpl=`@FILE fileBasedRow.tpl` ]]

Этот способ особенно удобен при работе с системами контроля версий.

Шаблоны ресурсов (@TEMPLATE)

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

[[!pdoResources? &tpl=`@TEMPLATE 10` ]]

Обычные чанки (@CHUNK)

Аналогично простому указанию имени чанка из базы данных, префикс оставлен для совместимости со сторонними сниппетами.

[[!pdoResources? &tpl=`@CHUNK tpl.Resource.row` ]]

Использование без префикса работает точно так же.

Практические примеры использования

Вывод списка новостей с фильтрацией по TV и сортировкой по дате публикации в обратном порядке:

[[!pdoResources? &parents=`5` &includeTVs=`image,tags` &tvPrefix=`` &sortby=`publishedon` &sortdir=`DESC` &limit=`10` &tpl=`@INLINE <article><img src="{{+image}}"><h2>{{+pagetitle}}</h2></article>` ]]

Использование prepareSnippet для модификации данных перед выводом:

[[!pdoResources? &parents=`0` &includeTVs=`price` &prepareSnippet=`calculateDiscount` &tpl=`productRow` ]]

Фильтрация по нескольким TV параметрам одновременно через параметр where:

[[!pdoResources? &includeTVs=`image,file,status` &where=`{ "TVimage.value:LIKE":"%photo.jpg%", "OR:TVfile.value:=": "1", "OR:TVstatus.value:!=": "" }` ]]