pdoTools для MODx

Общие сведения

pdoTools — это набор удобных инструментов (сниппетов) для повседневной работы. Дополнительно включает небольшую библиотеку, которая увеличивает скорость работы сниппета.

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

Особенности:

  • Быстрая работа с БД (запросы составляются на xPDO, а выбираются без объектов — на PDO).
  • Предварительная обработка простых плейсхолдеров в чанках (парсер MODX задействован только при работе со сложными вызовами.
  • Код чанков можно указывать прямо при вызове сниппета, загружать обычным образом или из статичных файлов.
  • Предусмотрена сортировка, подготовка, обработка и вывод ТВ параметров.
  • Ведение подробного журнала работы сниппета с отметками времени, для отладки.
  • Возможность загрузки классов и множество функций, которые можно применять в своих разработках.
  • Встроенный шаблонизатор Fenom в версии 2.0
  • В настоящее время в комплект входит 10 универсальных сниппетов (со временем появляются новые инструменты)

Набор универсальных сниппетов:

  • pdoResources — инструмент для выборки ресурсов (очень быстрая замена для getResources, совместимая по параметрам). Он поддерживает почти все его возможности, и бладает особенностями:
    — подключение других таблиц через разные JOIN
    — можно указывать, что именно выбирать из колонок таблиц
    — гибкие условия выборки, вплоть до указания чистого SQL
  • pdoMenu — инструмент для постоения различных меню (замена для Wayfinder)
  • pdoUsers — выборка и вывод пользователей сайта, с фильтрацией по ролям и группам.
  • pdoCrumbs — генерация хлебных крошек (замена BreadCrumb).
  • pdoSitemap — генерация карты сайта (очень быстрая замена GoogleSiteMap
  • pdoNeighbors — инстумент вывода ссылок на соседние документы.
  • pdoField — инструмент получающий любое поле ресурса или его родителя, включая ТВ параметр. Имеет возможность вывода по умолчанияю. Отличная замена getResourcesField и UltimateParent.
  • pdoPage — постраничный вывод результатов (замена getPage).
  • pdoTitle — выводит оформленный тег title на страницу сайта, который состоит из имени страницы, имён родителей этой страницы и, других параметров. Предназначен для визульного различия документов с постраничной навигацией.
  • pdoArchive — предназначен для вывода архива документов сайта с разбивкой на годы, месяцы и дни.

Классы pdoTools

Ядро компонента разделено на 3 класса: общий pdoTools, работа с БД - pdoFetch и работа с оформлением, то есть pdoParser.

При установке в систему для быстрого запуска они регистрируются таким образом:


$pdoTools = $modx->getService('pdoTools');
$pdoFetch = $modx->getService('pdoFetch');
$pdoParser = $modx->getService('pdoParser');

pdoFetch наследует pdoTools, так что не нужно вызывать эти два класса вместе. Если вы хотите работать с БД, вызывайте один Fetch, а если нет - Tools.

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

Установка pdoTools осуществляется стандартным образом из официального репозитория modx.com или c modstore.pro

Общие параметры для сниппетов, основанных на 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%||filter1==foo`. Обратите внимание: фильтрация использует оператор LIKE и знак «%» является метасимволом. И еще: Поиск идёт по значениям, которые физически находятся в БД, то есть, сюда не подставляются значения по умолчанию из настроек ТВ.
&tvFiltersAndDelimiter "," Разделитель для условий AND в параметре &tvFilters.
&tvFiltersOrDelimiter "||" Разделитель для условий OR в параметре &tvFilters.
&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. В качестве шаблона будет использован код после этого префикса.


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

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

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


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

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


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

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


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

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


    [[!pdoResources?
    &tpl=`@CHUNK tpl.Resource.row`
]]
[[!pdoResources?
    &tpl=`tpl.Resource.row`
]]
Возвращаемые значения

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


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

Ссылки по теме