• Заметки

    • MODX. Вывод списка ресурсов на сайте с использованием pdoResources

    Меню

    Отредактировано: 10 Февраля 2023

    pdoResources — это улучшенная версия getResource, сниппета для вывода ресурсов (страниц) сайта на MODX Revolution. 

    Для перехода с getResources на pdoResources в большинстве случаев достаточно просто поменять префикс get на pdo в вызове.

    Использование pdoResources

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

    Fenom
    Теги MODX
    {'pdoResources' | snippet : [
   'parents' => $_modx->resource.id,
   'tpl' => 'chunk1',
]}
    [[pdoResources?
    &parents=`1`
    &tpl=`chunk1`
]]
    • parent — ID ресурса с которого отсчитывать вывод ресурсов;
    • tpl — это шаблон ресурса;

    Параметр parent можно указывать следующими путями:

    • parent=`1` — непосредственно номер ресурса;
    • parent=`[[*id]]` — id текущего ресурса;

    В качестве шаблона можно указать чанк, или использовать инлайновую запись

    &tpl=`@CODE: <h1>[[*pagetitle]]</h1>`

    Для добавления дополнительных полей к результату вывода надо прописать названия полей в параметр &includeTVs. А некоторые типы полей, например изображения, после подключения надо подготовить (отрендерить) с помощью параметра &processTVs

    [[pdoResources?
    &parents=`1`
    &tpl=`chunk1`
    &includeTVs=`tags, image`
    &prepareTVs=`1`
    &processTVs=`image`
]]

    Если надо отфильтровать по какому-либо параметру

    [[pdoResources?
    &parents=`1`
    &tpl=`chunk1`
    &includeTVs=`tags, image`
    &prepareTVs=`1`
    &processTVs=`image`
    &tvFilters=`tags!=null`
]]

    Для более сложной фильтрации можно использовать параметр &where.

    Если надо использовать разные шаблоны в зависимости от условия

    [[pdoResources?
    &parents=`1`
    &tpl=`chunk1`
    &includeTVs=`tags, image`
    &prepareTVs=`1`
    &processTVs=`image`
    &tvFilters=`tags!=null`
    &tplCondition=`tv.image`
    &tplOperator=`!=`
    &conditionalTpls=`{"":"chunk2"}`
]]

    Вывод ресурсов где каждые N имеют свою обертку (параметр &tpl_nN не совместим с &offset)

    [[pdoResources?
        &parents=`[[*id]]`
        &tpl=`chunk`
        &tplFirst=`@INLINE <div class="item item-50">[[$chunk]]`
        &tpl_n2=`@INLINE [[$chunk]]</div><div class="item item-50">`
        &tplLast=`@INLINE [[$chunk]]</div>`
    ]]
]]

    Вызов xPDO с параметрами

    $modx->runSnippet('pdoResources', array( 
                  'parent'	=> '1',
                  'tpl' => 'chunk1',   
                  'includeTVs' => 'tags, image',
                  'sortdir' => 'ASC', 
                  'prepareTVs' => '1',
                  'tvFilters' => 'tags!=null',
                  ));

    Возможные ошибки

    Все заполнено правильно, но вместо ресурсов отображается массив. Ищите проблему в вызове

    • неправильные кавычки?
    • не существующий чанк с шаблоном?
    • строковый шаблон без @INLINE?

    Примеры

    Вывод ресурсов не являющихся папкой

    Fenom / xPDO
    Теги MODX
                            $modx->runSnippet('pdoResources', array( 
        'parent'	=> '1',
        'tvFilters' =>'isfolder!=1',
));
                        
                            [[pdoResources?
    &parents=`1`
    &tvFilters=`isfolder!=1`
]]

    Вывод рандомных ресурсов из рандомных родительских каталогов:

     [[!pdoResources?
                                  &parents=`1,2,3`
                                  &resources=`[[!pdoResources? &sortby=`RAND()` limit=`1` &returnIds=`1`]]`
                                  &tplWrapper=`@INLINE <div>[[+output]]</div>`
                                  &tpl=`tpl.someTpl`
                                  &hideContainers=`1`
                                  &sortby=`RAND()`
                                  &limit=`24`
                              ]]

    Документация сниппета pdoResources

    pdoResources ​

    pdoResources ​

    Сниппет предназначен для вывода списка ресурсов. Является продвинутой заменой для getResources: обладает всеми его возможностями, но лишен недостатков.

    Умеет правильно сортировать ТВ параметры, присоединять таблицы при выборке, включать и исключать категории из разных контекстов и еще много чего.

    Параметры ​

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

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

    Название По умолчанию Описание
    &parents Текущий ресурс Список родителей, через запятую, для поиска результатов. Если поставить 0 - выборка не ограничивается. Если id родителя начинается с дефиса, он и его потомки исключаются из выборки.
    &depth 10 Глубина поиска дочерних ресурсов от родителя.
    &resources Список ресурсов, через запятую, для вывода в результатах. Если id ресурса начинается с дефиса, этот ресурс исключается из выборки.
    &context Ограничение выборки по контексту ресурсов.
    &where Массив дополнительных параметров выборки, закодированный в JSON.
    &showHidden 1 Показывать ресурсы, скрытые в меню.
    &showUnpublished 0 Показывать неопубликованные ресурсы.
    &showDeleted 0 Показывать удалённые ресурсы.
    &hideContainers 0 Отключает вывод контейнеров, то есть, ресурсов с «isfolder = 1».
    &select 0 Список полей для выборки, через запятую. Можно указывать JSON строку с массивом, например {"modResource":"id,pagetitle,content"}.
    &sortby pagetitle Любое поле ресурса для сортировки, включая ТВ параметр, если он указан в параметре &includeTVs. Можно указывать JSON строку с массивом нескольких полей, например {"tvname":"ASC", "pagetitle":"DESC"}. Для случайно сортировки укажите «RAND()»
    &sortdir DESC Направление сортировки: по убыванию или возрастанию.
    &setTotal 0 Отключение выборки total по умолчанию (с версии 2.11.0). Сниппет pdoPage включает его всегда.
    &limit 10 Ограничение количества результатов выборки. Можно использовать «0».
    &offset 0 Пропуск результатов от начала. Необходимо использовать вместе с явно указанным &limit
    &first 1 Номер первой итерации вывода результатов.
    &last Автоматически, по формуле (total + first - 1) Номер последней итерации вывода результатов.
    &loadModels Список компонентов, через запятую, чьи модели нужно загрузить для построения запроса. Например: &loadModels=`ms2gallery,msearch2`.
    &tvFilters Список фильтров по ТВ, с разделителями AND и OR. Разделитель, указанный в параметре &tvFiltersOrDelimiter представляет логическое условие OR и по нему условия группируются в первую очередь. Внутри каждой группы вы можете задать список значений, разделив их &tvFiltersAndDelimiter. Поиск значений может проводиться в каком-то конкретном ТВ, если он указан «myTV==value», или в любом «value». Пример вызова: &tvFilters=`filter2==one,filter1==bar%||filter1==foo`. Обратите внимание: фильтрация использует оператор LIKE и знак «%» является метасимволом. И еще: Поиск идёт по значениям, которые физически находятся в БД, то есть, сюда не подставляются значения по умолчанию из настроек ТВ.
    &tvFiltersAndDelimiter , Разделитель для условий AND в параметре &tvFilters.
    &tvFiltersOrDelimiter || Разделитель для условий OR в параметре &tvFilters.

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

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

    Название Описание
    &returnIds Установите значение «1», чтобы вернуть строку со списком id ресурсов, вместо оформленных результатов. Все указанные шаблоны игнорируются.
    &tpl Имя чанка для оформления ресурса. Если не указан, то содержимое полей ресурса будет распечатано на экран.
    &tplFirst Имя чанка для первого ресурса в результатах.
    &tplLast Имя чанка для последнего ресурса в результатах.
    &tplOdd Имя чанка для каждого второго ресурса (хоть "odd" значит "нечётный", работает для чётных ресурсов).
    &tplWrapper Чанк-обёртка, для заворачивания всех результатов. Понимает один плейсхолдер: [[+output]]. Не работает вместе с параметром &toSeparatePlaceholders.
    &wrapIfEmpty Включает вывод чанка-обертки &tplWrapper даже если результатов нет.
    &tplCondition Поле ресурса, из которого будет получено значение для выбора чанка по условию в &conditionalTpls.
    &tplOperator Необязательный оператор для проведения сравнения поля ресурса в &tplCondition с массивом значений и чанков в &conditionalTpls.
    &conditionalTpls JSON строка с массивом, у которого в ключах указано то, с чем будет сравниваться &tplCondition, а в значениях - чанки, которые будут использованы для вывода, если сравнение будет успешно. Оператор сравнения указывается в &tplOperator. Для операторов типа isempty можно использовать массив без ключей.
    &outputSeparator Необязательная строка для разделения результатов работы.

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

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

    Название По умолчанию Описание
    &fastMode 0 Быстрый режим обработки чанков. Все необработанные теги (условия, сниппеты и т.п.) будут вырезаны.
    &idx Вы можете указать стартовый номер итерации вывода результатов.
    &totalVar total Имя плейсхолдера для сохранения общего количества результатов. Параметр setTotal должен быть включен.
    &includeContent 0 Включаем поле «content» в выборку.
    &includeTVs Список ТВ параметров для выборки, через запятую. Например: «action,time» дадут плейсхолдеры [[+tv.action]] и [[+tv.time]].
    &prepareTVs 1, что означает подготовку всех ТВ, указанных в &includeTVs Список ТВ параметров, которые нужно подготовить перед выводом.
    &processTVs Список ТВ параметров, которые нужно обработать перед выводом. Если установить в «1», будут обработаны все ТВ, указанные в &includeTVs.
    &tvPrefix tv. Префикс для ТВ параметров.
    &useWeblinkUrl Генерировать ссылку с учетом класса ресурса, включает плейсхолдер [[+link]].
    &toPlaceholder Если не пусто, сниппет сохранит все данные в плейсхолдер с этим именем, вместо вывода на экран.
    &toSeparatePlaceholders Если вы укажете слово в этом параметре, то ВСЕ результаты будут выставлены в разные плейсхолдеры, начинающиеся с этого слова и заканчивающиеся порядковым номером строки, от нуля. Например, указав в параметре «myPl», вы получите плейсхолдеры [[+myPl0]], [[+myPl1]] и т.д.
    &showLog 0 Показывать дополнительную информацию о работе сниппета. Только для авторизованных в контекте «mgr».

    Примеры ​

    Простейший вывод списка дочерних ресурсов документа с идентификатором 1:

    modx
    [[pdoResources?
  &parents=`1`
  &depth=`0`
  &tpl=`ListRowTpl`
]]

    Если используется дополнительное поле image, то вызов изменится следующим образом:

    modx
    [[pdoResources?
  &parents=`1`
  &depth=`0`
  &tpl=`ListRowTpl`
  &includeTVs=`image`
]]

    Если нужно вывести элементы в том же порядке, как они объявлены в параметре &resources

    modx
    [[pdoResources?
  &resources=`213,34,58,290`
  &sortby=``
  &sortdir=`ASC`
  &tpl=`ListRowTpl`
  &includeTVs=`image`
]]

    В чанке ListRowTpl за это поле будет отвечать плейсхолдер [[+tv.image]]

    Дополнительная информация ​

    При переносе чанков с getResources, довольно распространённой ошибкой является использование модификатора strtotime, для форматирования даты.

    Дело в том, что даты ресурсов и так хранятся в виде timestamp, но конвертируются в нормальные даты из-за использования объектов modResource - так запрограммировано в его свойствах. А потом, для форматирования даты, их нужно перевести обратно в timestamp. Выходит двойная ненужная конвертация.

    pdoTools же работает напрямую с базой данных, без создания объектов и конвертации их значений, поэтому в чанк приходит timestamp, который не нужно дополнительно обрабатывать. Вы можете сразу применять модификатор date к значениям:

    modx
    [[+publishedon:date=`%d.%m.%Y`]]
или
[[+createdon:date=`%Y-%m-%d`]]

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

    Общие параметры для пакета pdoTools

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

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

    Общие параметры для сниппетов, основанных на pdoTools/pdoFetch.

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

    Эти параметры определяют, какие объекты будут получены.

    Название По умолчанию Описание
    &class modResource Класс получаемого объекта
    &parents Текущий ресурс Список родителей, через запятую, для поиска результатов. Если поставить 0 - выборка не ограничивается. Если id родителя начинается с дефиса, он и его потомки исключаются из выборки.
    &depth 10 Глубина поиска дочерних ресурсов от родителя.
    &resources Список ресурсов, через запятую, для вывода в результатах. Если id ресурса начинается с дефиса, этот ресурс исключается из выборки.
    &templates Список шаблонов, через запятую, для фильтрации результатов. Если id шаблона начинается с дефиса, ресурсы с ним исключается из выборки.
    &context Ограничение выборки по контексту ресурсов.
    &where Массив дополнительных параметров выборки, закодированный в JSON.
    &showHidden 0 Показывать ресурсы, скрытые в меню.
    &showUnpublished 0 Показывать неопубликованные ресурсы.
    &showDeleted 0 Показывать удалённые ресурсы.
    &hideContainers 0 Отключает вывод контейнеров, то есть, ресурсов с isfolder = 1.
    &hideUnsearchable Отключает вывод спрятанных от поиска ресурсов.
    &select Список полей для выборки, через запятую. Можно указывать JSON строку с массивом, например {"modResource":"id,pagetitle,content"}.
    &leftJoin Аналог SQL оператора left join
    &rightJoin Аналог SQL оператора right join
    &innerJoin Аналог SQL оператора inner join
    &joinSequence innerJoin,leftJoin,rightJoin Порядок подключения таблиц, через зяпятую.
    &sortby pagetitle Любое поле ресурса для сортировки, включая ТВ параметр, если он указан в параметре &includeTVs. Можно указывать JSON строку с массивом нескольких полей. Для случайно сортировки укажите RAND()
    &sortdir ASC Направление сортировки: по убыванию или возрастанию.
    &groupby Указывает поле, по которому группируются результаты
    &having Используется, чтобы ограничить выборку сгруппированных строк с помощью условия, относящегося ко всей группе, заданной в &groupby
    &limit 0 Ограничение количества результатов выборки. Можно использовать «0».
    &offset 0 Пропуск результатов от начала.
    &first 1 Номер первой итерации вывода результатов.
    &last Автоматически, по формуле (total + first - 1) Номер последней итерации вывода результатов.
    &loadModels Список компонентов, через запятую, чьи модели нужно загрузить для построения запроса. Например:&loadModels=`ms2gallery,msearch2` .
    &tvFilters Список фильтров по ТВ, с разделителями AND и OR. Разделитель, указанный в параметре &tvFiltersOrDelimiter представляет логическое условие OR и по нему условия группируются в первую очередь. Внутри каждой группы вы можете задать список значений, разделив их &tvFiltersAndDelimiter. Поиск значений может проводиться в каком-то конкретном ТВ, если он указан myTV==value, или в любом «value». Пример вызова: ``&tvFilters=`filter2==one,filter1==bar%
    &tvFiltersAndDelimiter , Разделитель для условий AND в параметре &tvFilters.
    &tvFiltersOrDelimiter `
    &sortbyTV Дополнительное поле, по которому нужно сортировать результаты. Может быть указано напрямую в параметре &sortby
    &sortdirTV Направление сортировки по дополнительному полю, указанному в &sortbyTV. Может быть указано напрямую в параметре &sortby
    &sortbyTVType Тип сортировки по ТВ параметру. Возможные варианты: string, integer, decimal и datetime. Если пусто, то ТВ будет отсортирован в зависимости от его типа: как текст, число или дата.
    &checkPermissions Укажите, какие разрешения нужно проверять у пользователя при выводе объектов.
    &disableConditions Отключает специфичные для класса modResource параметры выборки.
    &fenomModifiers Список сниппетов-модификаторов через запятую, для подключения в Fenom. Подробности в соответствующем разделе.

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

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

    Название Описание
    &tpl Имя чанка для оформления ресурса. Если не указан, то содержимое полей ресурса будет распечатано на экран.
    &tplFirst Имя чанка для первого ресурса в результатах.
    &tplLast Имя чанка для последнего ресурса в результатах.
    &tplOdd Имя чанка для каждого чётного ресурса (хоть "odd" значит "нечётный", работает для чётных ресурсов).
    &tpl_N Имя чанка для N-го ресурса, например, &tpl_4=`tpl4th` установит шаблон для 4-го ресурса.
    &tpl_nN Имя чанка для каждого N-го ресурса, например, &tpl_n4=`tplEvery4th` будет применено к каждому 4-му ресурсу.
    &tplCondition Поле ресурса, из которого будет получено значение для выбора чанка по условию в &conditionalTpls.
    &tplOperator Необязательный оператор для проведения сравнения поля ресурса в &tplCondition с массивом значений и чанков в &conditionalTpls.
    &conditionalTpls JSON строка с массивом, у которого в ключах указано то, с чем будет сравниваться &tplCondition, а в значениях - чанки, которые будут использованы для вывода, если сравнение будет успешно. Оператор сравнения указывается в &tplOperator. Для операторов типа isempty можно использовать массив без ключей.
    &outputSeparator Необязательная строка для разделения результатов работы.

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

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

    Название По умолчанию Описание
    &return chunks Определяет способ вывода результатов. См. ниже.
    &fastMode 0 Быстрый режим обработки чанков. Все необработанные теги (условия, сниппеты и т.п.) будут вырезаны.
    &nestedChunkPrefix pdotools_ Префикс для "быстрых плейсхолдеров", включаемых параметром &fastMode
    &idx Вы можете указать стартовый номер итерации вывода результатов.
    &totalVar total Имя плейсхолдера для сохранения общего количества результатов.
    &includeContent 0 Включаем поле content в выборку.
    &includeTVs Список ТВ параметров для выборки, через запятую. Например: action,time дадут плейсхолдеры [[+action]] и [[+time]].
    &includeTVList Псевдоним &includeTVs
    &prepareTVs 1 Список ТВ параметров, с файлами из источников медиа, для которых нужно сгенерировать полные пути. Если установить в 1, будут подготовлены все ТВ, указанные в &includeTVs.
    &processTVs Список ТВ параметров, которые нужно обработать и вывести согласно их настроек в менеджере системы. Если установить в 1, будут обработаны все ТВ, указанные в &includeTVs. Замедляет работу.
    &tvPrefix tv. у pdoResources и пусто у других сниппетов Префикс для ТВ параметров.
    &prepareSnippet 1 Указывает сниппет, который принимает данные перед выводом в чанк и может их менять или добавлять
    &decodeJSON Разбирает поля типа JSON вместо вывода в виде строки
    &scheme -1 Схема формирования url, передаётся в modX::makeUrl(), поэтому возможные варианты нужно смотреть здесь. Особый тип uri подставляет значение uri ресурса, без запуска функции.
    &useWeblinkUrl Генерировать ссылку с учетом класса ресурса.
    &toSeparatePlaceholders Если вы укажете слово в этом параметре, то ВСЕ результаты будут выставлены в разные плейсхолдеры, начинающиеся с этого слова и заканчивающиеся порядковым номером строки, от нуля. Например, указав в параметре myPl, вы получите плейсхолдеры [[+myPl0]], [[+myPl1]] и т.д.
    &additionalPlaceholders Устанавливает дополнительные плейсхолдеры
    &cache_key Значение системной настройки cache_resource_key для ресурсов (по умолчанию resource) или default Ключ кеширования
    &cache_handler Значение системной настройки cache_resource_handler или xPDOFileCache Обработчик кеша
    &cacheTime Значение системной настройки cache_resource_expires или 0 (вечный) Время жизни кеша (в секундах)

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

    Все чанки могут иметь один из следующих префиксов:

    @INLINE или @CODE. В качестве шаблона будет использован код после этого префикса.

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

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

    Поэтому для INLINE чанков предусмотрена замена [[+]] на {{+}} - такие теги MODX пропускает, а pdoTools при работае конвертирует их как нужно. Конечно, вы всё равно можете использовать теги MODX, если вам нужно, чтобы в чанк попала уже обработанная информация, например:

    modx
    [[!pdoResources?
  &parents=`0`
  &tplFirst=`@INLINE Текущая страница: [[*pagetitle]]`
  &tpl=`@INLINE <p>[[+id]] - [[+pagetitle]]<p>`
]]

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

    Имя файла должно быть с расширением .tpl или .html.

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

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

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

    @CHUNK. Аналогично простому указанию имени чанка, оставлено для совместимости со сторонними сниппетами.

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

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

    Подробнее про возможности pdoParser можно прочитать в соответствующем разделе.

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

    pdoTools умеет возвращать данные в разном виде, в зависимости от параметр &return. В основном это используют сами сниппеты для внутренних нужд, но вы можете указывать &return в pdoResources:

    modx
    [[!pdoResources?
  &parents=`0`
  &return=`json`
]]
    • chunks - оформленные чанки, по умолчанию.
    • sql - подготовленный сырой SQL, полезно для отладки. Сам запрос не выполняется, только выводится на экран.
    • data - готовый массив данных. Из-за особенностей работы сниппетов MODX этот вариант имеет смысл использовать только при вызове pdoFetch::run() напрямую из своего сниппета, в противном случае вы получите только строку Array.
    • ids - возвращает только идентификаторы документов, через запятую. Удобно для подстановки в качестве параметра другим сниппетам. Параметр &returnIds использует именно этот тип.
    • json - возврат массива данных JSON строкой.
    • serialize - возврат массива данных сериализованной строкой. Иногда, по непонятным причинам, может вызвать нехватку памяти. Лучше использовать json.

    Внимание

    Все значения параметра &return понимают только pdoResources (pdoPage в связке с pdoResources) и pdoUsers.

    Значения chunks и data понимают pdoMenu и pdoCrumbs.

    Остальные сниппеты понимают, в основном, лишь chunks.

    modx back-end компоненты