Как вывести контент в ModX Revolution с помощью GetResources
Что такое getResources?
getResources это сниппет MODX Revolution, который извлекает содержимое полей из других ресурсов и выводит его в любом удобном для вас виде. Если вы знакомы MODX Evolution, getResources может считаться заменой Ditto.
Почему нужно использовать именно getResources?
getResources отлично подходит для случаев, где вам необходимо объединить и вывести информацию от различных ресурсов в одном месте и в необходимом формате. Наиболее очевидным применением сниппета getResources будет создание основной блоговой страницы сайта, другие возможные блоки использования - слайдеры, страница портфолио, новостная лента...
Как использовать сниппет getResources?
Ниже приведён список шагов описывающих процесс использования сниппета getResources. После того, как вы привыкните к его использованию, большинство описанных шагов будут происходить интуитивно, но так как вы только начинаете, то хорошо иметь под рукой некоторое подобие плана действий. Вот один описанный мною:
- Для начала установите сниппет getResources
- Далее необходимо решить как структурировать страницы, контент которых мы собираемся вывести и какой будет шаблон вывода страниц. Всё будет отличаться в зависимости от структуры вашего сайта и целей. Вы можете выводить отдельные страницы на вашем дереве сайтов либо размещать дочерние страницы в контейнере и использовать ИД контейнера, чтобы их вывести и др.
- Определиться какие поля будут показаны на выведенной странице. Вы можете, например, показать только список заголовков на вашем сайдбаре или показать только заголовок страницы и содержание, либо показать несколько полей и переменных шаблона, и т.д.
- Если у вас еще нет шаблона, то создайте шаблон для вашей странице вывода контента.
- Сделайте простой вызов getResources чтобы убедиться в том, что контент извлекается и выводится.
- Создайте чанк-шаблон для вывода полей, которые вы будете показывать на вашей странице.
- Добавьте нужные параметры в вызове сниппета getResources
Я детально и последовательно опишу каждый из описанных выше шагов. Если вы уже разбираетесь в построении шаблонов и разбираетесь в переменных шаблона и других вопросах шаблонизации, то можете смело переходить прямо к 5 шагу.
1. Установка getResources
Я уже установил getResources и мы будем его использовать для создания страницы статьи. Мы будем использовать для шаблона страницы блога шаблон 7 in 1 Business Success Site студии Themeforest. Страница блога (частично) будет выглядеть следующим образом:
Как видите, у нас есть страница с несколькими компонентами – заголовок, изображение, дата публикации, изображение и отрывок содержания со ссылкой “читать остальную часть записи” к целому посту. Этот шаблон мы будем использовать для объединённого вывода наших статей.
2.Подготовьте шаблон для вывода отдельной статьи:
После установки сниппета getResources, смотрим на оформить стуктуру страниц отдельного вывода статей. Для этого я буду использовать шаблон отдельного поста нашей темы, который я взял из файла single.html. Я уже портировал данный шаблон в свой шаблон и назвал его “7in1 Single Article”. Вот как мой “7in1 Single Article” шаблон будет выглядеть:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US"> <head profile="http://gmpg.org/xfn/11"> [[$7in1-header]] </head> <body> [[$7in1-logo-nav-search-bar]] <div class="clear"></div> <div id="page_container" class="grid_16"> <div id="container_bkgnd_btm" class="grid_16 alpha omega pngfix"> <div id="post_content" class="grid_11 lelfPadding20"> <div class="post-[[*id]] post hentry category-latest-news tag-tag3 tag-tag5 tag-tag7" id="post-[[*id]]"> <div class="post-top"> <div class="post-date"> <span class="day">[[*publishedon:strtotime:date=`%d`]]</span> <span class="month">[[*publishedon:strtotime:date=`%b`]]</span> <span class="year">[[*publishedon:strtotime:date=`%Y`]]</span> </div> <h3><a href="[[~[[*id]]]]" rel="bookmark" title="Permanent Link to [[*pagetitle]]">[[*pagetitle]]</a></h3> </div> <div class="entry"> <p><a href="[[*id]]"><img class="alignleft" title="[[*article_image_title]]" src="[[*article_image]]" alt="" width="618" height="197" /></a> [[*content]] <div class="postmetadata">Tags: <a href="#" rel="tag">tag3</a>, <a href="#" rel="tag">tag5</a>, <a href="#" rel="tag">tag7</a><br /> Posted in <a href="#" title="View all posts in Latest News" rel="category">Latest News</a> | <a href="#comments" title="Comment on Blog Post 5">6 Comments »</a></div> </div> </div> [[$articleCommentStuff_temp]] </div> <!-- end post_content --> [[$7in1-articles-sidebar]] </div> <!-- end container_bkgnd_btm --> </div> <!-- end page_container --> <div class="clear"></div> <div id="bottom_lid" class="grid_16 pngfix"> </div> [[$7in1-bottomwidgets]] <div id="footer_lid" class="grid_16 pngfix"> </div> [[$7in1-footer]] </body> </html>
Вы узнаете чанки шапки и подвала, мы уже их использовали, я добавил всего лишь два дополнительных чанка, один для содержимого сайдбара (7in1-articles-sidebar) и одного временного чанка (articleCommentStuff_temp) для секции комментирования, чтобы не нагромождать все элементы. В данный момент эти два чанка содержат статический контент нашего шаблона, но в следующий уроках мы сделаем их динамичными. Так же я добавил две дополнительных переменных шаблона, одну для вывода текста в теге изображения (article_image_title) и другую для самого изображения (article_image – {тип ввода – изображение, тип вывода – текст}). Также я добавил другие поля, такие как ИД поста, урлы и др., многое из этого должно быть вам понятно из предыдущих уроков.
Последним моментом, на который я хотел обратить ваше внимание - вывод поля даты. Он производится через publishedon используя при этом функцию PHP strtotime для показа даты в необходимом виде (как в шаблоне нашей темы). Более детально про функцию strtotime и форматирование дат - в конце этого поста ссылки.
Как я уже говорил, содержимое сайдбаров, теги и секция комментариев – статичны и мы над этим вопросом поработаем в следующих уроках.
3. Добавьте статьи
Отлично, теперь у нас есть шаблон для отдельных страниц и можно двигаться дальше. Создадим несколько статей для нашего сайта, используя этот шаблон, таким образом мы сможем проверить наш вызов getResources. В моём случае я создал контейнер Articles и установил шаблон для него Base Template, который я поменяю позже, когда буду готов выводить объединённый контент. Всередине я размещу парочку контейнеров для каждой категории или темы, которую покрывают мои статьи… например – новости, MODX уроки и др.
Размышляя об этом, я понимаю, что не хочу, чтобы мои статьи выводились в меню, также я хочу, чтобы они все использовали шаблон 7in1 Single Article. В рассуждениях о том, как же лучше сделать легче мою работу или работу клиента, я решил, что так как большинство новых ресурсов будут статьями, то есть здравый смысл в том, чтобы сделать соответствующими настройки по умолчанию для типа содержимого. Другими словами, сделайте все новые ресурсы с этого момента по умолчанию использующими шаблон 7in1 Single Article, а также они должны быть скрытыми от меню. Конечно же, можно отредактировать один за одним все ресурсы и это не будет проблемой, так как остальные мои страницы уже созданы и большинство новых ресурсов буду статьями. Итак, чтобы сделать это, идём System->System Settings, далее фильтр « area» и выбираем “Site”. Нужные настройки – Default Template, Hide from Menus Default.
После внесения изменений наблюдаем такую картину:
Теперь, при создании нового ресурса, он берёт шаблон отдельной статьи по умолчанию и уже поставлена галочка в Скрыть от меню (Hide From Menus).
Заметка: Обратите внимание, что такое поведение будет в случае, когда документ создаётся в корне. Если же вы зайдёте в любой контейнер и нажмёте «Создать документ здесь» (Create a Document Here), то он возмёт шаблон контейнера и скроет от меню. Поэтому будьте внимательны к настройкам каждого ресурса.
Давайте продолжим и создадим около 8 простых статей для нашего сайта, чтобы сниппет мог их объединить и вывести getResources. Я беру сгенерированный текст отсюда http://www.malevole.com/mv/misc/text/ и произовальные картинки из Гугла. Позже при наличии времени я заменю этот текст другим необходимым, здесь же в целях обучения будет достаточно наличия любого текста и картинок. Вот как выглядит дерево моего сайта в данный момент:
Теперь можно перейти к следующему этапу, который состоит в том, что мы созданим шаблон для нашей основной страницы блога и далее сформируем вызов сниппета getResources.
4. Подготовка страницы агрегированного контента.
Если вы используете тот же шаблон, что и я, то посмотрите на код и вы увидите, что он почти не отличается от кода для обычного шаблона, но без секции комментирования и других аналогичных элементов, поэтому можно использовать те же чанки и код, что мы использовали ранее. Вот как будет выглядеть шаблон 7in1 Aggregated Articles:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US"> <head profile="http://gmpg.org/xfn/11"> [[$7in1-header]] </head> <body> [[$7in1-logo-nav-search-bar]] <div class="clear"></div> <div id="page_container" class="grid_16"> <div id="container_bkgnd_btm" class="grid_16 alpha omega pngfix"> <div id="post_content" class="grid_11 lelfPadding20"> [[*content]] </div> <!-- end post_content --> [[$7in1-articles-sidebar]] </div> <!-- end container_bkgnd_btm --> </div> <!-- end page_container --> <div class="clear"></div> <div id="bottom_lid" class="grid_16 pngfix"> </div> [[$7in1-bottomwidgets]] <div id="footer_lid" class="grid_16 pngfix"> </div> [[$7in1-footer]] </body> </html>
Теперь я использую данный шаблон для вывода содержимого ресурсов - дочерних элементов следующих контейнеров – контейнер Articles и каждого из контейнеров для категорий, в моём случае - MODX News, MODX Web Development, MODX Tips and Tricks и Other Stuff. Теперь одна из категорий будет выглядить приблизительно так:
Давайте перейдём к выводу нашего контента.
5. Базовый вызов сниппета getResources
Перед тем, как мы начнём формировать вызов сниппета и работать с getResources, важно познакомится с несколькими вещами, которые могут легко ввести в заблуждение, если вы до этого не были знакомы с getResources и даже если вы знакомы. Я называю их мои getResources уловки!
- Вызов getResources по-умолчанию не содержит шаблона вывода. Вам необходим шаблон - tpl-чанк, чтобы определить вывод содержимого ресурса (ресурсов).
- getResources по-умолчанию не покажет ресурсы, которые скрыты от меню, поэтому вам необходимо задать &showHidden=`1`
- getResources по-умолчанию не включит поля содержимого ваших ресурсов, поэтому вам необходимо задать &includeContent=`1`
- В дополнение, если даже вы установите includeContent, сниппет getResources по-умолчанию не включит переменные шаблона, поэтому вам необходимо задать &includeTVs=`1` и &processTVs=`1`
- Если вы зададите includeTVs и processTVs, сниппет getResources будет ожидать, что в вашем шаблоне tpl, вы будете обозначать ваши переменные шаблона префиксом “tv.”. Вы можете перезаписать это добавив &tvPrefix=` ` и далее использовать только лишь имя переменной шаблона как заполнитель.
- Если вы выводите необходимые ресурсы через параметр &resources=`1,2,3`, где 1,2,3 - выводимые ресурсы, то не забудьте обязательно указать параметр &parents=`-1`
Есть еще много моментов, но это основные, в которых легко допустить ошибку.
Как и у всех других сниппетов, вызов getResources выглядит так:
[[!getResources]]
Базовый вызов позволит вам убедиться в том, что сниппет работает на нашем сайте. Если я размещу данный вызов на странице Articles page я ничего не получу. Вы можете подумать, что происходит что-то неправильное, но этому есть простое объяснение. Помните наш список находок? По умолчанию getResources ожидает, что ваши ресурсы не будут скрыты от меню, поэтому если вы хотите показать скрытые ресурсы вам необходимо добавить параметр &showHidden и установить его значение в true. Поэтому отредактируйте ваш вызов:
[[!getResources? &showHidden=`1` ]]
Если я перегружу страницу, то вот что я получу:
Выглядит плохо, но это значит, что getResources работает и извлекает контент. Что нам сейчас нужно сделать, так это привести контент к нужному виду и определить какими должны быть наши параметры: например, какие контейнеры использовать для параметра parents, как глубоко в дереве ресурсов делать выборку самих ресурсов, какие поля каждого ресурса мы хотим извлекать на нашу страницу статей и т.д.
6. Создание шаблонирующего tpl чанка для getResources
Для вывода страницы в нужном нам виде, нам необходимо создать чанк для шаблонизации отдельных элементов, которые будет извлекать наш сниппет getResources. Для этого, я возьму код из статического шаблона, который представляет каждый элемент поста и заменить статические элементы динамическим кодом.
При работе с tpl-чанком мы используем синтаксис заполнителя [[+field_name]] для динамических кусков.
Итак берём HTML код для вывода поста блога в статическом коде файла шаблона blog.html:
<div class="post-334 post hentry category-latest-news tag-tag3 tag-tag5 tag-tag7" id="post-334"> <div class="post-top"> <div class="post-date"> <span class="day">06</span> <span class="month">Jan</span> <span class="year">2010</span> </div> <h3><a href="single.html" rel="bookmark" title="Permanent Link to Blog Post 5">Blog Post 5</a></h3> </div> <div class="entry"> <p><a href="single.html"><img class="alignleft" title="slide_7_new" src="sample-data/slide_7_new.jpg" alt="" width="618" height="197" /></a>This is a test…Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim.</p> . . . <a href="#" class="more-link">Read the rest of this entry »</a></p> </div> <div class="postmetadata">Tags: <a href="#" rel="tag">tag3</a>, <a href="#" rel="tag">tag5</a>, <a href="#" rel="tag">tag7</a><br /> Posted in <a href="#" title="View all posts in Latest News" rel="category">Latest News</a> | <a href="single.html#comments" title="Comment on Blog Post 5">6 Comments »</a></div> </div>
Мы можем использовать данный код как базу нашего tpl чанка. Я заменю статические куски заполнителями. Для короткого содержимого поста я не хочу извлекать содержимое поля Content ресурса, мне нужна лишь короткая выдержка. Поэтому я буду использовать поле аннотация (Introtext) ресурса и далее выводить его, используя конструкцию [[+introtext]] можно также использовать Переменную шаблона [[+tv.tvname]]. Для вывода также можно использовать содержимое ресурса - поле Content. Я могу взять, например, первые 350 символов каждой статьи и вывести. Чтобы это сделать прикрепляю фильтр вывода :ellipsis=350 к моему заполнителю контента.
<div class="post-[[+id]] post hentry category-latest-news tag-tag3 tag-tag5 tag-tag7" id="post-[[+id]]"> <div class="post-top"> <div class="post-date"> <span class="day">[[+publishedon:strtotime:date=`%d`]]</span> <span class="month">[[+publishedon:strtotime:date=`%b`]]</span> <span class="year">[[+publishedon:strtotime:date=`%Y`]]</span> </div> <h2><a href="[[~[[+id]]]]" rel="bookmark" title="Permanent Link to [[+pagetitle]]">[[+pagetitle]]</a></h2> </div> <div class="entry"> <p><a href="[[~[[+id]]]]"><img class="alignleft" title="[[+tv.article_image_title]]" src="[[+tv.article_image]]" alt="" width="618" height="197" /></a> [[+content:ellipsis=`350`]]</p> <a href="[[~[[+id]]]]" class="more-link">Read the rest of this entry »</a></p> </div> <div class="postmetadata">Tags: <a href="#" rel="tag">tag3</a>, <a href="#" rel="tag">tag5</a>, <a href="#" rel="tag">tag7</a><br /> Posted in <a href="#" title="View all posts in Latest News" rel="category">Latest News</a> | <a href="single.html#comments" title="Comment on Blog Post 5">6 Comments »</a></div> </div>
Помните о том, что мы оставляем секцию тегов статической в данный момент, потом к этому мы ещё вернёмся.
Теперь я могу сохранить этот код в чанк, который я назову articleTpl. Далее я изменю мой вызов getResources, добавив туда мой tpl-чанк.
[[!getResources? &showHidden=`1` &tpl=`articleTpl` ]]
Если мы перегрузим нашу страницу Articles, то сразу увидим разницу:
Картинка постепенно оживает! Мы видим, что выводимый контент отображается с использованием правильного шаблона и мы можем нажать на заголовки, которые ведут на отдельные посты. Но еще предстоит еще много поработать.
Обратите внимание, что если у вас более 5 статей, то только 5 появятся на странице. Так происходит потому что по умолчанию getResources ограничен количеством извлекаемых страниц, которое равно 5.
Вы можете перезаписать данный параметр добавив &limit и указав необходимое количество статей. Я установлю количество статей равным 10, чтобы убедится, что у меня работает всё так как нужно.
Вспоминая наши уловки описанные выше, мы знаем причину того, что аннотации контента не показываются и причину того, что наши заполнители картинок пусты, потому что нам необходимо использовать includeContent, includeTVs и processTVs. Давайте изменим наш вызов и добавим следующие элементы:
[[!getResources? &showHidden=`1` &tpl=`articleTpl` &limit=`10` &includeContent=`1` &includeTVs=`1` &processTVs=`1`]]
Если мы обновим нашу страницу теперь, то увидим изображения и короткие в 350 символов аннотации извлекаемого содержимого, как я указал в шаблонирующем tpl-чанке:
Теперь наш контент извлекается и выводится нужнім образом, можем продолжить далее и улучшить наш вызов getResources, добавив другие параметры, которые нам могут понадобиться.
7. Добавьте другие параметры к вызову getResources
Итак мы добавили несколько параметров к нашему вызову и они помогают извлечь необходимые поля и вывести их соответствующим образом согласно нашего шаблона. Теперь мы можем продолжить и закончить формирование нашего вызова, добавив необходимые параметры. Полный список возможных параметров и их значение по умолчанию можно узнать на странице официальной документации getResources
Выбор параметров зависит от поведения сайта, которого нужно добится. В моём случае есть ещё парочка параметров, которые я хотел бы добавить.
Если вы взглянете на вывод, то заметите, что страница Articles извлекается на странице категории, то бишь MODX News, MODX Web Development, MODX Tips & Tricks и Other Stuff. Очевидно, что я этого не хочу. Вместо этого, я хочу обозначить, что эти субконтейнеры являются предками ресурсов, которые я хочу показать и я хочу проникать только на один уровень вниз до этих субконтейнеров. По умолчанию, getResources предполагает, что ресурс, в котором вы разместили вызов вашего сниппета – это родительский ресурс и он показывает все ресурсы под собой и их дочерние ресурсы на глубину равную 10.
Поэтому я изменю мой вызов и добавлю ID субконтейнеров тех ресурсов, которые я хочу включить и определю глубину отображения ресурсов:
[[!getResources? &showHidden=`1` &tpl=`articleTpl` &limit=`10` &includeContent=`1` &includeTVs=`1` &processTVs=`1` &parents=`13,14,15,16` &depth=`1`]]
Теперь данный вызов покажет только статьи сами по себе, а не их родительские контейнеры. Есть еще несколько спобов сделать так же. Например, если вы собираетесь добавить контейнеры других категорий в будущем и не хотите помнить о том, как возвращаться к вызову, чтобы добавить их ID к параметру &parents, то можете использовать &hideContainers=`1` и далее убрать или отредактировать параметр &depth, чтобы он отвечал структуре вашего сайта. В этом случае вы можете полностью убрать &parents, так как getResources будет считать, что вызов сниппета происходит в родительском ресурсе или для завершения редактирования задайте его значение равным [[*id]]:
[[!getResources? &showHidden=`1` &tpl=`articleTpl` &limit=`10` &includeContent=`1` &includeTVs=`1` &processTVs=`1` &parents=`[[*id]]` &hideContainers=`1`]]
Ну вот мы и закончили работу над нашим сниппетом getResources. Надеюсь, вы нашли что-то для себя полезное и можете разобраться с расскрытым здесь вопросом и использовать это в построении ваших сайтов.
Домашнее задание:
Вот маленькое домашнее задание для вас, чтобы протестировать знания, приобретённые в ходе урока.
- Поработайте над первой секцией сайдбара страницы articles, чтобы построить список и ссылки на категории статей. Можете использовать для этого Wayfinder или getResources, оставляю выбор за вами
- После этого, необходимо, чтобы страницы, на которые вели ссылки данных категорий содержали агрегацию контента только этой категории. Это просто сделать.