Wayfinder
Последнее обновление not available | История страницы | Улучшить эту страницу | Сообщить о проблеме
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 moreWayfinder это Сниппет от kylej, который сканирует указанную часть дерева документов MODX, находит все документы, которые соответствуют заданным критериям (определяются параметрами), и выводит отформатированный список этих документов. Форматирование вывода управляется шаблонами и может содержать любую комбинацию HTML, CSS и JavaScript, что даёт огромную гибкость.
Основное назначение Wayfinder: генерировать навигационные меню, которые автоматически обновляются при изменениях в дереве документов, но его можно использовать и для других задач.
Поскольку вы можете вызывать Wayfinder несколько раз на одной странице, и каждый вызов может указывать другую секцию дерева документов, на одной странице может быть несколько навигационных меню или списков документов. Например, вы можете разместить главное меню вверху страницы, а по бокам вторичные меню для продуктов, услуг, команд, ролей и т. д. Каждое из них относится к своей секции дерева документов.
Обратите внимание: после выхода Revolution доступны два типа сниппетов Wayfinder, по одному для каждой версии. Для ясности на этой странице в примерах используется синтаксис Evolution. В целом функциональность и параметры двух версий совпадают. В Revolution сниппеты нужно вызывать через [[Wayfinder? &...]], а не через [!Wayfinder? &...!].
Обсуждения Wayfinder на форумах MODX: https://forums.modx.com/index.php/board,182.0.html.
Если вы хотите прочитать всё о Wayfinder, на форуме есть 148-страничная электронная книга Kongondo, которая охватывает все аспекты Wayfinder. Подробнее здесь.
История¶
Wayfinder полностью переработан из исходного построителя навигации DropMenu, чтобы упростить создание пользовательской навигации с помощью Чанков в качестве шаблонов вывода. Благодаря шаблонам многие параметры больше не нужны для гибкого вывода в виде таблиц, неупорядоченных или упорядоченных списков (UL или OL), списков определений (DL) или в любом другом формате.
История версий¶
| Version | Released | MODX version | Notes |
|---|---|---|---|
| 0.9 beta 1/2/3 | Aug/Sept 2006 | 0.9.2.1 | Initial release |
| 1.0 | Oct 23, 2006 | 0.9.2.1 | |
| 1.0.1 | Nov 07, 2006 | 0.9.2.1 - 0.9.5 | |
| 2.0 | Feb 27, 2007 | 0.9.5 + | Current release for Evolution |
| 2.1.1 beta 1 | May 21, 2009 | 2.0.0-beta 1 | |
| 2.1.1 beta 2 | Oct 20, 2009 | 2.0.0-beta 4 | |
| 2.1.1 beta 4 | Nov 05, 2009 | 2.0.0-beta 5 + | |
| 2.3.1 | May 18, 2011 | 2.0+ | |
| 2.3.2 | Sept 20, 2011 | 2.0+ | |
| 2.3.3 | Oct 31, 2011 | 2.0+ | Current release for Revolution |
Установка¶
Загрузка¶
- Скачайте последнюю версию Wayfinder для Revolution из репозитория дополнений MODX или установите через Управление пакетами.
- Скачайте версию 2.0 для Evolution с MuddyDogPaws.
Evolution (и ранее)¶
MODX версии 0.9.5-1.0 включает Wayfinder в установщик по умолчанию. Чтобы добавить Wayfinder в более старую версию MODX или обновить Wayfinder в Evolution:
- Скачайте необходимые файлы по ссылке выше.
- Создайте новый сниппет в Менеджере MODX (Элементы -> Управление элементами -> Сниппеты) и назовите его Wayfinder.
- Скопируйте содержимое snippet.wayfinder.tpl.php в содержимое сниппета.
- Создайте новую папку в файловой системе в /assets/snippets/ и назовите её wayfinder.
- Скопируйте файл wayfinder.inc.php в новую папку.
Revolution¶
В MODX Revolution Wayfinder можно скачать через Управление пакетами. Откройте Управление пакетами, нажмите «Download Extras», перейдите в Navigation -> Wayfinder и скачайте последнюю версию. Затем щёлкните правой кнопкой мыши в сетке Packages и выберите Install. После установки всё готово.
Начало работы¶
Минимальный вызов сниппета Wayfinder:
[[Wayfinder? &startId=`0`&level=`1`]]
выведет HTML для многоуровневого неупорядоченного списка всего дерева документов (с определёнными исключениями), где каждый элемент списка это ссылка на соответствующий документ в дереве документов MODX.
См. Вводные примеры Wayfinder для подробных примеров сравнения вызовов сниппета Wayfinder с HTML-выводом.
Параметры¶
Общие параметры¶
| Parameter | Description | Default |
|---|---|---|
| &startId | Начальная точка (ID документа), с которой меню строит список документов. Укажите 0, чтобы начать с корня сайта. | current docId |
| &displayStart | Показывать документ, указанный в &startId, в меню. | 0 |
| &level | Глубина (число уровней) для построения меню. «0» проходит все уровни. | 0 |
| &limit | Параметр limit заставляет Wayfinder обрабатывать только указанное число элементов на каждом уровне. | 0 |
| &ignoreHidden | Игнорировать флажок «Show in menu» для документов и всё равно включать их в меню. | 0 |
| &ph | Имя плейсхолдера для записи результатов вывода вместо прямого возврата. | 0 |
| &debug | Установите «1», чтобы включить режим отладки для дополнительной диагностики. | 0 |
| &hideSubMenus | Установите «1», чтобы выводить только активное подменю. | 0 |
| &removeNewLines | Установите «1», чтобы удалить символы перевода строки из вывода. | 0 |
| &textOfLinks | Поле, из которого берётся текст ссылки. Возможные значения: menutitle, id, pagetitle, description, parent, alias, longtitle, introtext | menutitle |
| &titleOfLinks | Поле, из которого берётся атрибут title ссылки. Возможные значения: menutitle, id, pagetitle, description, parent, alias, longtitle, introtext | pagetitle |
| &rowIdPrefix | Если задан, создаёт уникальный ID для каждого элемента. Значение будет rowIdPrefix + docId. | 0 |
| &useWeblinkUrl | При значении 1 ссылка, указанная в документе weblink, выводится в плейсхолдер [ wf.link] вместо ссылки на сам weblink. | 1 |
| &includeDocs | Список ID документов через запятую для включения в меню. | |
| &excludeDocs | Список ID документов через запятую для исключения из меню. | 0 |
| &cacheResults | кэширует запросы для более быстрой загрузки ( added in 2.2.0-rc1) | |
| &cacheTime | Число секунд хранения кэшированного меню, если cacheResults равен 1. Установите 0 для бессрочного хранения до ручной очистки кэша. | 3600 |
| &contexts | Контексты для построения меню. По умолчанию используется текущий контекст. ( added in 2.2.0-rc1) | |
| &startIdContext | ( added in 2.2.0-rc1) | |
| &config | внешний php-файл для настройки Wayfinder ( see core/components/wayfinder/configs for examples) | |
| &scheme | формат генерации URL. Возможные значения (на основе вызова API makeURL): -1 : (значение по умолчанию) URL относительно site_url, 0: see http, 1: see https, full: URL абсолютный, с префиксом site_url из конфигурации, abs: URL абсолютный, с префиксом base_url из конфигурации, http: URL абсолютный, принудительно http, https: URL абсолютный, принудительно https (added in 2.3.1-pl) |
-1 |
| &sortBy | Поле для сортировки, например «published» | |
| &sortOrder | Порядок сортировки: «ASC» или «DESC» | |
| &where | Фильтрация в стиле JSON. Например, чтобы скрыть блог или новости из дополнения Articles: &where=\[{"class\_key:!=": "Article"}\] |
|
| &hereId | Задаёт текущий ID для сниппета. Используйте значение [[*id]], если шаблон, указанный в hereTpl и activeRowParentTpl, не применяется к пункту меню корректно. |
iterated ID |
| &hereTpl | Шаблон hereTpl используется, когда текущий элемент отображается в меню. |
Параметры шаблонов¶
Эти параметры указывают чанки с шаблонами, которые управляют генерацией вывода Wayfinder.
В текущей версии WayFinder для Revolution вы можете обращаться к своим TV через плейсхолдер без префикса «wf.», например [[+my\_TV]]
На момент написания возвращается только сырое значение TV без форматирования. Например, если TV это изображение, обычное использование TV в шаблоне вернёт полный тег img, а внутри tpl WayFinder только путь к изображению.
Если вам нужно, чтобы MODX 2.x обработал TV (например, TV изображения с base path/url как опцией ввода (с MODX 2.1.x) или со значением @inherit), вы можете вызвать сниппет внутри шаблона строки wayfinder (&rowTpl). Допустим, ваш TV изображения называется icon. Обычно вы используете что-то вроде:
... <img src="[[+icon]]" /> ...
Но это не даст полностью обработанный TV. Измените код так:
... <img src="[[processTV? &myId=`[[+id]]` &myTV=`icon` ]]" /> ...
В сниппете processTV разместите этот php-код:
<?php
$doc = $modx->getObject('modResource', $myId);
return $doc->getTVValue($myTV);
В результате вернётся полностью обработанный TV изображения.
&outerTpl¶
Имя чанка с шаблоном для внешнего контейнера. Если не указан, предполагается строка с [[+wf.wrapper]]
Доступные плейсхолдеры:
- wf.classes - выводит соответствующие классы (включая class=" ")
- wf.classnames - выводит соответствующие классы (без class=" ")
- wf.wrapper - выводит внутреннее содержимое (строки). Этот плейсхолдер обязателен.
Обратите внимание: плейсхолдеры нужно оборачивать в соответствующие теги.
Evolution: [+wf._____+]
Revolution: [[+wf._____]]
Пример чанка &outerTpl (Evo):
<ul id="topnav"[+wf.classes+]>[+wf.wrapper+]</ul>
Revo:
<ul id="topnav"[[+wf.classes]]>[[+wf.wrapper]]</ul>
В таблице ниже перечислены другие параметры для изменения вывода с теми же плейсхолдерами, что и у &outerTpl.
| Parameter | Description |
|---|---|
| &innerTpl | Имя чанка с шаблоном для любых подпапок, перечисленных в меню. |
&rowTpl¶
Имя чанка с шаблоном для обычных строк. Доступные плейсхолдеры:
- wf.classes - выводит соответствующие классы (включая class=" ")
- wf.classnames - выводит соответствующие классы (без class=" ")
- wf.link - значение href для ссылки
- wf.title - текст title ссылки из поля, указанного в параметре &titleOfLinks
- wf.linktext - текст ссылки из поля, указанного в параметре &textOfLinks
- wf.wrapper - выводит внутреннее содержимое, например подменю
- wf.id - выводит уникальный атрибут ID. Нужно указать параметр &rowIdPrefix, чтобы плейсхолдер получил значение. Значение: ваш префикс + docId.
- wf.attributes - выводит атрибуты ссылки текущего элемента
- wf.docid - идентификатор документа текущего элемента
- wf.description - описание текущего элемента
- wf.level - текущая глубина элемента (added in v2.3.3)
Обратите внимание: плейсхолдеры нужно оборачивать в соответствующие теги.
Evolution: [+wf._____+]
Revolution: [[+wf._____]]
Начиная с версии 2.3.0, вы можете использовать плейсхолдеры для всех полей Resource, например [[+introtext]], [[+menutitle]], [[+published]] и т. д.
Начиная с версии 2.3.2 добавлен плейсхолдер [[+protected]], равный 1, если Resource защищён группой ресурсов.
Примеры чанка &rowTpl (или связанного):
<li[+wf.id+][+wf.classes+]><a href="[+wf.link+]" title="[+wf.title+]" [+wf.attributes+]>[+wf.linktext+]</a>[+wf.wrapper+]</li>
<li><a href="[+wf.link+]">[+wf.linktext+]</a> - [+wf.description+] [+wf.wrapper+]</li>
Revo:
<li[[+wf.id]][[+wf.classes]]><a href="[[+wf.link]]" title="[[+wf.title]]" [[+wf.attributes]]>[[+wf.linktext]]</a>[[+wf.wrapper]]</li>
<li><a href="[[+wf.link]]">[[+wf.linktext]]</a> - [[+wf.description]] [[+wf.wrapper]]</li>
В таблице ниже перечислены другие параметры для изменения вывода с теми же плейсхолдерами, что и у &rowTpl.
| Parameter | Description |
|---|---|
| &startItemTpl | Имя чанка с шаблоном для начального элемента, если включено через параметр &displayStart. Примечание: шаблон по умолчанию показывает начальный элемент, но не делает его ссылкой. Если ссылка не нужна, класс можно задать шаблону по умолчанию через параметр &firstClass=className. |
| &parentRowHereTpl | Имя чанка с шаблоном для текущего документа, если он контейнер и имеет дочерние элементы. Не забудьте плейсхолдер [ wf.wrapper] для вывода дочерних документов. |
| &parentRowTpl | Имя чанка с шаблоном для любого документа-контейнера с дочерними элементами. Не забудьте плейсхолдер [ wf.wrapper] для вывода дочерних документов. |
| &hereTpl | Имя чанка с шаблоном для текущего документа. |
| &innerTpl | Имя чанка с шаблоном для каждого подменю. Если innerTpl не указан, вместо него используется outerTpl. |
| &innerRowTpl | Имя чанка с шаблоном для строк в подпапке. |
| &innerHereTpl | Имя чанка с шаблоном для текущего документа в подпапке. |
| &activeParentRowTpl | Имя чанка с шаблоном для элементов-контейнеров с дочерними элементами, которые сейчас активны в дереве. |
| &categoryFoldersTpl | Имя чанка с шаблоном для папок категорий. Папки категорий определяются пустым шаблоном или атрибутом ссылки rel="category". |
&parentRow и &activeParentRow требуют, чтобы у родительского ресурса была включена настройка «Container».
Пример использования &startItemTpl:
<h2 class="menustart"><a href="[+wf.link+]">[+wf.linktext+]</a></h2>[+wf.wrapper+]
Параметры имён CSS-классов¶
Вы можете использовать CSS для управления внешним видом (и в некоторых случаях поведением) различных частей сгенерированного вывода. Но вы должны указать Wayfinder, какие имена CSS-классов использовать и с какими частями вывода их связывать.
| Parameter | Description | Default |
|---|---|---|
| &firstClass | CSS-класс для первого элемента на данном уровне меню. | |
| &lastClass | CSS-класс для последнего элемента на данном уровне меню. | last |
| &hereClass | CSS-класс для элементов, показывающих текущее положение по всей цепочке. | active |
| &selfClass | CSS-класс для текущего элемента. | |
| &parentClass | CSS-класс для пунктов меню-контейнеров с дочерними элементами. | parent |
| &rowClass | CSS-класс для каждой выходной строки | |
| &levelClass | CSS-класс для каждого уровня строки. К указанному классу добавляется номер уровня (level1, level2, level3 и т. д., если указано «level»). | |
| &outerClass | CSS-класс для внешнего шаблона. | |
| &innerClass | CSS-класс для внутреннего шаблона | |
| &webLinkClass | CSS-класс для элементов weblink. |
Пример:
Просто укажите параметры классов в вызове сниппета, чтобы добавить имена классов в вывод.
Например, добавление &levelClass=level даст
<li class="level2">
Параметры встраивания кода¶
Если для вывода вызова Wayfinder нужны определённые CSS или JavaScript, вы можете хранить CSS в одном чанке, а JavaScript в другом, затем использовать эти параметры, чтобы Wayfinder скопировал один или оба чанка в секцию HEAD страницы, на которой выполняется вызов Wayfinder.
| Parameter | Description |
|---|---|
| &cssTpl | Имя чанка с CSS, который нужно добавить на страницу при наличии вызова Wayfinder. |
| &jsTpl | Имя чанка с JavaScript, который нужно добавить на страницу при наличии вызова Wayfinder. |
Значения по умолчанию в Revolution¶
| Parameter | Default value |
|---|---|
| &outerTpl | <ul[[+wf.classes]]>[[+wf.wrapper]]</ul> |
| &rowTpl | <li[[+wf.id]][[+wf.classes]]><a href="[[+wf.link]]" title="[[+wf.title]]" [[+wf.attributes]]>[[+wf.linktext]]</a>[[+wf.wrapper]]</li> |
| &startItemTpl | <h2[[+wf.id]][[+wf.classes]]>[[+wf.linktext]]</h2>[[+wf.wrapper]] |
Примеры¶
См. Вводные примеры Wayfinder для подробных примеров сравнения вызовов сниппета Wayfinder с HTML-выводом.
Минимальный вызов Wayfinder¶
Вызов сниппета:
[[Wayfinder? &startId=`0`]]
выведет HTML для многоуровневого неупорядоченного списка всего дерева документов (с определёнными исключениями), где каждый элемент списка это ссылка на соответствующий документ в дереве документов MODX.
Замена DropMenu на Wayfinder¶
В некоторых старых шаблонах может использоваться устаревший сниппет DropMenu вместо WayFinder. Сниппет DropMenu не входит в MODX 0.9.5 и выше. Такие шаблоны часто легко обновить для Wayfinder, заменив вызов DropMenu следующим образом:
Пример вызова DropMenu в файле шаблона:
[[DropMenu?startDoc=`0`&levelLimit=`1` ]]
Можно заменить на
[[Wayfinder? &startId=`0`&level=`1`]]
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