thepsion5/menuizer

A package for conveniently creating and rendering menu templates

dev-master 2014-05-20 16:22 UTC

Requires

• php: >=5.3.0

Requires (Dev)

• phpunit/phpunit: 4.0.*
• satooshi/php-coveralls: dev-master

MIT

• Sean Mumford

• menu
• laravel
• menus

README

• Installation
• Getting Started
• Basic Usage
• Available Menu Rules
• Rule Shortcuts
• Advanced Usage
• Todo

Installation

Add thepsion5/menuizer as a requirement to your composer.json:

{
    "require": {
        "thepsion5/menuizer" : "dev-master"
    }
}

Then run composer update or composer install

##Getting Started

###Vanilla PHP Menuizer provides a convenient factory method to create a new instance of the service

$menuizer = Thepsion5\Menuizer\MenuizerService::create();

###Laravel First, add Menuizer's service provider to the array of providers in app/config/app.php:

    'providers' => array(

    // ...

    'Thepsion5\Menuizer\Support\Laravel\MenuizerServiceProvider',

    );

Next, add the Menuizer facade to the array of aliases in the same file:

    'aliases' => array(

        // ...

        'Menuizer' => 'Thepsion5\Menuizer\Support\Laravel\Facade'
    );

You may now access any of the Menuizer service's functions via the facade:

Menuizer::render('foo');

Basic Usage

###Creating Menus Menu attributes and behavior is defined using arrays of strings with a simple, easy-to-read syntax:

$menuizer->define('primary', array(
    'url:/|label:Home',
    'url:/news|label:News|attributes:class=highlight,id=news',
    'url:/about|label:About Us',
    'url:/staff|label:Our Team',
    'url:/projects|label:Major Projects'
));

The define() function accepts a menu name as the first argument and an array of attributes as the second argument.

To render the defined menu, use the render() method:

<ul class="navbar navbar-nav">
    <?= $menuizer->render('primary'); ?>
</ul>

By default, this will generate the following html:

<ul class="nav navbar-nav">
    <li><a href="/" >Home</a></li>
    <li><a href="/news" class="highlight" id="news">News</a></li>
    <li><a href="/about" >About Us</a></li>
    <li><a href="/staff" >Our Team</a></li>
    <li><a href="/projects" >Major Projects</a></li>
</ul>

You can also define and render a menu with a single function call if desired:

<ul class="navbar navbar-nav"> <?= $menuizer->render('primary', array(
    'url:/|label:Home',
    'url:/news|label:News|attributes:class=highlight,id=news',
    'url:/about|label:About Us',
    'url:/staff|label:Our Team',
    'url:/projects|label:Major Projects'
)); ?>
</ul>

##Available Menu Rules

###Url Generates a url - this rule or one of it's equivalent shortcuts is required for a menu item to be considered valid

###Route Uses a Route Provider to generate a URL

###Label Used to specify the text to display for the menu item

###Attributes Defines any attributes other than the href on the anchor tag

##Rule Shortcuts

In addition to the basic syntax, there are also several shortcuts that allow you to define rules more concisely

• Any rule that starts with #, /, or ? will be interpreted as a URL rule
• The class and id will be converted to the equivalent attributes rule
• Any other rule will be interpreted as a route (if a route provider is available)

##Advanced Usage

###Named Route Providers Some frameworks provide for named routing functionality, where a particular url pattern is given an alias to a name to make the organization of routes easier. Menuizer can provides a means of integrating this functionality into its url generation.

When using this package with Laravel, this functionality is provided automatically. You can also enable this functionality by creating your own implementation of RouteProviderInterface.php.

You may then pass an instance of your implementation into the MenuizerService::create() function:

    $menuizer = Thepsion5\Menuizer\MenuizerService::create(new FooRouteProvider);

##Creating Menus and Menu Item Objects You may bypass the Menuizer service class entirely to create menu instances using traditional OOP syntax:

use Thepsion5\Menuizer\Menu;
use Thepsion5\Menuizer\MenuItem;

$items = array(
    new MenuItem('/', 'Home', array('class' => 'nav', 'id' => 'home')),
    new MenuItem('/about', 'About Us', array('class' => 'nav')),
    new MenuItem('contact', 'Contact Us', array('class' => 'nav'))
);
$menu = new Menu('foo', $items);

You can also save menu instances created outside the service class via the getRepository() method:

$menuizer->getRepository()->save($menu);

Todo

• Implement a better default configuration system instead of using class variables
• More features
• More documentation