An attempt to take a bit of the stress and boilerplate out of building menus (or indeed any list, because that's basically what a menu is) Comes with support for Laravel 4 (other frameworks to follow)
Simply require the library like so:
composer require tlr/menu "2.*"
Make a new MenuItem
class for your menu:
$menu = new Tlr\Menu\MenuItem;
Add some menu items:
$home = $menu->item( 'home', 'Home', 'http://foo.com' );
$blog = $menu->item( 'blog', 'Blog', 'http://foo.com/blog' );
$about = $menu->item( 'about', 'About', 'http://foo.com/about-us' );
Why not add a sub-menu? The menu, and all of its items are all the same MenuItem
class, so creating submenus is the same as with top level menus:
$about->item( 'where-we-are', 'Where We Are', 'http://eric.com/where-are-we' );
$about->item( 'contact-us', 'Contact Us', 'http://eric.com/contact-us' );
Then in you view, you can iterate over the menu's items using the $menu->getItems()
method.
You can retreive an existing item by using its key:
$blog = $menu->item('blog');
The method signature is as follows:
$menu->item( $key[, $title = "", $options = array(), $attributes = array(), $index = $n + 100] )
$key
is a string key used to retrieve the item. It is also added, in slugified form, to the class attribute. It is the only required argument.$title
is the text to display in the list item$options
is an array of options for the item. If you pass a string to the third item, it will assume it is the link option, and will convert it toarray( 'link' => $string )
$attributes
is an array of attributes for the HTML element$index
is an optional index to insert a new menu item at. The indices, by default, default to increments of 100, starting at 100, so you can easily insert items in between them.
If you have, say, a header and a footer menu, you can use the MenuRepository class:
$repo = new MenuRepository;
$headerMenu = $repo->menu( 'header-nav' );
$footerMenu = $repo->menu( 'footer-nav' );
and you can retrieve the menu later in your code in the same way:
$headerMenu = $repo->menu( 'header-nav' ); // will use the existing menu instance cached with this key
$newMenu = $repo->menu( 'other-nav' ); // that key hasn't been used yet, so a new instance will be created and cached with that key
The menu can be filtered. Say you have a menu for usage in an admin area, or in a context with user auth levels or permissions. You have two options:
- You can pass a filter closure to the
getItems
method that fill be used to filter the menu items.
// This will filter the items based on user permissions
$menu->getItems(function($item) use ($user)
{
return $user->can( $item->option( 'permissions', array() ) );
});
- You can add multiple filters to a menu with the
addFilter($callable)
method. These filters will be applied when thegetItems
method is called.
// This will add a filter that only lets the given user see the menu items if they have the appropriate auth level
$menu->addFilter(function($item) use ($user)
{
return $item->option('auth') <= $user->authLevel;
});
$menu->getItems();
- You don't have to filter an entire menu - you can filter a submenu, too:
$about->addFilter(function()
{
return $item->isVisible();
});
- By default, any filters added with
addFilter
get applied to submenus. You can override this behaviour by passing false as the second argument:
$menu->addFilter(function($item) use ($user)
{
return $user->canSeePage( $item );
}, false);
- If you do not want to filter the items, you can call
$menu->getItems(false)
To mark menu items as active, you have a few options:
Say you have this 2 level menu:
$home = $menu->item( 'home', 'Home', 'http://foo.com' );
$blog = $menu->item( 'blog', 'Blog', 'http://foo.com/blog' );
$about = $menu->item( 'about', 'About', 'http://foo.com/about-us' );
$contact = $about->item( 'contact', 'Contact Us', 'http://foo.com/contact-us' );
$find = $about->item( 'find', 'Find Us', 'http://foo.com/find-us' );
You can manually activate any of those items with the setActive method:
$blog->setActive();
For a more automated approach, you can recursively mark one of those as activated based on the current URL. For example:
$menu->activate( $currentUrl );
This would match the given url against each of the menu's items, and mark them as active if the url matches. It also calls each item's children, and marks the parents as active if they have an active child item. ie. activeness bubbles up the chain.
So, if the current URL was http://foo.com/contact-us
, this would mark the about
menu item, and its child item, contact
as active.
If you want to match based on something different than URL, you can match against anything in a MenuItem
's options
array:
$home = $menu->item( 'home', 'Home', [ 'link' => 'http://foo.com', 'routename' => 'home' ] );
$blog = $menu->item( 'blog', 'Blog', [ 'link' => 'http://foo.com/blog', 'routename' => 'blog' ] );
$menu->activate( 'blog', 'routename' );
Add Tlr\Menu\Laravel\MenuServiceProvider
to the providers
array in Laravel's app/config/app.php
's, and add 'Menu' => 'Tlr\Menu\Laravel\MenuFacade'
to the aliases
array.
You can then use the Menu
facade as a shortcut for the MenuRepository
class, like so:
$menu = Menu::menu( 'nav' );
$menu->item('Home')
after which, you can access it again later with Menu::menu( 'nav' )
.
The Laravel version of the class can be echoed out (which will call the render()
method). This renders the menu using Laravel's blade templating system. You have two options for customising:
- You can override the Menu Builder views (run
php artisan view:publish tlr/view
, then edit those files). - You can pass a view to the parent menu like so. This view will have the
MenuItem
object available as the$menu
variable:
$menu->setView( 'my.menu.view' );