\Menu\View\HelperMenuHelper

Menu helper.

Renders nested database records into a well formated <ul> menus suitable for HTML pages.

Summary

Methods
Properties
Constants
__construct()
render()
formatter()
countItems()
resetTemplates()
trigger()
eventDispatcher()
triggered()
$helpers
No constants found
_prepareOptions()
_prepareItemAttrs()
_prepareItems()
_renderPart()
_render()
_count()
_clear()
$_defaultConfig
$_rendering
N/A
No private methods found
No private properties found
N/A

Properties

$helpers

$helpers : array

Other helpers used by this helper.

Type

array

$_defaultConfig

$_defaultConfig : array

Default configuration for this class.

  • formatter: Callable method used when formating each item. Function should expect two arguments: $item and $info respectively.
  • beautify: Set to true to "beautify" the resulting HTML, compacted HTMl will be returned if set to FALSE. You can set this option to a string compatible with htmLawed library. e.g: 2s0n. Defaults to FALSE (compact).
  • dropdown: Set to true to automatically apply a few CSS styles for creating a "Dropdown" menu. Defaults to FALSE. This option is useful when rendering Multi-level menus, such as site's "main menu", etc.
  • activeClass: CSS class to use when an item is active (its URL matches current URL).
  • firstItemClass: CSS class for the first item.
  • lastItemClass: CSS class for the last item.
  • hasChildrenClass: CSS class to use when an item has children.
  • split: Split menu into multiple root menus (multiple UL's). Must be an integer, or false for no split (by default).
  • breadcrumbGuessing: Whether to mark an item as "active" if its URL is on the breadcrumb stack. Default to true.
  • templates: HTML templates used when formating items.
    • div: Template of the wrapper element which holds all menus when using split.
    • root: Top UL/OL menu template.
    • parent: Wrapper which holds children of a parent node.
    • child: Template for child nodes (leafs).
    • link: Template for link elements.

Example:

This example shows where each template is used when rendering a menu.

<div> // div template (only if split > 1)
    <ul> // root template (first part of split menu)
        <li> // child template
            <a href="">Link 1</a> // link template
        </li>
        <li> // child template
            <a href="">Link 2</a> // link template
            <ul> // parent template
                <li> // child template
                    <a href="">Link 2.1</a> // link template
                </li>
                <li> // child template
                    <a href="">Link 2.2</a> // link template
                </li>
                ...
            </ul>
        </li>
        ...
    </ul>

    <ul> // root template (second part of split menu)
        ...
    </ul>

    ...
</div>

Type

array

$_rendering

$_rendering : boolean

Flags that indicates this helper is already rendering a menu.

Used to detect loops when using callable formatters.

Type

boolean

Methods

__construct()

__construct(\Cake\View\View $view, array $config)

Constructor.

Parameters

\Cake\View\View $view

The View this helper is being attached to

array $config

Configuration settings for the helper, will have no effect as configuration is set on every render() call

render()

render(integer|string|array|\Cake\Collection\Collection $items, callable|array $config) : string

Renders a nested menu.

This methods renders a HTML menu using a threaded result set:

// In controller:
$this->set('links', $this->Links->find('threaded'));

// In view:
echo $this->Menu->render('links');

Options:

You can pass an associative array key => value. Any key not in $_defaultConfig will be treated as an additional attribute for the top level UL (root). If key is in $_defaultConfig it will temporally overwrite default configuration parameters, it will be restored to its default values after rendering completes:

  • formatter: Callable method used when formating each item.
  • activeClass: CSS class to use when an item is active (its URL matches current URL).
  • firstItemClass: CSS class for the first item.
  • lastItemClass: CSS class for the last item.
  • hasChildrenClass: CSS class to use when an item has children.
  • split: Split menu into multiple root menus (multiple UL's)
  • templates: The templates you want to use for this menu. Any templates will be merged on top of the already loaded templates. This option can either be a filename in App/config that contains the templates you want to load, or an array of templates to use.

You can also pass a callable function as second argument which will be used as formatter:

echo $this->Menu->render($links, function ($link, $info) {
    // render $item here
});

Formatters receives two arguments, the item being rendered as first argument and information abut the item (has children, depth, etc) as second.

You can pass the ID or slug of a menu as fist argument to render that menu's links:

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

// OR

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

Parameters

integer|string|array|\Cake\Collection\Collection $items

Nested items to render, given as a query result set or as an array list. Or an integer as menu ID in DB to render, or a string as menu Slug in DB to render.

callable|array $config

An array of HTML attributes and options as described above or a callable function to use as formatter

Throws

\Cake\Error\FatalErrorException

When loop invocation is detected, that is, when "render()" method is invoked within a callable method when rendering menus.

Returns

string —

HTML

formatter()

formatter(\Cake\ORM\Entity $item, array $info, array $options) : string

Default callable method (see formatter option).

Valid options are:

  • templates: Array of templates indexed as templateName => templatePattern. Temporally overwrites templates when rendering this item, after item is rendered templates are restored to previous values.
  • childAttrs: Array of attributes for child template.
    • class: Array list of multiple CSS classes or a single string (will be merged with auto-generated CSS; "active", "has-children", etc).
  • linkAttrs: Array of attributes for the link template.
    • class: Same as childAttrs.

Information argument

The second argument $info holds a series of useful values when rendering each item of the menu. This values are stored as key => value array.

  • index (integer): Position of current item.
  • total (integer): Total number of items in the menu being rendered.
  • depth (integer): Item depth within the tree structure.
  • hasChildren (boolean): true|false
  • children (string): HTML content of rendered children for this item. Empty if has no children.

Parameters

\Cake\ORM\Entity $item

The item to render

array $info

Array of useful information such as described above

array $options

Additional options

Returns

string

countItems()

countItems(\Cake\ORM\Query $items) : integer

Counts items in menu.

Parameters

\Cake\ORM\Query $items

Items to count

Returns

integer

resetTemplates()

resetTemplates() : void

Restores the default template values built into MenuHelper.

trigger()

trigger(array|string $eventName) : \Cake\Event\Event

Triggers the given event name. This method provides a shortcut for:

$this->trigger('EventName', $arg1, $arg2, ..., $argn);

You can provide a subject to use by passing an array as first arguments where the first element is the event name and the second one is the subject, if no subject is given $this will be used by default:

$this->trigger(['GetTime', new MySubject()], $arg_0, $arg_1, ..., $arg_n);

You can also indicate an EventDispatcher instance to use by prefixing the event name with <InstanceName>::, for instance:

$this->trigger('Blog::EventName', $arg1, $arg2, ..., $argn);

This will use the EventDispacher instance named Blog and will trigger the event EventName within that instance.

Parameters

array|string $eventName

The event name to trigger

Returns

\Cake\Event\Event —

The event object that was fired

eventDispatcher()

eventDispatcher(string $name) : \QuickApps\Event\EventDispatcher

Gets an instance of the given Event Dispatcher name.

Usage:

$this->eventDispatcher('myDispatcher')
    ->trigger('MyEventName', $argument)
    ->result;

Parameters

string $name

Name of the dispatcher to get, defaults to 'default'

Returns

\QuickApps\Event\EventDispatcher

triggered()

triggered(string|null $eventName) : integer|array

Retrieves the number of times an event was triggered, or the complete list of events that were triggered.

Parameters

string|null $eventName

The name of the event, if null returns the entire list of event that were fired

Returns

integer|array

_prepareOptions()

_prepareOptions(array|callable $options) : array

Prepares options given to "render()" method.

Usage:

list($options, $attrs) = $this->_prepareOptions($options);

Parameters

array|callable $options

Options given to render()

Returns

array —

Array with two keys: 0 => $options sanitized and filtered options array, and 1 => $attrs list of attributes for top level UL element

_prepareItemAttrs()

_prepareItemAttrs(\Cake\Datasource\EntityInterface $item, array $info, array $options) : array

Prepares item's attributes for rendering.

Parameters

\Cake\Datasource\EntityInterface $item

The item being rendered

array $info

Item's rendering info

array $options

Item's rendering options

Returns

array —

Associative array with two keys, link and child

_prepareItems()

_prepareItems(mixed $items) : mixed

Prepares the items (links) to be rendered as part of a menu.

Parameters

mixed $items

As described on render()

Returns

mixed —

Collection of links to be rendered

_renderPart()

_renderPart(mixed $items, array $options, array $attrs) : string

Starts rendering process of a menu's parts (when using the "split" option).

Parameters

mixed $items

Menu links

array $options

Options for the rendering process

array $attrs

Menu's attributes

Returns

string

_render()

_render(\Cake\ORM\Query $items, integer $depth) : string

Internal method to recursively generate the menu.

Parameters

\Cake\ORM\Query $items

Items to render

integer $depth

Current iteration depth

Returns

string —

HTML

_count()

_count(\Cake\ORM\Query $items) : integer

Internal method for counting items in menu.

This method will ignore children if parent has been marked as do no expand.

Parameters

\Cake\ORM\Query $items

Items to count

Returns

integer

_clear()

_clear() : void

Clears all temporary variables used when rendering a menu, so they do not interfere when rendering other menus.