Оглавление

Парсер pdoTools

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

В старых версиях компонента, включение парсера нужно было подтверждать при установке, но с версии 2.1.1-pl он включается по умолчанию. Если, по каким-то причинам, вас это не устраивает — удалите значения из следующих системных настроек:

По умолчанию в MODx эти настройки пустые, они нужны только для подключения стороннего парсера, как в нашем случае.

Принцип работы

pdoParser может быть использован в двух случаях:

  1. При рендере чанка сниппетом — это происходит всегда и во всех сниппетах, использующих pdoTools, независимо от системных настроек.
  2. При рендере страницы — только если парсер включен в настройках системы.

Обработка чанка

Для обработки чанков в классе pdoTools есть 2 метода очень похожих на таковые в классе modX:

Основной особенностью работы этих методов является то, что для загрузки чанка используется protected метод _loadChunk, который может не только загружать чанк из базы данных, но и превращает в него произвольные строки.

Варианты чанков

Итак, оба метода pdoTools поддерживают следующие виды имён чанков:

@INLINE или @CODE

Один из самых популярных вариантов — указание тела чанка прямо на странице вызова сниппетов pdoTools. Например:

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

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

То есть, если вызвать сниппет на странице вот так:

[[!pdoResources?
    &parents=`0`
    &tpl=`@INLINE <p>[[+id]] - [[+pagetitle]]</p>`
]]

и в памяти системы при этом выставлены плейсхолдеры [[+id]] или [[+pagetitle]], то в сниппет придёт уже обработанный чанк и вы получите на странице одинаковые строки, типа:

15 - тест
15 - тест
15 - тест

Просто одинаковые значения, которые выставил какой-то другой сниппет раньше. Именно поэтому в примере у нас такие необычные плейсхолдеры — {{+}} вместо [[+]]. Системный парсер их не трогает, а pdoTools заменяет их на нормальные во время работы.

Вы можете использовать фигурные скобочки в качестве обрамления плейсхолдеров во всех чанках pdoTools — он сам превратит их в [[+]] при загрузке.

По этой же причине у вас никогда не будут работать вызовы сниппетов и фильтров в INLINE чанках. Вот так работать не будет:

[[!pdoResources?
    &parents=`0`
    &tpl=`@INLINE <p>[[+id]] - [[+pagetitle:default=`название страницы`]]</p>`
]]

А вот так — без проблем

[[!pdoResources?
    &parents=`0`
    &tpl=`@INLINE <p>{{+id}} - {{+pagetitle:default=`название страницы`}}</p>`
]]

Помните об этом нюансе при использовании INLINE чанков.

@FILE

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

pdoTools открывает такую возможность при указании @FILE:

/* modParser */
[!pdoResources?
    &parents=`0`
    &tpl=`@FILE resources/mychank.tpl`
]]

/* pdoParser */
{$_modx->runSnippet('!pdoResources', [
'parents' => 0,
'tpl' => '@FILE resources/mychank.tpl',
])}

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

Вы можете указать свою собственную директорию для файлов через параметр & elementsPath:

/* modParser */
[[!pdoResources?
    &parents=`0`
    &tpl=`@FILE resources/mychunk.tpl`
    &elementsPath=`/core/elements`
]]

/* pdoParser */
{$_modx->runSnippet('!pdoResources', [
'parents' => 0,
'tpl' => '@FILE resources/mychank.tpl',
'elementsPath' => '/core/elements',
])}

Содержимое чанка будет загружено из файла /core/elements/resources/mychunk.tpl от корня сайта.

@TEMPLATE

Этот тип чанка позволяет использовать шаблоны системы (т.е. объекты modTemplate) для оформления вывода.

/* modParser */
[[!pdoResources?
    &parents=`0`
    &tpl=`@TEMPLATE Base Template`
]]

/* pdoParser */
{$_modx->runSnippet('!pdoResources', [
'parents' => 0,
'tpl' => '@TEMPLATE Base Template',
])}

Если указан пустой шаблон и в выбранных записях есть поле template с id или именем шаблона, то запись будет обёрнута в этот шаблон:

/* modParser */
[[!pdoResources?
    &parents=`0`
    &tpl=`@TEMPLATE`
]]

/* pdoParser */
{$_modx->runSnippet('!pdoResources', [
'parents' => 0,
'tpl' => '@TEMPLATE',
])}

При выводе шаблона можно указывать и набор параметров (как у сниппетов):

/* modParser */
[[!pdoResources?
    &parents=`0`
    &tpl=`@TEMPLATE Base Template@MyPropertySet`
]]

/* pdoParser */
{$_modx->runSnippet('!pdoResources', [
'parents' => 0,
'tpl' => '@TEMPLATE Base Template@MyPropertySet',
])}

Тогда значения из этого набора будут вставлены в шаблон.

Обычные чанки

Это режим по умолчанию, который загружает чанк из базы данных по его имени:

/* modParser */
[[!pdoResources?
    &parents=`0`
    &tpl=`MyChunk`
]]

/* pdoParser */
{$_modx->runSnippet('!pdoResources', [
'parents' => 0,
'tpl' => 'MyChunk',
])}

Точно так же поддерживаются и наборы параметров:

/* modParser */
[!pdoResources?
    &parents=`0`
    &tpl=`MyChunk@MyPropertySet`
]]

/* pdoParser */
{$_modx->runSnippet('!pdoResources', [
'parents' => 0,
'tpl' => 'MyChunk@MyPropertySet',
])}

Эти способы загрузки чанков работают во всех родных сниппетах pdoTools и во всех других, которые используют методы pdoTools getChunk и parseChunk.

Метод getChunk

Объявление этого метода выглядит так:

getChunk(string $chunkName, array $properties, bool $fastMode = false)

Метод загружает указанный чанк (следуя указанию @BINDING, если есть) и полностью обрабатывает его, заменяя все плейсхолдеры на переданные значения (параметр $properties).

Третий параметр fastMode вырезает все оставшиеся необработанные плейсхолдеры, чтобы не было лишних тегов на странице. Если этого не сделать, то парсер будет пытаться рекурсивно разобрать эти теги (до 10 итераций по умолчанию), что может привести к замедлению работы.

Рекурсивный парсер — это одно из достоинств MODx и специально оставленные теги очень часто встречаются в логике работы сниппетов системы. Поэтому fastMode отключен по умолчанию и использовать его нужно, только если вы уверены в том, что делаете.

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

Метод parseChunk

А этот метод объявлен вот так:

parseChunk(string $name, array $properties, string $prefix = '[[+', string $suffix = ']]')

Он также создаёт чанк из указанного имени, разбирая @BINDING, если есть, а потом просто заменяет плейсхолдеры на значения, без особых обработок.

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

Обработка страницы

Если pdoParser включен в настройках, то он вызывается и для обработки всей страницы при выводе её пользователю.

При использовании этого парсера все чанки и дополнения MODx обрабатываются немного быстрее. Всего лишь «немного» потому, что он не берёт на себя условия и фильтры, обрабатывая только простенькие теги, типа [[+id]] и [[~15]]. Однако, он это делает быстрее modParser, потому что не создаёт лишних объектов.

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