getResources

Что такое getResources?¶

Универсальный сниппет для вывода списка ресурсов и их краткого описания.

Требования¶

• MODX Revolution 2.0.0-beta5 или новее
• PHP5 или новее

История¶

getResources написал Jason Coward (opengeek). Релиз вышел 30 июня 2009 года.

Скачать¶

Скачайте через менеджер MODX Revolution в разделе управление пакетами или из репозитория MODX Extras: https://modx.com/extras/package/getresources

Это не замена Ditto, а альтернативный компонент, который может выполнять часть задач более специализированных решений: Ditto, Wayfinder, Breadcrumbs и всё, что выводит свойства списка ресурсов (в MODX Evolution они назывались Documents).

Дополнительные материалы и руководства на русском языке: http://modx.by/docs/modx-add-ons/getresources/

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

Вызов сниппета getResources:

[[getResources]]

До версии 1.6.1-pl вызов без свойства &tpl выводил массив каждого ресурса в результате и его полей. С версии 1.6.1-pl поведение изменилось. Полный результат можно получить через «&debug=1»:

[[getResources? &debug=`1`]]
[[getResources? &parents=`choose_an_id` &debug=`1`]]

Доступные свойства¶

Свойства шаблонов¶

Имя	Описание	Значение по умолчанию	Добавлено в версии
tpl	Имя чанка как шаблона ресурса. Если не задано, свойства каждого ресурса выводятся в результат
tplOdd	Имя чанка как шаблона ресурса с нечётным значением idx (см. свойство idx)
tplFirst	Имя чанка как шаблона первого ресурса
tplLast	Имя чанка как шаблона последнего ресурса
tpl_N	Имя чанка как шаблона N-го ресурса, например &tpl_4=tpl4th
tpl_nN	Имя чанка как шаблона каждого N-го ресурса, например &tpl_n4=tpl4th применится к элементам, кратным 4		1.4.1
tplCondition	Поле ресурса для сравнения с ключами из свойства &conditionalTpls. Должно быть полем ресурса. С TV не работает.		1.5.0
conditionalTpls	JSON-объект: значения поля и связанные tpl-чанки при совпадении с полем из &tplCondition : &conditionalTpls={"1":"tplA","2":"tplB","3":"tplC"} [ПРИМЕЧАНИЕ: tplOdd, tplFirst, tplLast, * и tpl_{n} имеют приоритет над conditionalTpls]		1.5.0
tplPath	Опциональная папка для файловых чанков при использовании @FILE	assets_path+ "elements/chunks/"
tplWrapper	Имя чанка-обёртки для вывода [ПРИМЕЧАНИЕ: не работает с toSeparatePlaceholders]. Плейсхолдер для элементов: [[+output]].		1.6.0
wrapIfEmpty	Если true, обёртка из &tplWrapper выводится даже при пустом результате.	false	1.6.0
outputSeparator	Опциональная строка-разделитель между экземплярами tpl	"\n"
toPlaceholder	Если задано, результат записывается в этот плейсхолдер вместо прямого вывода.
toSeparatePlaceholders	Если задано, каждый результат записывается в отдельный плейсхолдер с этим именем и порядковым номером (с 0).		1.3.0

О @FILE и @INLINE tpl:

Любое свойство tpl можно начать с @FILE или @INLINE для файлового чанка или inline-разметки соответственно.

• @FILE: префикс указывает файл вместо чанка в базе данных. Путь и имя файла по умолчанию ищутся относительно assets_path + elements/chunks/, если не задано свойство tplPath.
• @INLINE: префикс задаёт разметку tpl прямо в значении свойства. Рекомендуется использовать только в [наборе свойств], иначе плейсхолдеры в inline-разметке могут обработаться до передачи содержимого в getResources, потому что кешируемые вложенные теги в MODX Revolution обрабатываются до начала обработки содержащего тега. После префикса нужен пробел, например @INLINE [[+pagetitle]]

Свойства выборки¶

Имя	Описание	Значение по умолчанию	Добавлено в версии
parents	Список ID родителей через запятую. Используйте -1, чтобы игнорировать родителей при указании resources для включения. Иначе getResources считает &parents текущим ресурсом и читает его дочерние элементы (плюс ресурсы из &resources = неожиданный результат).	ID текущего ресурса
resources	Список ID для включения в результат через запятую. Префикс «-» перед ID исключает ресурс из результата.
depth	Глубина поиска ресурсов от каждого родителя. Первый уровень под родителем имеет глубину 1	10
tvFilters	Фильтрация ресурсов по значениям TV. Формат: [( tvname)( operator)]( value). Два разделителя для комбинации условий. OR-фильтры через два символа pipe. OR выбирает ресурсы с одним из указанных значений TV. Подробнее ниже.
sortby	Любое поле ресурса (кроме TV. Для TV есть свойство sortbyTV). Частые поля: publishedon, menuindex, pagetitle и др. Полный список см. в документации по ресурсам. Указывайте только имя поля, без синтаксиса тега. При сортировке по template, publishedby и подобным используются сырые значения (ID шаблона или пользователя, а не имена). Подробнее ниже.	createdon
publishedon	Изменено в 1.3.0
sortbyAlias	Псевдоним запроса для поля sortby
sortbyEscaped	Экранирует имя поля из sortby
sortdir	Направление сортировки	DESC
sortbyTV	TV для сортировки		1.2.0
sortdirTV	Направление сортировки при sortbyTV	DESC	1.2.0
sortbyTVType	Тип данных sortby TV: string, integer, decimal, datetime	string	1.3.0
limit	Ограничивает число возвращаемых ресурсов. 0 означает отсутствие ограничения.	5
offset	Смещение: сколько ресурсов из выборки пропустить	0
where	JSON-выражение для дополнительных условий WHERE. Пример ниже. См. xPDOQuery.where
context	Список ключей контекстов для ограничения результата. Если пусто, используются контексты всех указанных родителей (все контексты при 0)

Использование &tvFilters¶

Для &tvFilters значение может выглядеть так:

   mytv==somevalue||mytv==othervalue

Фильтр «и» через запятую. Все условия должны выполняться.

   mytv==somevalue,othertv==othervalue

Для сложной фильтрации можно группировать условия. Сначала разделение по OR (||), затем по AND (,). Пример:

   mytv==foo||mytv==bar,bartv==3||bartv==1

Ресурсы отфильтруются по одному из условий:

• mytv LIKE foo, или
• mytv LIKE bar AND bartv LIKE 3, или
• bartv LIKE 1

Примеры выше ищут точные значения. Символ процента (%) работает как wildcard. Например:

   mytv==%a%

Подходит любой ресурс, где в значении mytv есть «a».

   mytv==a%

Подходит ресурс, где значение mytv начинается с «a»

   mytv==%a

Подходит ресурс, где значение mytv заканчивается на «a».

Можно комбинировать с разделителями OR (||) и AND (,) выше.

Функция смотрит на сырое значение TV конкретного ресурса. Значение должно быть явно задано для ресурса и не обработано типом вывода TV (или это значение по умолчанию в релизах до 1.4.2-pl. В 1.4.2-pl добавлена фильтрация с учётом значений по умолчанию). Для TV типа «autotag» сырое значение представляет собой список через запятую, а не отдельные теги как в менеджере.

Новые операторы фильтрации в 1.4.2-pl:

С релиза 1.4.2-pl getResources поддерживает новые операторы сравнения. Для многих из них числовые значения автоматически приводят TV к числу перед сравнением.

Список допустимых операторов:

Оператор фильтра	SQL-оператор	Приводит числа	Примечания
<=>	<=>	Да	равенство с учётом NULL
===	=	Да
!==	!=	Да
<>	<>	Да
==	LIKE	Нет
!=	NOT LIKE	Нет
<<	<	Да
<=	<=	Да
=<	=<	Да
>>	>	Да
>=	>=	Да
=>	=>	Да

Использование &sortby¶

В sortby можно передать любое поле ресурса: pagetitle, alias, publishedon, menuindex и т.д.

Случайная сортировка через RAND():

&sortby=`RAND()`

С версии 1.3.0 можно передать JSON-массив для сортировки по нескольким полям:

&sortby=`{"publishedon":"ASC","createdon":"DESC"}`

Сортировка в заданном порядке по списку ID ресурсов:

&sortby=`FIELD(modResource.id, 4,7,2,5,1 )`

То же возможно, если отсортированные ID лежат в TV:

&sortby=`FIELD(modResource.id,[[*templateVariable]])`

Иногда нужно (неочевидно) явно указать направление сортировки:

&sortby=`FIELD(modResource.id, 4,7,2,5,1 )` &sortdir=`ASC`

Прочие свойства¶

Имя	Описание	Значение по умолчанию	Добавлено в версии
showUnpublished	Если true, показывает также неопубликованные ресурсы.	0
showDeleted	Если true, показывает ресурсы независимо от пометки удаления.	0
showHidden	Если true, показывает ресурсы, скрытые из меню.	0
hideContainers	Если задано, не показывает ресурсы-контейнеры (isfolder).	0
includeContent	Включать ли content каждого ресурса в результат	0
includeTVs	Включать ли значения TV в свойства, доступные шаблону каждого ресурса	0
includeTVList	Опциональный список имён TV через запятую для явного включения при includeTVs = 1		1.4.0
prepareTVs	Подготавливает значения TV, зависящие от источника медиа.	1	1.5.0
prepareTVList	Ограничивает подготовку TV указанными именами через запятую		1.5.0
processTVs	Обрабатывает значения TV так же, как на суммируемом ресурсе. TV должны быть включены (includeTVs/includeTVList).	0
processTVList	Список имён TV для явной обработки. TV должны быть включены через includeTVs/includeTVList		1.4.0
tvPrefix	Префикс для свойств TV	tv.
idx	Стартовое значение idx ресурсов. Свойство увеличивается при выводе каждого ресурса	1
first	idx, который представляет первый ресурс	1
last	idx последнего ресурса. По умолчанию: число суммируемых ресурсов + first - 1
totalVar	Ключ плейсхолдера с общим числом ресурсов в выборке без учёта limit.	total
debug	Если true, отправляет SQL-запрос в лог MODX.	false

Доступные плейсхолдеры¶

Плейсхолдеры в форматирующих чанках getResources в основном зависят от выводимых ресурсов.

См. All Tags на странице «Commonly Used Template Tags». Там перечислены свойства, доступные всем ресурсам.

Если у ресурса есть TV, для них будут плейсхолдеры (с префиксом из &tvPrefix).

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

Плейсхолдер	Описание
[[+idx]]	Увеличивается на каждой итерации, начиная с 1 (или значения из &idx)

Примеры¶

Подробные примеры и руководства см. в подразделе Примеры.

Вывод списка дочерних ресурсов текущего ресурса с чанком myRowTpl:

[[getResources? &parents=`[[*id]]` &tpl=`myRowTpl`]]

Вывод всех ресурсов под ресурсом с ID 5, кроме ресурса 10, с чанком myRowTpl:

[[getResources? &parents=`5` &resources=`-10` &tpl=`myRowTpl`]]

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

[[getResources? &parents=`-1` &resources=`10,11,12` &tpl=`myRowTpl`]]

Топ-5 последних опубликованных ресурсов под ресурсом с ID 5 с tpl blogPost:

[[getResources? &parents=`5` &limit=`5` &tpl=`blogPost` &includeContent=`1`]]

Список дочерних ресурсов текущего ресурса по шаблону ресурса:

[[getResources? &parents=`[[*id]]` &where=`{"template:=":8}` &tpl=`myRowTpl`]]

Список дочерних ресурсов, где ID шаблона 1 или 2:

[[getResources? &parents=`[[*id]]` &where=`{"template:=":1, "OR:template:=":2}` &tpl=`myRowTpl`]]

Список дочерних ресурсов, где ID шаблона 1, 2 или 3 (одно имя ключа нельзя использовать дважды):

[[getResources? &parents=`[[*id]]` &where=`{"template:IN":[1,2,3]}` &tpl=`myRowTpl`]]

Сообщение при пустом результате (аналог параметра empty в Ditto):

[[getResources:default=`No results found`? &parents=`[[*id]]` &tpl=`myRowTpl`]]

Пример с inline tpl

[[getResources? &tpl=`@INLINE <li title="[[+longtitle]]">[[+pagetitle]]</li>`]]

Обёртка результата getResources в другую разметку (как свойство &outerTpl, которого нет у getResources. С версии 1.6.0 можно так или через &tplWrapper).

[[getResources? ... &toPlaceholder=`results`]]
[[+results:notempty=`<ol>[[+results]]</ol>`]]

Вывод TV через getResources¶

По умолчанию getResources не загружает значения TV, чтобы ускорить выборку. Для вывода TV добавьте параметры:

&includeTVs=`1` &processTVs=`1`

Также нужно либо добавить префикс tv. ко всем TV, либо указать в вызове:

&tvPrefix=``

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

[[+tv.my_tv]]

Постраничный вывод через getPage¶

В связке с getPage (или pdoPage) getResources даёт гибкую постраничную навигацию.

Примеры¶

Первые 10 ресурсов под ID 17, не глубже 2 уровней, сортировка по publishedon, tpl blogListPost, с TV и content:

[[!getPage?
    &elementClass=`modSnippet`
    &element=`getResources`
    &parents=`17`
    &depth=`2`
    &limit=`10`
    &pageVarKey=`page`
    &includeTVs=`1`
    &includeContent=`1`
    &tpl=`blogListPost`
]]
<div class="paging">
    <ul class="pageList">
        [[!+page.nav]]
    </ul>
</div>

и чанк blogListPost:

<div class="blogPost">
    <div class="date">[[+publishedon:strtotime:date=`%b %d %Y`]]</div>
    <h2><a href="[[~[[+id]]]]" title="[[+pagetitle]]">[[+pagetitle]]</a></h2>
    <p class="author">
        <strong>Author:</strong>
        <span class="author">[[+createdby:userinfo=`username`]]</span>
    </p>
    <p class="summary">[[+introtext]]</p>
    <p class="readmore">
        <a href="[[~[[+id]]]]"><span>Read more</span></a>
    </p>
    <div class="clear"></div>
</div>
<hr/>

Устранение неполадок¶

Ничего не происходит¶

Перед отладкой проверьте, установлено ли дополнение на сайте.

Выводится массив атрибутов¶

Вы не указали параметр &tpl. Без &tpl сниппет получит ресурсы, но не знает, как их форматировать. Добавьте &tpl в вызов, например:

[[!getResources? &parents=`5` &limit=`5` &tpl=`blogPost`]]

Или опечатка в имени чанка. &tpl задан, но чанк не существует. getResources не сможет отформатировать результат.

Или при корректном &tpl вы забыли амперсанд у другого параметра. Например:

limit=`5`

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

&limit=`5`

Один ресурс выводится несколько раз (1.2.2 и более ранние релизы)¶

Если один ресурс повторяется в списке, уберите параметр &sortbyTV.

Нет content¶

Ресурсы выбираются верно, часть разметки отображается, но [[+content]] пуст. Добавьте &includeContent=1.

Проблемы кеширования с tpl, tpl_N, tpl_nN, tplFirst, tplLast или tplOdd¶

При использовании этих параметров часто хочется переиспользовать tpl-чанк. Пример:

Общий tpl-чанк: [[$GenericTplChunk]]

<div>Hi [[+pagetitle]]</div>

Четвёртый tpl-чанк (tpl_nN): [[$4thTplChunk]]

<div class="highlight">[[$GenericTplChunk]]</div>

Если результат пустой или странный, причина в кешировании MODX. Некешируемый вызов чанка не поможет. Нужен обходной приём: фиктивный тег при вызове общего чанка.

<div class="highlight">[[$GenericTplChunk? &idx=`[[+idx]]` ]]</div>

Примечание: вызывать чанк некешируемым не обязательно.

Источник: http://forums.modx.com/thread/43748/chunk-inside-getresources-template-not-processed-correctly

См. также¶

Если нужно одно поле из другого ресурса, используйте getResourceField.

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

Budget

$204 per month—let's make that $500!

Learn more