README

MarkupMenu 是一个用于生成导航菜单标记的 ProcessWire 模块。当提供起始根页面以及（可选，但推荐）当前（活动）页面时，它会根据这些参数生成一个无序列表 <ul>，并用 <nav> 元素包装，形成一个导航菜单。

MarkupMenu 提供了许多可配置选项，包括用于各种菜单项的模板字符串（如上面提到的列表和 nav 元素），以及可供那些需要完全控制菜单布局方式的人钩接的方法。

使用方法

MarkupMenu 主要用于前端，但您当然也可以在模块中使用它。通常，您只需要 render() 方法，它只接受一个选项数组作为其唯一参数

echo $modules->get('MarkupMenu')->render([
    'root_page' => $pages->get(1),
    'current_page' => $page,
]);

注意：如果您省略了 root_page 选项，默认使用站点根页面 – 除非您已指定了 menu_items 选项，在这种情况下，根页面根本不需要。如果您省略了 current_page，菜单将会被渲染，但当前（活动）页面无法突出显示等。

或者，您可以使用 MarkupMenu 通过提供 menu_items 选项来渲染预定义的菜单项列表。此选项的值可以是 PageArray 或数组数组

echo $modules->get('MarkupMenu')->render([
    'current_page' => $page,
    'menu_items' => [
        [
            'title' => 'Home',
            'url' => '/',
            'id' => 1,
        ],
        [
            'title' => 'Search',
            'url' => '/search/',
            'id' => 26,
        ],
        [
            'title' => 'About',
            'url' => '/about/',
            'id' => 29,
        ],
    ],
]);

如果您提供了一个预定义的菜单项数组，您可以在数组中定义当前（活动）页面（默认情况下，通过在活动项的 'is_current' 属性中分配布尔值 true），但如果您像上面示例那样提供 'current_page' 和每个菜单项的 ID，MarkupMenu 可以自动确定活动页面和父页面。

选项

下面将列出所有可用的选项及其默认值。您可以通过传递给 render 方法的数组来覆盖这些默认值，或者您可以通过站点配置设置 $config->MarkupMenu 指定一个全局自定义选项数组。

$config->MarkupMenu = [

    // 'root_page' is the starting point for the menu. This is optional if you provide 'menu_items'
    // instead, but leaving *both* empty will make MarkupMenu::render() return an empty string.
    'root_page' => null,

    // 'menu_items' is an optional, prepopulated PageArray of first level menu items.
    'menu_items' => null,

    // 'current' page is the current or active menu page.
    'current_page' => null,

    // 'templates' define the template strings used for rendering individual parts of the menu:
    //
    // - the semantic <nav> element that acts as a wrapper for the menu ('nav'),
    // - the lists wrapping the menu items and the subtrees within it ('list'),
    // - the list items wrapping menu branches ('list_item'),
    // - the items (links) in the menu ('item')
    // - the active item ('item_current')
    //
    // special placeholder values supported by default and populated while rendering the menu:
    //
    // - {classes}: all default classes applied, including template class, current class, etc.
    // - {class}: the template class only, mostly useful for adding a prefix to other classes
    // - {item}: the item itself, i.e. a Page object and all its field values andproperties
    // - {level}: the level of current item, represented by an integer starting from 1
    //
    // As of MarkupMenu 0.11.0 you can alternatively provide a callable (or an anonymous function)
    // that returns the template string in question. This callback function receives the menu item
    // and the options array as its arguments.
    'templates' => [
        'nav' => '<nav class="{classes}">%s</nav>',
        'list' => '<ul class="{classes} {class}--level-{level}">%s</ul>',
        'list_item' => '<li class="{classes} {class}--level-{level}">%s</li>',
        'item' => '<a href="{item.url}" class="{classes} {class}--level-{level}">{item.title}</a>',
        'item_current' => '<span class="{classes} {class}--level-{level}">{item.title}</span>',
    ],

    // 'include' defines the pages included in the menu: you can provide 'selector' string to choose suitable pages,
    // and use a boolean toggle ('root_page') to choose whether the root page itself should be included in the menu.
    'include' => [
        'selector' => null,
        'root_page' => false,
    ],

    // 'exclude' rules are the opposite of the include rules, and allow you to define the pages not
    // included in the menu: pages matching a selector string, non-listable pages ('listable' value
    // of false means that non-listable pages are excluded), and pages that would exceed a maximum
    // level or depth ('level_greater_than').
    //
    // **NOTE**: exclude rules are applied *after* initial query, which makes them less performant
    // than include rules; in particular one should always prefer the selector in the include rules
    // over the one in the exclude rules.
    'exclude' => [
        'selector' => null,
        'listable' => false,
        'level_greater_than' => null,
    ],

    // 'collapsed', in the lack of a better name, defines whether your menu should only be rendered
    // up current (active) page, or first level if no current page was provided.
    'collapsed' => true,

    // 'flat_root' is only useful if you've chosen to include the root page in the menu: this puts
    // the root page at the same level as your other first level pages – typically you'd want this,
    // so that your home page shows up at the same level as the first level below it.
    'flat_root' => true,

    // 'placeholder_options' is an array of options that will be passed to wirePopulateStringTags()
    // function, used for tag replacements in templates defined via the 'templates' option.
    'placeholder_options' => [],

    // 'placeholders' can be used to provide additional custom values for string replacements used
    // within the template strings defined via the 'templates' option.
    'placeholders' => [],

    // 'classes' can be used to override default class names added to items when the {classes} tag
    // is used in template strings defined via the 'templates' option.
    'classes' => [
        // 'page_id' => '&--page-id-', // note: page_id is disabled by default!
        'nav' => 'menu',
        'list' => 'menu__list',
        'list_item' => 'menu__list-item',
        'item' => 'menu__item',
        'item_current' => 'menu__item',
        'current' => '&--current',
        'parent' => '&--parent',
        'has_children' => '&--has-children',
    ],

    // 'array_item_keys' are used to pull data from menu items when an array of menu items (arrays)
    // is provided via the 'menu_items' option.
    'array_item_keys' => [
        'id' => 'id',
        'is_current' => 'is_current',
        'is_parent' => 'is_parent',
        'children' => 'children',
    ],
];

要求

• ProcessWire >= 3.0.112
• PHP >= 7.1.0

如果您正在使用 ProcessWire 或 PHP 的早期版本，我强烈建议您检查 MarkupSimpleNavigation 模块：https://github.com/somatonic/MarkupSimpleNavigation.

安装

此模块可以像其他任何 ProcessWire 模块一样安装，通过将 MarkupMenu 目录下载或克隆到您的 /site/modules/ 目录中。或者，您也可以通过 Composer 安装模块。

composer require teppokoivula/markup-menu

许可证

本项目采用 Mozilla 公共许可证版本 2.0。