Сниппет вывода меню DLBuildMenu, основанный на DocLister, предоставляет мощные инструменты создания меню сайта на MODx Evo. Но многие, даже опытные, MODx-юзеры его не применяют из-за отсутствия документации. Восполняю этот пробел.

Уровень статьи: для начинающих


Краткое описание

DLBuildMenu — сниппет для вывода меню сайта на MODx Evolution. Построен на основе ДокЛистера, по сути это сниппет-обертка с вызовом DocLister внутри — поэтому в нём можно использовать практически все параметры и фишки самого DocLister.

Применяя prepare, мы получаем неограниченные возможности подготовки данных. А развитая система шаблонизации ДокЛистер, дополненная в DLBuildMenu новыми параметрами, даёт в руки, на мой взгляд, даже чрезмерно богатый инструментарий.

Разработчик: Agel_Nash

Зависимости и требования

  • Для работы DLBuildMenu у вас должен быть установлен DocLister (есть в последних релизах MODx Evo по умолчанию).
  • Требуется PHP не ниже версии 5.3

Установка

  • DLBuildMenu входит по умолчанию в новую кастомную сборку MODx Evo 1.2.1-d9.1.2 от 21.03.2017.
  • На более старых кастомных сборках и на официальной сборке для его установки нужно установить или переустановить ДокЛистер из Extras, при этом нужно, чтобы DLBuildMenu был отмечен галочкой в списке при установке.

Файлы

  • assets/snippets/DocLister/snippet.DLBuildMenu.php
  • assets/snippets/DocLister/lib/DLFixedPrepare.class.php (метод buildMenu)

Преимущества DLBuildMenu

  • есть возможность применения prepare для обработки данных перед выводом.
  • богатый выбор способов задания шаблонов, в том числе инлайн-шаблоны.
  • сортировка по TV-параметрам с приведением к нужному типу.
  • может делать фильтрацию по TV-параметрам.
  • можно придумывать и задавать собственные параметры и обрабатывать их в prepare.
Кроме того, в DLBuildMenu работают и другие фишки из арсенала ДокЛистер, описывать которые здесь не стану, для этого нужно изучать сам DL.

Параметры

Базовые параметры

&idType (hardcoded)
Тип выборки аналогично DocLister.

Возможные значения: parents
Примечание: значение параметра &idType жестко записано в коде как parents.

&parents
Родительская (начальная) папка.

Возможные значения: список ID родителей через запятую.
Значение по умолчанию: 0
Примечание: Обратите внимание, что значение &parents по умолчанию равно 0, что означает «выводить начиная с корня сайта». Это отличается от дефолтного значения &parents параметра в ДокЛистере.

& currentDepth
Исходный уровень вложенности (глубина).

Возможные значения: целое число от 1 и больше.
Значение по умолчанию: 1
!!!В название параметра пришлось вставить пробел после "&" — иначе здешний парсер вырезает.

&maxDepth
Макс. глубина

Возможные значения: целое число от 1 и больше.
Значение по умолчанию: 5

&BeforePrepare и &AfterPrepare
Обработка данных через prepare аналогично DocLister.

Возможные значения: задаются по правилам ДокЛистера. Могут быть списком имен сниппетов и вызовов методов ранее загруженных классов, либо анонимной функцией.
Примечание: для prepare в DLBuildMenu уже имеется встроенный обязательный вызов DLFixedPrepare::buildMenu. Обработчики из &BeforePrepare вызываются перед встроенным, из &AfterPrepare — после встроенного вызова.

&activeClass
CSS-класс активного (текущего) пункта меню и его родительских элементов всех уровней.

Возможные значиения: Имя CSS-класса, или несколько имён CSS-классов, заданные как в HTML-теге (через пробел).
Значение по умолчанию: active
Примечание: этот класс и этот параметр существуют в дополнение к уже имеющимся в ДокЛистере классам first, last, odd, even и current (см. документацию по DocLIster).

Параметры условий выборки

&addWhereList
Условия выборки документов для всех уровней.

Возможные значения: задаются как в DocLister (по правилам MySQL для условия WHERE).
Значение по умолчанию: c.hidemenu = 0

&addWhereListN
Условия выборки документов N-го уровня, для соответствующих уровней &addWhereListN имеет приоритет над &addWhereList.

Возможные значения: задаются по правилам MySQL для условия WHERE.
Значение по умолчанию: нет
Примечание: Если &addWhereListN не задан, для всех уровней используется &addWhereList.

Параметры сортировки

&orderBy
Условия сортировки документов всех уровней.

Возможные значения: задаются как в DocLister (по правилам MySQL для ORDER BY).
Значение по умолчанию: menuindex ASC, id ASC

&orderByN
Условия сортировки документов N-го уровня вложенности, для соответствующих уровней &orderBy имеет приоритет над &orderBy.

Возможные значения: задаются по правилам MySQL для ORDER BY.
Значение по умолчанию: нет
Примечание: Если &orderByN не задан, для всех уровней используется &orderBy.

Параметры «Список TV»

&tvList
Список TV-параметров, которые участвуют в выборке (как в DocLister).

Возможные значения: список имён TV-параметров через запятую.
Значение по умолчанию: нет

&tvListN
Список TV-параметров в выборке для N-го уровня вложенности, для соответствующих уровней &tvListN имеет приоритет над &tvList.

Возможные значения: список имён TV-параметров через запятую.
По умолчанию: пусто.
Примечание: Если &tvListN не задан, для всех уровней используется &tvList.

Шаблоны

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

Шаблоны-обёртки

&TplMainOwner
Основной шаблон-обертка.

Значение по умолчанию:
@CODE:<ul id="nav" class="menu level-1">[+dl.wrap+]</ul>

Примечание: у вас должен быть задан шаблон &TplMainOwner или &TplOwner1, иначе будет использовано дефолтное значение шаблона &TplMainOwner.

&TplSubOwner
Шаблон-обертка для вложенных уровней (для субменю).
Примечание: для вывода N-уровневого меню у вас в дополнение к основной обёртке должен быть задан по крайней мере &TplSubOwner и/или шаблоны &TplOwnerN. Иначе будет использовано дефолтное значение &TplSubOwner.

Значение по умолчанию:
@CODE:<ul class="sub-menu level-[+dl.currentDepth+]">[+dl.wrap+]</ul>


&TplOwnerN
Шаблон-обертка для субменю N-го уровня вложенности, для соответствующих уровней &TplOwnerN имеет приоритет над &TplMainOwner и &TplSubOwner (см. Примечание).

Значение по умолчанию: нет
Примечание: Если заданы и &TplOwner1, и &TplMainOwner, то будет использован &TplOwner1. Если заданы и &TplOwner2 и &TplSubOwner, то для уровня 2 будет использован &TplOwner2, а для уровней начиная с 3-го — &TplSubOwner.

Шаблоны пункта меню

&TplOneItem
Основной шаблон для каждого пункта меню всех уровней.

Значение по умолчанию:
@CODE:<li id="menu-item-[+id+]" class="menu-item [+dl.class+]">
   <a href="[+url+]" title="[+e.title+]">[+title+]</a>
   [+dl.submenu+]
</li>

Примечание: у вас должны быть заданы все нужные вам шаблоны пунктов меню, по крайней мере &TplOneItem. Иначе для пунктов, у которых шаблон не определен вами, будет использовано дефолтное значение &TplOneItem.

&TplDepthN
Шаблон пункта меню вложенности N, для соответствующих уровней &TplDepthN имеет приоритет над &TplOneItem.

Значение по умолчанию: нет
Примечание: Например, если задан &TplDepth3, он заменит собой шаблон &TplOneItem на 3-м уровне вложенности.

Шаблоны пункта без дочерних элементов

&noChildrenRowTPL
Основной шаблон пункта меню без дочерних элементов для всех уровней.

Значение по умолчанию: нет

&TplNoChildrenDepthN
Шаблон пункта меню без дочерних элементов вложенности N. Для соответствующих уровней &TplNoChildrenDepthN имеет приоритет над &noChildrenRowTpl.

Значение по умолчанию: нет
Примечание: если для пункта меню не задан ни &noChildrenRowTPL, ни &TplNoChildrenDepthN, то в качестве шаблона для «бездетных» пунктов будет использован шаблон, заданный вами в других параметрах (&TplOneItem или &TplDepthN).

Шаблоны текущего пункта

&TplCurrent
Шаблон текущего пункта меню с дочерними, имеет приоритет перед всеми шаблонами пунктов меню, кроме &TplCurrentN.

Значение по умолчанию: нет

&TplCurrentN
Шаблон текущего пункта меню вложенности N с дочерними, для N-го уровня шаблон &TplCurrentN имеет приоритет перед всеми шаблонами пунктов меню с дочерними, включая &TplCurrent.

Значение по умолчанию: нет.

&TplCurrentNoChildrenN
Шаблон текущего пункта меню без дочерних элементов, где N — номер уровня вложенности. Для уровня N имеет приоритет перед любыми другими шаблонами «бездетных» пунктов меню.

Значение по умолчанию: нет.

Плейсхолдеры

Основные плейсхолдеры

[+dl.wrap+]
С его помощью в шаблон-обёртку подставляется сформированный HTML-код меню/субменю для вывода.

Примечание: используется только для шаблонов-обёрток &TplMainOwner, &TplSubOwner и &TplOwnerN.

[+dl.submenu+]
Сюда подставляется сформированный HTML-код субменю вместе с шаблоном-обёрткой.
Примечание: используется для шаблонов пункта меню, как не текущих, так и текущих.

[+dl.currentDepth+]
Текущий уровень вложенности (текущая глубина).

Примечание: обратите внимание, что отсчёт текущего уровня вложенности (текущей глубины) начинается с 1.

[+dl.class+]
Работает так же, как и в DocLister, автоматически добавляя классы last, first, current, even, odd соответственно для последнего, первого, текущего, четного и нечетного пункта. Кроме того, добавляет класс active для текущего элемента и родительских элементов всех уровней текущего элемента.

Примечание: классы last, first, current, even, odd и active могут быть переопределены в параметрах &lastClass, & currentClass, &firstClass, &evenClass, &oddClass и &activeClass.
!!! В название параметра & currentClass пришлось вставить пробел после "&" — иначе здешний парсер вырезает.

[+url+]
УРЛ ресурса аналогично ДокЛистеру.

[+e.title+]
Экранированное значение menutitle или pagetitle (если menutitle пуст) аналогично Доклистеру.

[+id+]
ID ресурса аналогично ДокЛистеру.

Другие плейсхолдеры из DocLister

Вы можете использовать и другие плейсхолдеры ДокЛистера, устанавливаемые контроллером site_content и различными экстендерами.

Например, плейсхолдеры вида [+tvPrefix.tvName+], плейсхолдеры экранированных значений вида [+e.fieldName+] (где fieldName — это имя поля таблицы site_content), [+date+] и другие (см. документацию к DocLister).



Больше информации о DLBuildMenu у меня на сайте, там в конце материала есть еще «Таблица приоритетов шаблонов».

Вопросы можете задавать и здесь и там.