README

MenuBuilder 助手

为 CakePHP 提供的动态菜单构建助手

背景

这是一个具有许多自定义选项的菜单构建助手。请查看使用部分。

现在它支持使用 ACL 菜单组件构建的菜单，由 Mark Story 提供

特性

基于当前用户类型/组/权限/级别生成菜单（可用于与 Auth, Authsome 等组件一起使用）
提供各种有用的 CSS 类
支持多级菜单
支持 ACL 菜单组件，由 Mark Story 提供
CakePHP 单元测试 (~~100% 代码覆盖率~~)

要求

CakePHP 2.x
PHP 5.3

安装

[使用 Composer]

将插件添加到项目的 composer.json 文件中 - 略如以下内容

  {
    "require": {
      "torifat/cake-menu_builder": "2.0.3"
    }
  }

由于此插件在其自己的 composer.json 中设置了类型 cakephp-plugin，Composer 会将其安装到您的 /Plugins 目录中，而不是通常的 vendors 文件中。建议您将 /Plugins/MenuBuilder 添加到 .gitignore 文件中。（为什么？查看此处。）

[手动]

下载此内容：http://github.com/torifat/cake-menu_builder/zipball/master
解压下载的内容。
将生成的文件夹复制到 app/Plugin
将您刚刚复制的文件夹重命名为 MenuBuilder

[GIT 子模块]

在您的应用目录中输入

  git submodule add -b master git://github.com/torifat/cake-menu_builder.git Plugin/MenuBuilder
  git submodule init
  git submodule update

[GIT Clone]

在您的 Plugin 目录中输入

git clone -b master git://github.com/torifat/cake-menu_builder.git MenuBuilder

启用插件

在 2.0 中，您需要在 app/Config/bootstrap.php 文件中启用插件

CakePlugin::load('MenuBuilder');

如果您已经使用了 CakePlugin::loadAll();，则此步骤不是必需的。

使用方法

最小配置

通过修改您的 app/Config/bootstrap.php 文件来加载插件

<?php
...
CakePlugin::load('MenuBuilder');
?>

或

<?php
...
CakePlugin::loadAll();
?>

要使用此助手，请将以下内容添加到您的 AppController 中

<?php
...
var $helpers = array(..., 'MenuBuilder.MenuBuilder');

function beforeFilter() {
    ...
    // Define your menu
    $menu = array(
        'main-menu' => array(
            array(
                'title' => 'Home',
                'url' => array('controller' => 'pages', 'action' => 'home'),
            ),
            array(
                'title' => 'About Us',
                'url' => '/pages/about-us',
            ),
        ),
        'left-menu' => array(
            array(
                'title' => 'Item 1',
                'url' => array('controller' => 'items', 'action' => 'view', 1),
                'children' => array(
                    array(
                        'title' => 'Item 3',
                        'url' => array('controller' => 'items', 'action' => 'view', 3),
                    ),
                    array(
                        'title' => 'Item 4',
                        'url' => array('controller' => 'items', 'action' => 'view', 4),
                    ),
                )
            ),
            array(
                'title' => 'Item 2',
                'url' => array('controller' => 'items', 'action' => 'view', 2),
            ),
        ),
    );

    // For default settings name must be menu
    $this->set(compact('menu'));
    ...
}
?>

现在，要在视图中构建 main-menu，请使用以下代码

<?php
    echo $this->MenuBuilder->build('main-menu');
?>

您将在主页 (/pages/home) 页面获得以下输出

<ul id="main-menu">
    <li class="first-item active"><a title="Home" href="/pages/home">Home</a></li>
    <li><a title="About Us" href="/pages/about-us">About Us</a></li>
</ul>

要构建您的 left-menu，请将以下代码添加到视图中

<?php
    echo $this->MenuBuilder->build('left-menu');
?>

您将在 'Item 4' (/items/view/4) 页面获得以下输出

<ul id="left-menu">
    <li class="first-item active has-children">
        <a title="Item 1" href="/items/view/1">Item 1</a>
        <ul>
            <li class="first-item">
                <a title="Item 3" href="/items/view/3">Item 3</a>
            </li>
            <li class="active">
                <a title="Item 4" href="/items/view/4">Item 4</a>
            </li>
        </ul>
    </li>
    <li>
        <a title="Item 2" href="/items/view/2">Item 2</a>
    </li>
</ul>

您可以在 build 函数中传递可选参数，例如 -

<?php
    echo $this->MenuBuilder->build('main-menu', array('class' => array('fun', 'red'));
    // OR
    echo $this->MenuBuilder->build('main-menu', array('class' => 'fun green');
?>

高级配置

您可以在数组中提供以下高级选项

<?php
...
var $helpers = array(
    ...
    'MenuBuilder.MenuBuilder' => array(/* array of settings */)
);
?>

默认设置

如果您不提供任何设置，则以下设置将生效。

$settings = array(
    'activeClass' => 'active',
    'firstClass' => 'first-item',
    'childrenClass' => 'has-children',
    'evenOdd' => false,
    'itemFormat' => '<li%s>%s%s</li>',
    'wrapperFormat' => '<ul%s>%s</ul>',
    'noLinkFormat' => '<a href="#">%s</a>',
    'menuVar' => 'menu',
    'authVar' => 'user',
    'authModel' => 'User',
    'authField' => 'group',
);

设置详情

activeClass 选中/当前项及其后继项的 CSS 类名。 (默认 - 'active')

firstClass 每级第一个项的 CSS 类名。 (默认 - 'first-item')

childrenClass 包含子菜单的项的 CSS 类名。 (默认 - 'has-children')

evenOdd 如果设置为 true，则将为每个项提供偶数/奇数类名。 (默认 - false)

<ul id="main-menu">
    <li class="first-item odd">
        <a title="Home" href="/pages/home">Home</a>
    </li>
    <li class="even">
        <a title="About Us" href="/pages/about-us">About Us</a>
    </li>
</ul>

itemFormat 如果您想为菜单项使用除 li 之外的标签 (默认 - '<li%s>%s%s</li>')

wrapperFormat 如果您想为菜单项容器使用除 ul 之外的标签 (默认 - '<ul%s>%s</ul>')

noLinkFormat 空链接项的格式 (默认 - '<a href="#">%s</a>')

示例设置

'MenuBuilder.MenuBuilder' => array(
    'itemFormat' => '<div%s>%s%s</div>',
    'wrapperFormat' => '<div%s>%s</div>',
    'noLinkFormat' => '<div>%s</div>',
),

示例输出（添加一个额外项来解释 noLinkFormat）

<div id="main-menu">
    <div class="first-item">
        <a title="Home" href="/pages/home">Home</a>
    </div>
    <div>
        <a title="About Us" href="/pages/about-us">About Us</a>
    </div>
    <div>
        Empty
    </div>
</div>

menuVar 包含所有菜单的变量的名称 (默认 - 'menu')

以下设置将用于基于权限的菜单（见下文）

authVar 包含用户数据的变量的名称 (默认 - 'user')

authModel 身份验证模型的名称 (默认 - 'User')

authField 包含用户的类型/组/权限/级别的字段的名称 (默认 - 'group')

基于权限的菜单

假设您有一个如下所示的 users 表

CREATE TABLE `users` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `email` varchar(255) NOT NULL,
    `password` char(40) NOT NULL,
    `group` enum('user','manager','admin') NOT NULL DEFAULT 'user',
    `name` varchar(255) NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY (`email`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

现在假设您正在使用 CakePHP 身份验证组件进行身份验证，因此请将以下内容添加到您的 AppController 中

<?php
...
function beforeFilter() {
    ...
    $user = $this->Auth->user();
    $this->set(compact('user'));
}
?>

但是，如果您正在使用 Authsome 组件进行身份验证，那么请将以下内容添加到您的 AppController 中

<?php
...
function beforeFilter() {
    ...
    $user = Authsome::get();
    $this->set(compact('user'));
}
?>

现在我们必须在我们的菜单中定义权限，如下所示

<?php
...
function beforeFilter() {
    ...
    // Define your menu
    $menu = array(
        'main-menu' => array(
            // Anybody can see this
            array(
                'title' => 'Home',
                'url' => array('controller' => 'pages', 'action' => 'home'),
            ),
            // Users and Admins can see this, Guests and Managers can't
            array(
                'title' => 'About Us',
                'url' => array('controller' => 'pages', 'action' => 'about-us'),
                'permissions' => array('user','admin'),
            ),
            // Only Guests can see this
            array(
                'title' => 'Login',
                'url' => array('controller' => 'users', 'action' => 'login'),
                'permissions' => array(''),
            ),
        ),
        ...
    );
    // For default settings name must be menu
    $this->set(compact('menu'));
    ...
}
?>

完成！

其他菜单选项

permissions 可以查看该项目的类型/组/权限/级别的数组 (默认 - array())

partialMatch 通常 url 匹配是严格的。假设您位于 /items/details，并且您的菜单包含一个针对 /items 的条目，则默认情况下它不会设置为活动状态。但是，如果您将 partialMatch 设置为 true，则它将设置为活动状态。 (默认 - false)

id 为项目提供 CSS id (默认 - null)

class 为项目提供 CSS 类 (默认 - null)

separator 如果您想在菜单中定义一些分隔符，下面是一个很好的示例，说明您可以做什么。 (默认 - false)

示例设置

'MenuBuilder.MenuBuilder' => array(
    'itemFormat' => '<dd%s>%s%s</dd>',
    'wrapperFormat' => '<dl%s>%s</dl>',
    'noLinkFormat' => '<dd>%s</dd>',
),

示例菜单

<?php
...
var $helpers = array(..., 'MenuBuilder.MenuBuilder');

function beforeFilter() {
    ...
    // Define your menu
    $menu = array(
        'main-menu' => array(
            array(
                'separator' => '<dt>Main Menu</dt>',
            ),
            array(
                'title' => 'Home',
                'url' => array('controller' => 'pages', 'action' => 'home'),
            ),
            array(
                'title' => 'About Us',
                'url' => '/pages/about-us',
            ),
        )
    );

    // For default settings name must be menu
    $this->set(compact('menu'));
    ...
}
?>

示例输出

<dl id="main-menu">
    <dt>Main Menu</dt>
    <dd class="first-item">
        <a title="Home" href="/pages/home">Home</a>
    </dd>
    <dd>
        <a title="About Us" href="/pages/about-us">About Us</a>
    </dd>
</dl>

更多即将到来 :)

待办事项

添加更多测试用例

许可证

MIT 许可证 (MIT)

特此免费许可，任何获得本软件及其相关文档副本（“软件”）的人，均可不受限制地使用软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本，并允许向软件提供者提供软件的人这样做，前提是遵守以下条件

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、适用于特定目的和侵权不保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任承担责任，无论是基于合同、侵权或其他原因， arising from, out of or in connection with the software or the use or other dealing with the software。

torifat / cake-menu_builder

维护者

详细信息