README

A KnpMenu seasoned plugin that assists with creating menus for your CakePHP applications.

Requirements

CakePHP 5.0+ (use the 4.x branch of this plugin if you need CakePHP 4 compatibility)
KnpMenu 3.3+

Installation

Use Composer to add the menu plugin to your project:
```
$ composer require icings/menu
```
Make sure that you are loading the plugin in your bootstrap, either run:
```
$ bin/cake plugin load Icings/Menu
```
or add the following call to your Application class' bootstrap() method in the src/Application.php file:
```
$this->addPlugin('Icings/Menu');
```
Load the helper in your AppView class' initialize() method, located in the src/View/AppView.php file:
```
$this->loadHelper('Icings/Menu.Menu');
```

Usage

Detailed usage documentation can be found in the docs folder. For those that are familiar with CakePHP and KnpMenu, here's two examples for a quick start.

Via the Menu helper

Build and render the menu via the helpers create() and render() methods:

$menu = $this->Menu->create('main');
$menu->addChild('Home', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'home']]);
$menu->addChild('About', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'about']]);

$menu->addChild('Services', ['uri' => '#']);
$menu['Services']->addChild('Research', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'research']]);
$menu['Services']->addChild('Security', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'security']]);

$menu->addChild('Contact', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'contact']]);

echo $this->Menu->render();

In the default setup, this would generate the following HTML:

<ul>
    <li>
        <a href="/pages/display/home">Home</a>
    </li>
    <li>
        <a href="/pages/display/about">About</a>
    </li>
    <li class="has-dropdown">
        <a href="#">Services</a>
        <ul class="dropdown">
            <li>
                <a href="/pages/display/research">Research</a>
            </li>
            <li>
                <a href="/pages/display/security">Security</a>
            </li>
        </ul>
    </li>
    <li>
        <a href="/pages/display/contact">Contact</a>
    </li>
</ul>

Using the library directly

Aside from using the menu helper and its various configuration possibilities, it's also possible to manually utilize the library provided by this plugin, optionally combining things with the KnpMenu library:

use Icings\Menu\Integration\PerItemVotersExtension;
use Icings\Menu\Integration\RoutingExtension;
use Icings\Menu\Integration\TemplaterExtension;
use Icings\Menu\Matcher\Matcher;
use Icings\Menu\Matcher\Voter\UrlVoter;
use Icings\Menu\MenuFactory;
use Icings\Menu\Renderer\StringTemplateRenderer;

$factory = new MenuFactory();
$factory->addExtension(new RoutingExtension());
$factory->addExtension(new PerItemVotersExtension());
$factory->addExtension(new TemplaterExtension());

$menu = $factory->createItem('main');
$menu->addChild('Home', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'home']]);
$menu->addChild('About', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'about']]);
$menu->addChild('Services', ['uri' => '#']);
$menu['Services']->addChild('Research', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'research']]);
$menu['Services']->addChild('Security', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'security']]);
$menu->addChild('Contact', ['uri' => ['controller' => 'Pages', 'action' => 'display', 'contact']]);

$matcher = new Matcher();
$matcher->addVoter(new UrlVoter($this->request));

$renderer = new StringTemplateRenderer($matcher);
echo $renderer->render($menu);

Issues

Please use the issue tracker to report problems.

icings / menu

Maintainers

Details