Download the PHP package konekt/menu without Composer

Laravel Menu

This is a rework of Lavary Menu

A quick and easy way to create menus in Laravel v5.4 - v10

Laravel Compatibility

PHP Compatibility

Documentation

• Installation
• Getting Started
• Sub-items
• Referring to Items
  • Get All Items
  • Get Sub-items of the Item
  • Magic Where Methods
• Referring to Menu Objects
• HTML Attributes
• Manipulating Links
  • Link's Href Property
• Active Item
  • URL Wildcards
  • Check for Active Children
• Inserting a Separator
• Append and Prepend
• Meta Data
• Manipulating The Items
• Sorting the Items
• Rendering
  • Built-in Renderers
    • Render As UL
    • Render As OL
    • Render As Div
  • Custom Renderers
• Authorization
• Configuration

Installation

Getting Started

You can define the menus in a service provider's boot method, so any request hits your application, the menu objects will be available.

Create A Menu

You can reference it later as Menu::get('sidebar').

Access Menu In Views

If you want the make the menu object available across all application views pass the 'share' option for create():

In a blade view:

Adding Items

The addItem() method receives 3 parameters:

• the name of the item
• the title of the item
• and options

options can be a simple string representing a URL or an associative array of options and HTML attributes which is described below.

Removing Items

Render The Menu

This component provides 3 rendering methods out of the box, ul, ol and div. You can read about the details here.

You can also access the menu object via the Menu facade:

This will render your menu like this:

Sub-items

Items can have sub-items too:

You can also chain the item definitions and go as deep as you wish:

It is possible to add sub items directly using parent attribute:

Referring to Items

You can access defined items throughout your code using the methods described below.

Get Item By Name

You can also store the item variable for further reference:

Get All Items

Menus have an items property that is a collection of menu Item objects.

ItemCollection is a slightly extended Laravel Collection.

Get Sub-Items of the Item

Get the item using the methods described above then call children() on it.

To get children of About item:

children() also returns an ItemCollection.

To check if an item has any children or not, you can use hasChildren()

Magic Where Methods

You can also search the items collection by magic where methods. These methods are consisted of a where concatenated with a property (object property or even meta data)

For example to get items with a specific meta data:

This method returns an ItemCollection.

Referring to Menu Instances

You might encounter situations when you need to refer to menu instances out of the builder context.

To get a specific menu by name:

Or to get all menus instances:

It returns a Laravel Collection

HTML Attributes

Since all menu items would be rendered as HTML entities like list items or divs, you can define as many HTML attributes as you need for each item:

If you render it with the ul renderer, the result will be something like this:

It is also possible to set or get HTML attributes after the item has been defined using attr() method.

• If you call attr() with one argument, it will return the attribute value for you.
• If you call it with two arguments, It will consider the first and second parameters as a key/value pair and sets the attribute.
• You can also pass an associative array of attributes if you need to add a group of HTML attributes in one step
• Lastly if you call it without any arguments it will return all the attributes as an array.

You can use attr on an ItemCollection, if you need to target a group of items:

Manipulating Links

All the HTML attributes will go to the wrapping tags(li, div, etc); You might encounter situations when you need to add some HTML attributes to <a> tags as well.

Each Item instance has an attribute which stores an instance of Link object. This object is provided for you to manipulate <a> tags.

Just like each item, Link also has an attr() method which functions exactly like item's:

Link's Href Property

If you don't want to use the routing feature or you don't want the builder to prefix your URL with anything (your host address for example), you can explicitly set your link's href property:

Active Item

You can mark an item as activated using activate() on that item:

You can also add class active to the anchor element instead of the wrapping element (div or li):

The Menu component automatically activates the corresponding item based on the current URI the time you register the item.

You can disable auto activation or choose the element to be activated (item or the link):

URL Wildcards

Konekt Menu component makes you able to define a pattern for a certain item, if the automatic activation can't help:

So articles, articles/random-news-title will both activate the Articles item.

Check for Active Children

You can check if a menu item has an active sub item by calling:

You can get the active item(s) from an item colletion by applying the actives() filter on them:

Append and Prepend

You can append or prepend HTML or plain-text to each item's title after it is defined:

The above code will result:

You can call prepend and append on item collections as well so that it'll affect all the items.

Meta Data

You might encounter situations when you need to attach some meta data to each item; This data can be anything from item placement order to permissions required for accessing the item; You can do this by using data() method.

data() method works exactly like attr() method:

If you call data() with one argument, it will return the data value for you. If you call it with two arguments, It will consider the first and second parameters as a key/value pair and sets the data. You can also pass an associative array of data if you need to add a group of key/value pairs in one step; Lastly if you call it without any arguments it will return all data as an array.

You can also access a data as if it's a property:

Meta data don't do anything to the item and won't be rendered in HTML either. It is the developer who would decide what to do with them.

You can use data on a collection, if you need to target a group of items:

Manipulating The Items

Menu items collection can be filtered, sorted, etc by any of Illuminate Collection methods

Rendering

Built-in Renderers

Several rendering formats are available out of the box:

1. ul
2. ol
3. div

Render As UL

In blade template:

Result:

Render As OL

Template:

Result:

Render As Div

In Blade:

Result:

Custom Renderers

Rendering was designed to be extensible from ground up.

It is possible to define separate renderers for menus and for items.

Custom Renderer Example (Bulma)

See Bulma Menu Component for reference on CSS.

Create A Menu Renderer Class:

Register the renderer:

Create the menu:

Render in blade template:

Result:

Authorization

Items can be authorized for users in two simple ways:

1. Checking Via Actions

Based on Laravel's built-in authorization, you can pass action names (strings) that will be tested against the current user with the can() method:

2. Checking Via Callbacks

You can also pass callbacks to authorize menu items for users:

The callback will receive the user as the first parameter.

You can add multiple allowIf and/or allowIfUserCan conditions to an item. The item will be allowed if ALL the conditions will be met.

Checking Authorization

By default, items without any allow* condition are allowed.

To check if an item is allowed:

To get the list of allowed children:

Configuration

You can adjust the behavior of the menu builder by passing settings when creating a menu:

• auto_activate Automatically activates menu items based on the current URI (true by default)
• activate_parents Activates the parents of an active item (true by default)
• active_class CSS class name for active items ("active" by default)
• cascade_data If you need descendants of an item to inherit meta data from their parents, make sure this option is enabled (true by default)
• active_element Which HTML element to be set active 'link' (<a>) or 'item' (<li>, <div>, etc) (item by default)

Menu::create('menu', [
    'auto_activate'    => false,
    'activate_parents' => true,
    'active_class'     => 'active',
    'active_element'   => 'item',    // item|link
    'restful'          => true,
    'share'            => 'myMenu'   // Will be available as `$myMenu` in blade files
]);