Modx pdotools – Большой рассказ про pdoTools, часть первая / Создание сайтов / Курсы обучения / bezumkin.ru

pdoTools / Утилиты / Дополнения MODX / modstore.pro

Внимание, этот компонент требует версию PHP 7.0 или выше! Если ваш сайт использует PHP ниже требуемого, установка этого дополнения может его сломать.

Внимание, этот компонент требует версию MODX не ниже 3.0 !

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

Благодаря использованию общей библиотеки, все сниппеты pdoTools обладают единым минимальным функционалом:

  • Все запросы в БД работают через PDO. Объекты xPDO не создаются, только если они действительно не нужны.
  • Предварительная обработка простых плейсхолдеров в чанках. Парсер MODX разбирается только со сложными вызовами.
  • Правильная сортировка, подготовка, обработка и вывод ТВ параметров.
  • Код чанков можно указывать прямо при вызове сниппета, загружать обычным образом или из статичных файлов.
  • «Быстрые плейсхолдеры» в чанках, которые заменяют фильтры типа «isempty» и оборачивают значения в теги только если те не пусты.
  • Ведение подробного журнала работы сниппета с отметками времени, для отладки.

Все запросы строятся на xPDO, выборка производится через PDO для экономии ресурсов и скорости.

В состав входят:

  • pdoResources — Очень быстрая замена для getResources, совместимая по параметрам.
  • pdoMenu — Замена для Wayfinder, строит меню.
  • pdoUsers — Выборка и вывод пользователей сайта, с фильтрацией по ролям и группам.
  • pdoCrumbs — Хлебные крошки, замена BreadCrumb.
  • pdoSitemap — Быстрая генерация карты сайта, замена GoogleSiteMap.
  • pdoNeighbors — Вывод ссылок на соседние документы.
  • pdoField — Вывод любого поля документа, замена getResourceField и UltimateParent.
  • pdoPage
    — Постраничный вывод результатов, замена getPage.

Основные возможности


— Любые выборки, из любых таблиц с любыми условиями и джоинами.
— Учет времени на каждую операцию, подробный лог для выявления узких мест.
— Полная совместимость с getPage для постраничного вывода результатов.
— Самый быстрый процессинг чанков, быстрее только вообще без них.
Встроенный шаблонизатор Fenom в версии 2.0

Общие параметры / pdoTools / Компоненты / docs.modx.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,msearch3`.
&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`
]]

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

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

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

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

pdoArchive / Сниппеты / pdoTools / docs.modx.pro

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

Чанки

  • tpl - Имя чанка для оформления ресурса. Если не указан, то содержимое полей ресурса будет распечатано на экран.
@INLINE <li>[[+date]] <a href="[[+link]]">[[+menutitle]]</a></li>
  • tplYear - Шаблон для оформления года
@INLINE <h4>[[+year]] <sup>([[+count]])</sup></h4><ul>[[+wrapper]]</ul>
  • tplMonth - Шаблон для оформления месяца
@INLINE <li><h5>[[+month_name]] <sup>([[+count]])</sup></h5><ul>[[+wrapper]]</ul></li>
  • tplDay - Шаблон для оформления дня
@INLINE <li><h5>[[+day]] <sup>([[+count]])</sup></h5><ul>[[+wrapper]]</ul></li>
  • tplWrapper - Чанк-обёртка, для заворачивания всех результатов. Понимает один плейсхолдер: [[+output]].

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

Параметры

Сниппет принимает общие параметры pdoTools.

Параметр По умолчанию Описание
tplWrapper Чанк-обёртка, для заворачивания всех результатов. Понимает один плейсхолдер: [[+output]].
wrapIfEmpty Включает вывод чанка-обертки (tplWrapper) даже если результатов нет.
dateField createdon Поле ресурса для получения даты документа: createdon, publishedon или editedon.
dateFormat %H:%M Формат даты для функции strftime()
showLog Показывать дополнительную информацию о работе сниппета. Только для авторизованных в контекте "mgr".
sortby createdon Любое поле ресурса для сортировки, включая ТВ параметр, если он указан в параметре "includeTVs". Можно указывать JSON строку с массивом нескольких полей. Для случайно сортировки укажите "RAND()"
sortbyTV Сортировка по ТВ параметру. Если он не указан в &includeTVs, то будет подключен автоматически.
sortbyTVType Тип сортировки по ТВ параметру. Возможные варианты: string, integer, decimal и datetime. Если пусто, то ТВ будет отсортирован в зависимости от его типа: как текст, число или дата.
sortdir DESC Направление сортировки: по убыванию или возрастанию.
sortdirTV ASC Направление сортировки ТВ: по убыванию или возрастанию. Если не указан, то будет равен параметру &sortdir.
limit Ограничение количества результатов выборки. Можно использовать "0".
offset Пропуск результатов от начала.
depth 10 Глубина поиска дочерних ресурсов от родителя.
outputSeparator \n Необязательная строка для разделения результатов работы.
toPlaceholder Если не пусто, сниппет сохранит все данные в плейсхолдер с этим именем, вместо вывода не экран.
parents Список родителей, через запятую, для поиска результатов. По умолчанию выборка ограничена текущим родителем. Если поставить 0 - выборка не ограничивается. Если id родителя начинается с дефиса, он и его потомки исключается из выборки.
includeContent Включаем поле "content" в выборку.
includeTVs Список ТВ параметров для выборки, через запятую. Например: "action,time" дадут плейсхолдеры [[+action]] и [[+time]].
prepareTVs 1 Список ТВ параметров, которые нужно подготовить перед выводом. По умолчанию, установлено в "1", что означает подготовку всех ТВ, указанных в "&includeTVs=``"
processTVs Список ТВ параметров, которые нужно обработать перед выводом. Если установить в "1" - будут обработаны все ТВ, указанные в "&includeTVs=``". По умолчанию параметр пуст.
tvPrefix tv. Префикс для ТВ параметров.
where Массив дополнительных параметров выборки, закодированный в JSON.
showUnpublished Показывать неопубликованные ресурсы.
showDeleted Показывать удалённые ресурсы.
showHidden 1 Показывать ресурсы, скрытые в меню.
hideContainers Отключает вывод контейнеров, то есть, ресурсов с isfolder = 1.
context Ограничение выборки по контексту ресурсов.
totalVar total Имя плейсхолдера для сохранения общего количества результатов.
resources Список ресурсов, через запятую, для вывода в результатах. Если id ресурса начинается с дефиса, этот ресурс исключается из выборки.
select Список полей для выборки, через запятую. Можно указывать JSON строку с массивом, например {"modResource":"id,pagetitle,content"}.
scheme Схема формирования ссылок: "uri" для подстановки поля uri документа (очень быстро) или параметр для modX::makeUrl().
useWeblinkUrl 1 Генерировать ссылку с учетом класса ресурса.

Примеры

Обычный вызов:

[[!pdoArchive?
    &parents=`0`
]]

Вызов через pdoPage:

[[!pdoPage?
    &element=`pdoArchive`
    &parents=`0`
]]
[[!+page.nav]]

Пример вывода тикетов, как на картинке в начале страницы:

[[!pdoPage?
    &element=`pdoArchive`
    &parents=`0`
    &limit=`1000`
    &maxLimit=`1000`
    &scheme=`uri`
    &sortby=`publishedon`
    &dateField=`publishedon`
    &where=`{"class_key":"Ticket"}`
    &tplYear=``
    &tplMonth=`@INLINE <h5>{$month_name} {$year} <sup>({$count})</sup></h5><ul>{$wrapper}</ul>`
    &tpl=`@INLINE <li>{$date} <a href="{$link}">{$menutitle}</a> / <small>{$section}</small></li>`
    &leftJoin=`{
        "Parent": {
            "class": "modResource"
        }
    }`
    &select=`{
        "modResource": "*",
        "Parent":"Parent.pagetitle as section"
    }`
]]

pdoMenu / Сниппеты / pdoTools / docs.modx.pro

Сниппет генерации меню. Может заменять Wayfinder, и позволяет более гибко указывать параметры.

Например, умеет строить меню сразу из нескольких родителей, отображая их как вместе, так и отдельными ветками.

Существенный прирост скорости дает только при первом запуске, дальше Wayfinder не особо уступает, благодаря грамотному кэшированию.

Параметры

По умолчанию pdoMenu принимает общие параметры pdoTools и некоторые свои:

Название По умолчанию Описание
&parents Текущий ресурс Список родителей для поиска результатов, через запятую. Если поставить &parents=`0` - выборка не ограничивается. Если id родителя начинается с дефиса, он и его потомки исключаются из выборки.
&level 0 (не ограниченно) Уровень генерируемого меню.
&resources Список ресурсов для вывода в результатах, через запятую. Если id ресурса начинается с дефиса, этот ресурс исключается из выборки.
&templates Список шаблонов для фильтрации результатов, через запятую. Если id шаблона начинается с дефиса, ресурсы с ним исключается из выборки.
&where Массив дополнительных параметров выборки, закодированный в JSON.
&displayStart 0 Включить показ начальных узлов меню. Полезно при указании более одного «parents».
&context Ограничение выборки по контексту ресурсов.
&showHidden 0 Показывать ресурсы, скрытые в меню.
&showUnpublished 0 Показывать неопубликованные ресурсы.
&previewUnpublished 0 Включить показ неопубликованных ресурсов, если у пользователя есть на это разрешение.
&hideSubMenus 0 Спрятать неактивные ветки меню.
&select Список полей для выборки, через запятую. Можно указывать JSON-строку с массивом, например &select=`{"modResource":"id,pagetitle,content"}`
&sortby menuindex Любое поле ресурса для сортировки, включая ТВ-параметр, если он указан в параметре &includeTVs, например &sortby=`{"tvname":"ASC","pagetitle":"DESC"}`. Можно указывать JSON-строку с массивом нескольких полей. Для случайной сортировки укажите &sortby=`RAND()`
&sortdir ASC Направление сортировки: по убыванию или по возрастанию. Если оставить параметры &sortby и &sortdir пустыми, то сортировка будет идти по порядку ресурсов в &resources.
&limit 0 Ограничение количества результатов выборки.
&offset 0 Пропуск результатов от начала. Необходимо использовать вместе с явно указанным &limit
&checkPermissions Укажите, какие разрешения нужно проверять у пользователя при выводе ресурсов, например &checkPermissions=`list`.
&countChildren 0 Точный подсчет количества дочерних ресурсов каждой категории и вывод их в плейсхолдер [[+children]]. Делает дополнительные запросы в БД, поэтому по умолчанию отключен.
&toPlaceholder Если не пусто, сниппет сохранит все данные в плейсхолдер с этим именем вместо вывода на экран.
&plPrefix wf. Префикс для выставляемых плейсхолдеров.
&showLog 0 Показывать дополнительную информацию о работе сниппета. Только для авторизованных в контекcте «mgr».
&fastMode 0 Быстрый режим обработки чанков. Все необработанные теги (условия, сниппеты и т.п.) будут вырезаны.
&cache 0 Кэширование результатов работы сниппета.
&cacheTime 3600 Время актуальности кэша, в секундах.
&scheme -1 Схема формирования url, передаётся в modX::makeUrl(), поэтому возможные варианты нужно смотреть здесь. Особый тип uri подставляет значение uri ресурса, без запуска функции.
&useWeblinkUrl 1 Генерировать ссылку с учетом класса ресурса.
&rowIdPrefix Префикс для выставления идентификатора в чанк.
&hereId id текущего ресурса для генерируемого меню. Нужно указывать только если скрипт сам его неверно определяет, например при выводе меню из чанка другого сниппета.
&includeTVs Список ТВ-параметров для выборки, через запятую. Например &includeTVs=`action,time` дадут плейсхолдеры [[+action]] и [[+time]].
&prepareTVs Список ТВ-параметров, с файлами из источников медиа, для которых нужно сгенерировать полные пути. Если установить &prepareTVs=`1`, будут подготовлены все ТВ, указанные в &includeTVs.
&processTVs Список ТВ-параметров, которые нужно обработать и вывести согласно их настроек в менеджере системы. Если установить &processTVs=`1`, будут обработаны все ТВ, указанные в &includeTVs. Замедляет работу.
&tvPrefix Префикс для ТВ-параметров.

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

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

Название Описание
&tplOuter Чанк оформления всего блока меню. По умолчанию: @INLINE <ul [[+classes]]>[[+wrapper]]</ul>
&tpl Чанк оформления пункта меню. Если не указан, то содержимое полей ресурса будет распечатано на экран. По умолчанию: @INLINE <li [[+classes]]><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a>[[+wrapper]]</li>
&tplHere Чанк оформления текущего пункта меню.
&tplStart Чанк оформления корневого пункта, при условии, что включен &displayStart. По умолчанию: @INLINE <h3 [[+classes]]>[[+menutitle]]</h3>[[+wrapper]]
&tplParentRow Чанк оформления родителя с потомками, не подпадающего под условия &tplCategoryFolder. Например: @INLINE <li><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a>[[+wrapper]]</li>
&tplParentRowHere Чанк оформления текущего документа, если он содержит потомков.
&tplParentRowActive Чанк оформления родителей с потомками в активной ветке меню.
&tplCategoryFolder Специальный чанк оформления категории. Категорией считается родитель с потомками, у которого указан пустой шаблон или rel="category" в поле link_attributes.
&tplInner Чанк оформления всего блока подпунктов меню. Если пуст - будет использовать &tplOuter. Например: @INLINE <ul>[[+wrapper]]</ul>
&tplInnerRow Чанк оформления подпункта меню. Например: @INLINE <li><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a>[[+wrapper]]</li>
&tplInnerHere Чанк оформления активного подпункта меню.

Параметры CSS классов

Эти параметры задают значение плейсхолдеров [[+classnames]] и [[+classes]] для различных элементов меню. Плейсхолдер [[+classnames]] выводит только название класса без атрибута class="", в отличие от плейсхолдера [[+classes]].

Название Описание
&firstClass Класс для первого пункта меню. По умолчанию: first
&lastClass Класс последнего пункта меню. По умолчанию: last
&hereClass Класс для активного пункта меню. По умолчанию: active
&parentClass Класс категории меню.
&rowClass Класс пункта меню.
&outerClass Класс обертки блока меню.
&innerClass Класс обертки блока подпунктов меню.
&levelClass Класс уровня меню. Например если укажите «level», то будет «level1», «level2» и т.д.
&selfClass Класс текущего ресурса в меню.
&webLinkClass Класс ресурса-ссылки.

Примеры

Обычный вывод меню из корня сайта в один уровень:

[[pdoMenu?
    &parents=`0`
    &level=`1`
]]

Вывод с исключением определенных родителей и проверкой разрешений пользователя:

[[pdoMenu?
    &parents=`-10,-15`
    &level=`2`
    &checkPermissions=`load,list,view`
]]

Вывод меню сразу из двух родителей, с показом корневых точек:

[[pdoMenu?
    &parents=`10,15`
    &displayStart=`1`
]]

Вывод двух уровней ресурсов с подсчетом количества вложенных:

[[pdoMenu?
    &parents=`0`
    &level=`2`
    &tplInner=`@INLINE [[+wrapper]]`
    &tplParentRow=`@INLINE <li [[+classes]]><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a> ([[+children]])</li>[[+wrapper]]`
    &countChildren=`1`
]]

pdoParser / Классы / pdoTools / docs.modx.pro

pdoParser является заменой класса modParser.

Обработка плейсхолдеров

Его задача - стараться быстро разобрать теги MODX без создания объектов, как это делает оригинальный парсер. pdoParser умеет работать только с простыми тегами, без фильтров и условий, то есть:

  • [[%tag]] - строка лексикона
  • [[~id]] - ссылка
  • [[+tag]] - обычные плейсхолдеры
  • [[++tag]] - системные плейсхолдеры
  • [[*tag]] - плейсхолдеры ресурса
  • [[#tag]] - плейсхолдеры FastField

Специальные теги FastField были предложены Виталием Киреевым в одноимённом дополнении. После согласованию с автором, pdoParser был обучен работе с ними.

Он умеет:

  • Выводить поля ресурсов: [[#15.pagetitle]], [[#20.content]]
  • Выводить ТВ параметры ресурсов: [[#15.date]], [[#20.some_tv]]
  • Выводить поля товаров miniShop2: [[#21.price]], [[#22.article]]
  • Выводить массивы ресурсов и товаров: [[#12.properties.somefield]], [[#15.size.1]]
  • Выводить глобальные массивы: [[#POST.key]], [[#SESSION.another_key]]
  • Распечатывать массивы для отладки: [[#15.colors]], [[#GET]], [[#12.properties]]

Цифра после решетки - это id ресурса, от которого нужно выбрать данные.

Все эти теги pdoTools обрабатывает без создания объектов modElement, поэтому работает немного быстрее чем родные методы MODX. Если же плейсхолдер вызван с какими-то параметрами, то он уйдёт в родной modParser.

Шаблонизатор Fenom

С версии 2.0 в состав pdoTools входит шаблонизатор Fenom (анонс от автора на Хабре).

Работает только при включенном pdoParser и если разрешен в системных параметрах.

Возможности

  • Компилируется в нативный PHP код, который выполняется гораздо быстрее, чем теги MODX. Прирост, в среднем 30% - 50%.
  • Может работать и в чанках и на страницах сайта
  • Теги Fenom и MODX никак не мешают друг другу и работают одновременно
  • Если в чанке нет плейсхолдеров MODX, то парсер MODX не запускается
  • Если в чанке нет тегов Fenom, то он тоже не запускается
  • Поддерживаются даже @INLINE чанки
  • В отличии от других решений, вам не нужно никаким образом менять или переписывать свои сниппеты - всё работает через методы pdoTools::getChunk() и pdoTools::parseChunk() автоматически.
  • Все ошибки компиляции пишутся в системный журнал

Настройки

  • pdotools_fenom_default включает обработку синтаксиса Fenom во всех чанках сайта.
  • pdotools_fenom_parser включает обработку синтаксиса Fenom на страницах сайта. Контент ресурсов, шаблоны - везде. По умолчанию отключено.
  • pdotools_fenom_php включает возможность выполнения произвольных функций PHP в шаблонах через {$.php.функция()}. Опция эта очень опасная, так что тоже отключена.
  • pdotools_fenom_modx - чуть менее опасная опция, но во многих случаях, пока, необходимая - работа с объектами modX и pdoTools через переменные {$modx} и {$pdoTools}. Если вы не доверяете своим менеджерам - выключите её от греха подальше, потому что через объект modX можно удалить начисто весь сайт.
  • pdotools_fenom_cache - включает кэшированние чанков (только чанков, не страниц сайта) через кэшер MODX (а не как раньше). Стоит использовать только на продакшн сайтах при больших и сложных чанках.

Порядок запуска шаблонизатора

Если включен pdoParser и системная опция pdotools_fenom_parser, то шаблонизатор запускается ровно вот здесь.

В этот момент все кэшированные чанки и сниппеты на странице обработаны (или загружены из кэша) и вы можете использовать вот такие конструкции:

{if $.get.test == 1}
    [[!pdoResources?parents=`0`]]
{else}
    [[!pdoMenu?parents=`0`]]
{/if}

То есть, в зависимости от $_GET['test'] на странице будет запущен или один сниппет или другой. Парсер MODX же запустил бы оба и результат выполнения одного неподходящего просто не показал.

Таким образом, вы можете реализовывать гораздо более сложную логику работы сайта даже с отключенными опциями pdotools_fenom_php и pdotools_fenom_modx. Понятное дело, что вызов тегов Fenom на страницах сайта никак не кэшируется.

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

Кэширование чанков Fenom

По умолчанию этот функционал Fenom отключен, потому что по моим тестам, толку от него в MODX нет. Но, это на моих мелких и простых чанках, а у вас может быть что-то посложнее.

Поэтому вы можете включить системную настройку pdotools_fenom_cache и тогда скомпилированные шаблоны будут сохранены в /cache/default/fenom/ в зависимости от своего типа.

Чанки из БД кэшируются под своими id, а INLINE именуются как хэш от своего содержимого, то есть - путь к обычному чанку будет выглядеть как cache/default/fenom/chunk/90.cache.php, а к INLINE уже как cache/default/fenom/inline/35e115c27fdc3814b6f41a1015aa67e6.cache.php.

Отсюда следует, что нормальные чанки из БД кэшируются намертво, и обновляются только при очистке системного кэша, а INLINE чанки при изменении контента сохраняются под новым именем и весь кэш чистить не нужно.

Как это работает дальше?

При первом запуске с пустым кэшем pdoTools получает нужный чанк, определяет его тип и отдаёт в Fenom. Тот компилирует шаблон и сохраняет его во внутренний кэш pdoTools методом setStore(). Этот кэш находится в ОЗУ и сохраняется только на время выполнения скрипта, он нужен чтобы не компилировать 10 раз один и тот же чанк при выводе pdoResources.

А вот если включена опция pdotools_fenom_cache, то исходный код скомпилированного шаблона сохраняется на HDD сервера, и при следующем запуске Fenom уже не нужно его компилировать. Кэшер MODX отдаёт исходный код, из него получается объект Fenom\Render который передаётся в setStore() и оттуда уже работает.

Собственно, вопрос в том, что для вас будет быстрее - поднять скомпилированный шаблон из кэша, или скомпилировать его заново.

Обычно выходит, что на маленьких и простых чанках (как у сниппетов pdoTools) выигрыша нет, а лишних файлов много, а вот на больших и сложных чанках (которые вы наверняка создадите, используя возможности Fenom) разница уже может быть. Время компиляции и работы с кэшем выводится в &showLog=`1`, так что каждый может проверить сам.

Примеры

Стандартный чанк tpl.Tickets.comments.wrapper из компонента Tickets

<div>
    [[+modx.user.id:isloggedin:is=`1`:then=`
    <span>
        <label for="comments-subscribe">
            <input type="checkbox" name="" value="1" [[+subscribed:notempty=`checked`]] />
            [[%ticket_comment_notify]]
        </label>
    </span>
    `:else=``]]

    <h5>[[%comments]] (<span>[[+total]]</span>)</h5>

    <div>
        <ol>[[+comments]]</ol>
    </div>

    <div>
        <div></div>
        <div></div>
    </div>
</div>

Он же, переписанный для работы с Fenom

<div>
    {if $modx->user->isAuthenticated($modx->context->key)}
        <span>
        <label for="comments-subscribe">
            <input type="checkbox" name="" value="1" {$subscribed != '' ? 'checked' : ''} />
            {$modx->lexicon('ticket_comment_notify')}
        </label>
    </span>
    {/if}

    <h5>{$modx->lexicon('comments')} (<span>{$total}</span>)</h5>

    <div>
        <ol>{$comments}</ol>
    </div>

    <div>
        <div></div>
        <div></div>
    </div>
</div>

pdoTitle / Сниппеты / pdoTools / docs.modx.pro

Сниппет выводит оформленный тег title на страницу сайта, который состоит из имени страницы, имён родителей этой страницы и, других параметров.

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

Параметры

Сниппет не принимает никаких общих параметров pdoTools, из-за специфики своей работы. Но передаёт все полученные параметры во вложенный вызов pdoCrumbs.

Параметр По умолчанию Описание
&id 0 Идентификатор ресурса.
&limit 3 Лимит выборки родителей ресурса.
&titleField longtitle Поле текущего ресурса для вывода в заголовке страницы.
&cache Кэширование выборки родителей ресурса для заголовка страницы.
&cacheTime 0 Время актуальности кэша, в секундах.
&tplPages @INLINE ... Шаблон оформления пагинации в заголовке страницы.
&pageVarKey page Имя переменной для поиска номера страницы в url.
&tplSearch @INLINE ... Шаблон оформления поискового запроса в заголовке страницы.
&queryVarKey query Имя переменной поискового запроса в url.
&minQuery 3 Минимальная длина поискового запроса для вывода в заголовке страницы.
&outputSeparator / Разделитель элементов в заголовке страницы.
&registerJs 1 Вставить на страницу javascript с переменными для поддержки &ajaxMode сниппета pdoPage.

Поддержка навигации

pdoTitle определяет, когда на страницу был передан параметр &pageVarKey и выводит в title указание на это.

]

Функция работает и при включенном &ajaxMode сниппета pdoPage, тогда заголовок меняется без перезагрузки страницы.

Поддержка поиска

Если в url был передан параметр &queryVarKey, то сниппет вставит для него чанк &tplSearch в тег.

По умолчанию вставляется плейсхолдер [[+mse2_query]] сниппета mSearch3.

Кэширование

pdoTitle нужно вызывать некэшированным, чтобы он мог реагировать на параметры в url, но вы можете кэшировать внутренний вызов выборки родителей ресурса, который работает через pdoCrumbs.

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

Javascript переменные

Если включен параметр &registerJs, то сниппет вставит в страницу свои переменные в объекте pdoTitle.

Вы можете найти там разделитель элементовtitle и шаблон оформления постраничной навигации.

Примеры

Обычный вызов на странице:

<title>[[!pdoTitle]] / [[++site_name]]</title>

Вызов с увеличенной выборкой родителей ресурса и кэшированием:

<title>[[!pdoTitle?limit=`5`&cache=`1`]] / [[++site_name]]</title>

pdoField / Сниппеты / pdoTools / docs.modx.pro

Этот сниппет одновременно обладает возможностями getResourceField и UltimateParent, то есть выводит любое поле указанного ресурса или его родителя, включая ТВ параметры.

Отличием от аналогов является работа с документами любых контекстов и возможность указать дополнительные параметры при выборке, что позволяет не выводить поля, например, скрытых ресурсов. Так же с помощью указания параметра &class можно получить поле любого объекта MODX. Может быть вызван как фильтр вывода.

Параметры

Принимает общие параметры выборки и результатов pdoTools и некоторые свои:

Параметр По умолчанию Описание
&id Текущий документ Идентификатор ресурса.
&field pagetitle Поле ресурса.
&top Выбирает родителя указанного &id на уровне &top.
&topLevel Выбирает родителя указанного &id на уровне &topLevel от корня контекста.
&default Указывает поле ресурса, которое вернётся, если &field окажется пуст. Более быстрый аналог фильтра :default=
&output Указывает строку, которая вернётся, если и &default, и &field оказались пусты.
&toPlaceholder Если не пусто, сниппет сохранит все данные в плейсхолдер с этим именем, вместо вывода не экран.

Если указаны &top или &topLevel, а &context нет, то для его определения будет сделан дополнительный запрос в базу данных.

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

Примеры

Сниппет может быть вызван как фильтр вывода:

[[*id:pdofield=`longtitle`]]

При этом вы можете указывать параметры JSON массивом. Например, выбор второго родителя от ресурса и вывод его «longtitle»:

[[*id:pdofield=`{"top":2,"field":"longtitle"}`]]

Но лучше использовать обычный вызов - он и быстрее, и удобнее:

[[pdoField?
    &id=`[[*id]]`
    &field=`longtitle`
    &top=`2`
]]

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *