Урок 8. Вывод меню с помощью Wayfinder

Начинаем 8 урок MODx Revolution для новичков. Напоминаю мы делаем сайт для изучения MODx Revolution. На последнем уроке мы рассмотрели концепцию сниппетов, которые являются кусками PHP кода, который позволяет добавить функциональности в наш вебсайт. В этом уроке мы рассмотрим особенный сниппет – Wayfinder, и будем использовать его для создания динамического меню нашего сайта.

Что такое Wayfinder?

Wayfinder– это сниппет, который выводит неотсортированный список ссылок на ресурсы в вашем дереве сайта, тип вывода списка зависит от вызова сниппета и параметров данного вызова. В общих словах это значит, что когда вы помещаете вызов Wayfinder‘а в вашем шаблоне, он начинает искать ресурсы, которые отвечают заданным в нём параметрам и возращает список ссылок к этим ресурсам в формате неотсортированного списка либо в определенном вами формате.

Для чего использовать Wayfinder?

Обычно Wayfinder использую для создания динамической навигации по сайту, то бишь меню. Так как большинство HTML шаблонов используют неупорядочненные списки для создания меню, то Wayfinder является идеальным инструментом для этих целей. При создании сайта вы можете кропотливо вставлять ваши урлы в меню навигации, так как вы делали до этого в статическом HTML сайте. В то же время, каждый раз, когда необходимо удалить или создать страницу, то вам необходимо внести соответствующие изменения в вашем меню, поменять урлы. Использование сниппета Wayfinder для динамического генерирования ваших менюшек позволяют избежать этой головной боли, так как он автоматически определяет изменения и соответственно меняет ваше меню.

Wayfinder довольно-таки гибкий инструмент и позволяет определить, какие ресурсы включить или исключить из меню, каков шаблон меню, как глубина меню вашего сайта. Граница ваших возможностей определяется вашим HTML/CSS кодом.

Как использовать Wayfinder?

Как мы уже упомянули в предыдущем уроке, синтаксис вызова сниппетов выглядит так: [[!somesnippet]]

Это всего лишь базовый вызов и его не достаточно, кроме этого мы должны определить некоторые свойства данного вызова. В случае с Wayfinder`ом самый минимум, который необходимо определить в свойствах: где в дереве ресурсов Wayfinder должен начинать строить список ресурсов. Таким образом в вызове сниппета Wayfinder необходимо задать по крайней мере один параметр – начальный ID. Базовый вызов сниппета Wayfinder в таком случае будет выглядеть вот так:

Этот вызов говорит Wayfinder‘у начинать с корня дерева (ID 0 значит корень сайта) и показывает все ресурсы, которые опубликованы и у которых не стоит галочка в чекбоксе Hide from Menus (Спрятать от Меню).

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

Давайте взглянем на шаблон и код, который выводит данное меню:

Как вы видите, это вложенный неупорядочненный список. Давайте заменим этот код базовым вызовом Wayfinder и увидим, что у нас получится. Удалите код приведенный вверху и вставте вместо него:

Если вы используете тот же шаблон, что и я, то ваш код будет выглядет приблизительно вот так:

Сохраните шаблон и посмотрите на домашнюю страницу, она должна выглядет следующий вид:

Фантастика! Вы видите, что наше предыдущее меню, которое имело несколько пунктов, теперь заменено простым меню с одним лишь пунтктом – Home. Это говорит нам, что Wayfinder работает так как нужно и берет одну страницу из нашего сайта и выводит ее название в виде пункта меню.

Давайте создадим еще парочку ресурсов. Я собираюсь добавить страницу About с 3 дочерними страницами (MODx, страницы Tutorials, Contact и FAQ). Вы можете создать какие угодно ресурсы или страницы для вашего сайта. Цель этого упражнения – создать несколько ресурсов, чтобы Wayfinder‘у было что отображать.

Я закончил с созданием страниц и мое дерево ресурсов сайта выглядит вот так:

Теперь у нас есть несколько страниц, посмотрим как вызов Wayfinder‘а сгенерирует меню для нашего сайта:

Хорошей новостью является то, что все наши страницы появились в меню и нажимая на каждый пункт меню мы попадаем на соответствующую страницу. (Для тестирования этого элемента добавте какой-нибудь текст в каждую страницу, например на страницу About можете добавить “Это страница About” и эта сообщение появится при открытии страницы. Помните, что нам необходимо определять шаблон для каждой страницы, но в данный момент я не собираюсь об этом беспокоится).

Плохой новостью является та, что нарушилось форматирование меню, но мы можем это починить. Нажмите правой кнопкой мыши на вебстраницу и посмотрите исходный код (либо используйте для этого firebug), вы увидите что сейчас Wayfinder генерирует HTML следующего вида:

Как вы видите это выглядит очень похоже на наш начальный статичный код за некоторым исключением. Во-первых, Wayfinder сгенерировал <ul> пункт без класса sf-menu который применялся в нашем статичном коде. Шаблону необходим этот класс для работы с CSS. Также видно, что <li> пункты имеют параметр span, который относится к элементам текста ссылки в оригинальном статическом коде и его нет в сгенерированом Wayfinder‘ом коде. В дополнение, наш статический HTML код имеет класс acurrent-page-item, который не представлен в нашем коде сниппета Wayfinder. Все эти пропавшие куски делают вид нашего меню неприглядным.

Как настроить стиль вывода сниппета Wayfinder

Смотря на то, как Wayfinder генерирует код, у нас возникает вполне естественный вопрос: «Как нам добавить недостающие куски кода, чтобы мы хотели вывести меню в нужном для нас виде?» Ответ – очень легко, мы используем чанки шаблона для форматирования вывода сниппета Wayfinder.

Wayfinder гибкий инструмент и при помощи параметров можно определить внешний вид вывода. Некоторые общие параметры позволяют вам определить с какого уровня начинать построение меню, какие пункты не включать в меню и т.д. Другие параметры – это параметры шаблона, которые позволяют вам задать html код шаблона для вашего меню и др. Описания последних можно найти в официальной документации –http://rtfm.modx.com/display/ADDON/Wayfinder.

Возьмите на заметку: некоторые параметры Wayfinder имеют значение по умолчанию.

Это объясняет, например, почему в сгенерированном Wayfinder меню, пункт страницы Home имеет название класса “first active”. Это класс по-умолчанию, но мы можем перезаписать его обозначив собственные классы в чанках шаблона.

Мы будем использовать несколько параметров Wayfinder в этом уроке, но я советую вам изучить их все и поупражнятся в их использовании как можно больше, чтобы понять все их возможности. Так как параметры по-умолчанию Wayfinder чётко задокументированы на официальном сайте, было бы глупо рассказывать о них здесь. Мы будем использовать больше и всё больше из них, когда будем работать с различными меню.

Для начала работы над шаблоном меню давайте создадим несколько минишаблонов и сохраним их в чанках. Вы увидите, что в этих чанках мы используем код HTML, но заменяем динамические элементы заполнителями (или плейсхолдерами как их еще называют) синтаксис которых выглядит так:[[+placeholder]]. Заполнители, которые мы используем являются особенными в сниппете Wayfinder и их определение очевидно из названия, но вы всегда можете обратиться в документацию MODx за более полной справкой.

Вот чанки, которые я буду использовать для создания нашего шаблона:

7in1menuOuter – будет содержать HTML код для нашего внешнего ul контейнера.

Вы видите, что я добавил класс для внешнего ul. Альтернативным способом сделать это является использование wf.classes заполнителя и далее добавить имя класса к текущему вызову wayfinder используя параметр outerClass. Но для простоты давайте будем использовать первый способ, но оба из них будут работать нормально…

7in1menuRow – будет содержать HTML код пунктов меню первого уровня

Главной мыслью тут является та, что я добавил тег <span> к тексту ссылки меню как в оригинальном статичном HTML коде. Я также включил wf.classes заполнитель и это позволит мне определить класс для текущей страницы, который перезапишет класс “active”, который стоит у нас по-умолчанию.

7in1menuInner – будет содержать HTML код внутренних ul контейнеров

7in1menuInnerRow – будет содержать HTML код для строчек пунктов внутренних уровней

Снова я добавил тег <span> и включил заполнитель wf.classes.

Всё, теперь наши чанки шаблона на месте, как вы видите (для порядка, я поместил их в отдельную категорию) :

Теперь мы можем изменить вызов Wayfinder, таким образом мы можем использовать эти мини шаблоны для вывода Wayfinder. Если вы взгляните на список параметров шаблонизации (было бы полезно иметь перед глазами http://rtfm.modx.com/display/ADDON/Wayfinder открытым либо же распечатать и держать возле экрана), вы увидите, что я называл мои чанки похожими на соответсвующие параметры вызова сниппета. Это я сделал для удобства, это помогает мне отслеживать что к чему, когда я начинаю конструировать мой вызов. Давайте добавим параметры и вызовем наши чанки. Вызов Wayfinder теперь будет иметь вид:

Отлично, давайте взглянем на этот вызов. Вы видите, что мы используем параметры шаблонизации для вызова наших чанков так, что Wayfinder выводит нужный нам HTML с корректными классами. Я определил вызываемый hereClass параметр и дал ему значение current_page_item, чтобы он соответствовал статическому HTML шаблону. Можно заметить, что я оставил параметры firstClass и lastClass пустыми. Причиной этого является то, что мой HTML шаблон не устанавливает класс для первого и последнего пункта меню, поэтому чтобы избежать накладок я перезаписал в них пустые строки.

Давайте пройдем дальше и сохраним измененный Wayfinder вызов и обновим страницу и увидим, как изменился вид нашего меню:

Видно, что наше меню выглядит именно так, как мы хотели. Правильные стили используются в выпадающем меню. Если вы посмотрите на исходный код, то увидите, что сгенерированный Wayfinder‘ом HTML код изменился до неузнаваемости:

Этот код соответствует оригинальному статичному коду нашего шаблона, но он был сгенерирован вызовом Wayfinder.

Существует много других параметров, которые вы можете использовать вместе с Wayfinder для построение ваших меню. В следующих уроках мы рассмотрим сложные меню и как их интегрировать в Wayfinder. Подведем итог: сейчас наш сайт приобрел некоторую форму и у нас есть функциональное и динамичное меню.