MenuBuilder ドキュメント

カスタマイズのオプションが豊富な、CakePHP 2 用の動的なメニュー作成ヘルパーです。

Mark Story による ACL Menu Component で作ったメニューにも対応しています。

特徴
インストール
使い方
設定
権限に応じたメニュー
メニュー項目のオプション

特徴

現在のユーザーの種別・グループ・権限・レベルに応じてメニューを生成します (Auth コンポーネント、 Authsome などと一緒に使えます)
便利な CSS クラスをいろいろ付けます
多階層のメニューに対応しています
Mark Story による ACL Menu Component に対応しています

インストール

Composer でプラグインをインストールします。

bash

composer require pieceofcake2/menu_builder

このプラグインのタイプは cakephp-plugin なので、composer/installers によってプラグインディレクトリに (MenuBuilder として) インストールされます。正しい場所にインストールされるように、アプリケーションの composer.json で installer-paths を設定してください。

レイアウト	`installer-paths`
モダン (`config/`、`src/`、`templates/`、`plugins/`)	`"plugins/{$name}/": ["type:cakephp-plugin"]`
レガシー (`app/Config/`、`app/Plugin/`)	`"app/Plugin/{$name}/": ["type:cakephp-plugin"]`

インストールされたプラグインのディレクトリ (たとえば plugins/MenuBuilder) は、.gitignore ファイルに追加することをお勧めします。

プラグインの有効化

config/bootstrap.php (レガシーレイアウトでは app/Config/bootstrap.php) でプラグインを読み込みます。すでに CakePlugin::loadAll() を使っている場合は不要です。

php

CakePlugin::load('MenuBuilder');

使い方

このヘルパーを使うには、AppController に次のように追加します。

php

class AppController extends Controller
{
    public $helpers = ['MenuBuilder.MenuBuilder'];

    public function beforeFilter()
    {
        parent::beforeFilter();

        // Define your menu
        $menu = [
            'main-menu' => [
                [
                    'title' => 'Home',
                    'url' => ['controller' => 'pages', 'action' => 'home'],
                ],
                [
                    'title' => 'About Us',
                    'url' => '/pages/about-us',
                ],
            ],
            'left-menu' => [
                [
                    'title' => 'Item 1',
                    'url' => ['controller' => 'items', 'action' => 'view', 1],
                    'children' => [
                        [
                            'title' => 'Item 3',
                            'url' => ['controller' => 'items', 'action' => 'view', 3],
                        ],
                        [
                            'title' => 'Item 4',
                            'url' => ['controller' => 'items', 'action' => 'view', 4],
                        ],
                    ],
                ],
                [
                    'title' => 'Item 2',
                    'url' => ['controller' => 'items', 'action' => 'view', 2],
                ],
            ],
        ];

        // With the default settings, the variable must be named menu
        $this->set(compact('menu'));
    }
}

main-menu を作るには、ビューで次のコードを使います。

php

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

Home (/pages/home) ページでは、次のように出力されます。

html

<ul class="main-menu" 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) ページでは、次のように出力されます。

html

<ul class="left-menu" 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>

最上位のラッパーには、メニュー名が id と class として付きます。build() の class オプションで CSS クラスを追加できます。

php

// <ul class="main-menu fun green" id="main-menu">
echo $this->MenuBuilder->build('main-menu', ['class' => 'fun green']);

build() のそれ以外のオプションは設定と同じもので、指定するとそれ以降はヘルパーの設定を上書きします。

設定

ヘルパーに設定を渡せます。

php

public $helpers = [
    'MenuBuilder.MenuBuilder' => [/* array of settings */],
];

デフォルトの設定

設定を何も指定しない場合は、次のデフォルトが使われます。

php

public $helpers = [
    'MenuBuilder.MenuBuilder' => [
        'activeClass' => 'active',
        'firstClass' => 'first-item',
        'childrenClass' => 'has-children',
        'menuClass' => null,
        'evenOdd' => false,
        'itemFormat' => '<li%s>%s%s</li>',
        'wrapperFormat' => '<ul%s>%s</ul>',
        'wrapperClass' => null,
        'noLinkFormat' => '<a href="#">%s</a>',
        'menuVar' => 'menu',
        'authVar' => 'user',
        'authModel' => 'User',
        'authField' => 'group',
        'indentHtmlOutput' => true,
    ],
];

設定の詳細

activeClass 選択中・現在の項目とその祖先に付ける CSS クラス名です。(デフォルト 'active')

firstClass 各階層の最初の項目に付ける CSS クラス名です。(デフォルト 'first-item')

childrenClass サブメニューを含む項目に付ける CSS クラス名です。(デフォルト 'has-children')

menuClass 最上位のラッパー (ul) に付ける CSS クラス名です。(デフォルト null)

wrapperClass サブメニューのラッパーに付ける CSS クラス名です。(デフォルト null)

evenOddtrue にすると、各項目に偶数・奇数のクラス名が付きます。(デフォルト false)

html

<ul class="main-menu" 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 URL のない項目のフォーマットです。(デフォルト '<a href="#">%s</a>')

設定の例

php

'MenuBuilder.MenuBuilder' => [
    'itemFormat' => '<div%s>%s%s</div>',
    'wrapperFormat' => '<div%s>%s</div>',
    'noLinkFormat' => '<div>%s</div>',
],

出力の例 (noLinkFormat を説明するために URL のない項目を追加しています)

html

<div class="main-menu" 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')

indentHtmlOutput 生成する HTML をインデントします。(デフォルト true)

defaults 各項目のオプションのデフォルトで、すべての項目にマージされます。

次の設定は、権限に応じたメニュー (後述) に使われます。

authVar ユーザーのデータを含むビュー変数の名前です。(デフォルト 'user')

authModel 認証モデルの名前です。(デフォルト 'User')

authField ユーザーの種別・グループ・権限・レベルを含むフィールドの名前です。(デフォルト 'group')

権限に応じたメニュー

次のような users テーブルがあるとします。

sql

CREATE TABLE `users` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `email` varchar(255) NOT NULL,
    `password` varchar(255) 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=utf8mb4;

ヘルパーは、グループを $user['User']['group'] から読み取ります (authVar、authModel、 authField をご覧ください)。認証に Auth コンポーネントを使っている場合は、AppController に次のように追加します。

php

public function beforeFilter()
{
    parent::beforeFilter();

    $user = ['User' => $this->Auth->user()];
    $this->set(compact('user'));
}

認証に Authsome を使っている場合は、代わりに次のように追加します。

php

public function beforeFilter()
{
    parent::beforeFilter();

    $user = Authsome::get();
    $this->set(compact('user'));
}

次に、メニューで権限を定義します。

php

$menu = [
    'main-menu' => [
        // Anybody can see this
        [
            'title' => 'Home',
            'url' => ['controller' => 'pages', 'action' => 'home'],
        ],
        // Users and admins can see this, guests and managers can't
        [
            'title' => 'About Us',
            'url' => ['controller' => 'pages', 'action' => 'about-us'],
            'permissions' => ['user', 'admin'],
        ],
        // Only guests can see this
        [
            'title' => 'Login',
            'url' => ['controller' => 'users', 'action' => 'login'],
            'permissions' => [''],
        ],
    ],
];

// With the default settings, the variable must be named menu
$this->set(compact('menu'));

メニュー項目のオプション

title 項目のタイトルです。タイトルのない項目 (separator もないもの) は出力されません。

url 項目の URL で、文字列または URL 配列で指定します。URL のない項目には noLinkFormat が使われます。

children サブメニュー項目の配列です。

permissions 項目を表示できる種別・グループ・権限・レベルの配列です。(デフォルト []、全員)

partialMatch 通常、URL の照合は厳密です。/items/details にいて、メニューに /items の項目がある場合、デフォルトではその項目はアクティブになりません。partialMatch を true にすると、アクティブになります。 (デフォルト false)

id 項目の CSS の id です。(デフォルト null)

class 項目の CSS クラスで、文字列または配列で指定します。(デフォルト null)

linkClass リンクの CSS クラスです。(デフォルト null)

target リンクの target 属性です。(デフォルト null)

escape、escapeTitleHtmlHelper::link() に渡されます。

image リンクの中に表示する画像です。その後に、label クラスの span に入ったタイトルが続きます。 (デフォルト null)

separator 項目の代わりに、指定した HTML を出力します。以下は、これを使ってできることの例です。 (デフォルト false)

設定の例

php

'MenuBuilder.MenuBuilder' => [
    'itemFormat' => '<dd%s>%s%s</dd>',
    'wrapperFormat' => '<dl%s>%s</dl>',
    'noLinkFormat' => '<dd>%s</dd>',
],

メニューの例

php

$menu = [
    'main-menu' => [
        [
            'separator' => '<dt>Main Menu</dt>',
        ],
        [
            'title' => 'Home',
            'url' => ['controller' => 'pages', 'action' => 'home'],
        ],
        [
            'title' => 'About Us',
            'url' => '/pages/about-us',
        ],
    ],
];

// With the default settings, the variable must be named menu
$this->set(compact('menu'));

出力の例

html

<dl class="main-menu" 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>

由来

このパッケージは torifat/cake-menu_builder (Packagist では torifat/cake-menu_builder、アップストリームの最終バージョンは v2.0.3) のメンテナンスされたフォークで、元は Rifat Nabi によって作られました。 pieceofcake2 が、モダンな PHP 上の CakePHP 2 向けにメンテナンスしています。オリジナルからの変更点はフォーク以降のコミット履歴にあります。

MenuBuilder ドキュメント ​

特徴 ​

インストール ​

プラグインの有効化 ​

使い方 ​

設定 ​

デフォルトの設定 ​

設定の詳細 ​

権限に応じたメニュー ​

メニュー項目のオプション ​

由来 ​

MenuBuilder ドキュメント

特徴

インストール

プラグインの有効化

使い方

設定

デフォルトの設定

設定の詳細

権限に応じたメニュー

メニュー項目のオプション

由来