DLBuildMenu: параметры и шаблоны

DLBuildMenu: параметры и шаблоны

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

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

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 родителя, либо список ID родителей через запятую.

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

Примечание: Обратите внимание, что в DLBuildMenu значение &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

Примечание: этот CSS-класс и  этот параметр существуют в дополнение к уже имеющимся в ДокЛистере классам 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

Основной шаблон-обертка (для уровня глубины 1).

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

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

&TplSubOwner

Шаблон-обертка для вложенных уровней (для субменю).

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

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

&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 соответственно для последнего, первого, текущего, четного и нечетного пункта. Кроме того, добавляет класс из параметра &activeClass для текущего элемента и его родительских элементов всех уровней.

Примечание: классы lastfirstcurrent, even, odd и active могут быть переопределены в параметрах &lastClass, &currentClass, &firstClass, &evenClass, &oddClass и &activeClass.

[+url+]

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

[+e.title+]

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

[+id+]

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

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

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

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

Шпаргалка по приоритетам шаблонов

Система шаблонов DLBuildMenu действительно очень гибкая, но к ней нужно привыкнуть. Для упрощения задачи ниже привожу cheatsheet (шпаргалку) по приоритетам шаблонов.

В левой колонке перечислены типы элементов меню, а справа от каждого элемента идут применяемые для него шаблоны в порядке убывания приоритета.

Тип элемента менюВысший приоритетПриоритет 1Приоритет 2Приоритет 3Приоритет 4Приоритет 5
Обёртка для всего меню (уровень 1) &TplOwner1 &TplMainOwner дефолтное значение &TplMainOwner
Обёртка для суб-меню (уровень N равен 2 и более) &TplOwnerN &TplSubOwner дефолтное значение &TplSubOwner
Не текущий пункт меню с дочерними (любой уровень N) &TplDepthN &TplOneItem дефолтное значение &TplOneItem
Не текущий пункт меню без дочерних (любой уровень N) &TplNoChildrenDepthN &noChildrenRowTPL &TplDepthN &TplOneItem дефолтное значение &TplOneItem
Текущий пункт меню с дочерними (любой уровень N) &TplCurrentN &TplCurrent &TplDepthN &TplOneItem дефолтное значение &TplOneItem
Текущий пункт меню без дочерних (любой уровень N) &TplCurrentNoChildrenN &TplNoChildrenDepthN &noChildrenRowTPL &TplDepthN &TplOneItem дефолтное значение &TplOneItem

Свои вопросы и предложения оставляйте в комментариях к статье, я постараюсь ответить на все комменты.


Понравился материал? Поделись с друзьями!