Fr3nch13/CakePHP Utilities

BreadcrumbsHelper extends Helper
in package

Application

uses StringTemplateTrait

BreadcrumbsHelper to register and display a breadcrumb trail for your views

Properties

$Url : UrlHelper
$_config : array<string, mixed>: Runtime config
$_configInitialized : bool: Whether the config property has already been configured with defaults
$_defaultConfig : array<string, mixed>: Default config for the helper.
$_helperMap : array<string, array<string|int, mixed>>: A helper lookup table used to lazy load helper objects.
$_templater : StringTemplate|null: StringTemplate instance.
$_View : View: The View instance this helper is attached to
$crumbs : array<string|int, mixed>: The crumb list.
$helpers : array<string|int, mixed>: Other helpers used by BreadcrumbsHelper.

Methods

__call() : mixed|void: Provide non fatal errors on missing method calls.
__construct() : mixed: Default Constructor
__debugInfo() : array<string, mixed>: Returns an array that can be used to describe the internal state of this object.
__get() : Helper|null|void: Lazy loads helpers.
add() : $this: Add a crumb to the end of the trail.
addClass() : array<string, mixed>: Adds the given class to the element options
configShallow() : $this: Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.
formatTemplate() : string: Formats a template string with $data
getConfig() : mixed: Returns the config.
getConfigOrFail() : mixed: Returns the config for this specific key.
getCrumbs() : array<string|int, mixed>: Returns the crumb list.
getTemplates() : array<string|int, mixed>|string: Gets templates to use or a specific template.
getView() : View: Get the view instance this helper is bound to.
implementedEvents() : array<string, mixed>: Get the View callbacks this helper is interested in.
initialize() : void: Constructor hook method.
insertAfter() : $this: Insert a crumb after the first matching crumb with the specified title.
insertAt() : $this: Insert a crumb at a specific index.
insertBefore() : $this: Insert a crumb before the first matching crumb with the specified title.
prepend() : $this: Prepend a crumb to the start of the queue.
render() : string: Renders the breadcrumbs trail.
reset() : $this: Removes all existing crumbs.
setConfig() : $this: Sets the config.
setTemplates() : $this: Sets templates to use.
templater() : StringTemplate: Returns the templater instance.
_configDelete() : void: Deletes a single config key.
_configRead() : mixed: Reads a config key.
_configWrite() : void: Writes a config key.
_confirm() : string: Returns a string to be used as onclick handler for confirm dialogs.
findCrumb() : int|null: Search a crumb in the current stack which title matches the one provided as argument.

$Url


    public
        UrlHelper
    $Url

$_config

Runtime config


    protected
        array<string, mixed>
    $_config
     = []

$_configInitialized

Whether the config property has already been configured with defaults


    protected
        bool
    $_configInitialized
     = false

$_defaultConfig

Default config for the helper.


    protected
        array<string, mixed>
    $_defaultConfig
     = ['templates' => ['wrapper' => '<ul{{attrs}}>{{content}}</ul>', 'item' => '<li{{attrs}}><a href="{{url}}"{{innerAttrs}}>{{title}}</a></li>{{separator}}', 'itemWithoutLink' => '<li{{attrs}}><span{{innerAttrs}}>{{title}}</span></li>{{separator}}', 'separator' => '<li{{attrs}}><span{{innerAttrs}}>{{separator}}</span></li>']]

$_helperMap

A helper lookup table used to lazy load helper objects.


    protected
        array<string, array<string|int, mixed>>
    $_helperMap
     = []

$_templater

StringTemplate instance.


    protected
        StringTemplate|null
    $_templater

$_View

The View instance this helper is attached to


    protected
        View
    $_View

$crumbs

The crumb list.


    protected
        array<string|int, mixed>
    $crumbs
     = []

$helpers

Other helpers used by BreadcrumbsHelper.


    protected
        array<string|int, mixed>
    $helpers
     = ['Url']

__call()

Provide non fatal errors on missing method calls.


    public
                    __call(string $method, array<string|int, mixed> $params) : mixed|void

Parameters

$method : string: Method to invoke
$params : array<string|int, mixed>: Array of params for the method.

Return values

mixed|void

__construct()

Default Constructor


    public
                    __construct(View $view[, array<string, mixed> $config = [] ]) : mixed

Parameters

$view : View: The View this helper is being attached to.
$config : array<string, mixed> = []: Configuration settings for the helper.

__debugInfo()

Returns an array that can be used to describe the internal state of this object.


    public
                    __debugInfo() : array<string, mixed>

Return values

array<string, mixed>

__get()

Lazy loads helpers.


    public
                    __get(string $name) : Helper|null|void

Parameters

$name : string: Name of the property being accessed.

Return values

Helper|null|void —

Helper instance if helper with provided name exists

add()

Add a crumb to the end of the trail.


    public
                    add(array<string|int, mixed>|string $title[, array<string|int, mixed>|string|null $url = null ][, array<string, mixed> $options = [] ]) : $this

Parameters

$title : array<string|int, mixed>|string

If provided as a string, it represents the title of the crumb. Alternatively, if you want to add multiple crumbs at once, you can provide an array, with each values being a single crumb. Arrays are expected to be of this form:

title The title of the crumb
link The link of the crumb. If not provided, no link will be made
options Options of the crumb. See description of params option of this method.

$url : array<string|int, mixed>|string|null = null

URL of the crumb. Either a string, an array of route params to pass to Url::build() or null / empty if the crumb does not have a link.

$options : array<string, mixed> = []

Array of options. These options will be used as attributes HTML attribute the crumb will be rendered in (a

tag by default). It accepts two special keys:

innerAttrs: An array that allows you to define attributes for the inner element of the crumb (by default, to the link)
templateVars: Specific template vars in case you override the templates provided.

Return values

$this

addClass()

Adds the given class to the element options


    public
                    addClass(array<string, mixed> $options, string $class[, string $key = 'class' ]) : array<string, mixed>

Parameters

$options : array<string, mixed>: Array options/attributes to add a class to
$class : string: The class name being added.
$key : string = 'class': the key to use for class. Defaults to 'class'.

Return values

array<string, mixed> —

Array of options with $key set.

configShallow()

Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.


    public
                    configShallow(array<string, mixed>|string $key[, mixed|null $value = null ]) : $this

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

$key : array<string, mixed>|string: The key to set, or a complete array of configs.
$value : mixed|null = null: The value to set.

Return values

$this

formatTemplate()

Formats a template string with $data


    public
                    formatTemplate(string $name, array<string, mixed> $data) : string

Parameters

$name : string: The template name.
$data : array<string, mixed>: The data to insert.

Return values

string

getConfig()

Returns the config.


    public
                    getConfig([string|null $key = null ][, mixed $default = null ]) : mixed

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

$key : string|null = null: The key to get or null for the whole config.
$default : mixed = null: The return value when the key does not exist.

Return values

mixed —

Configuration data at the named key or null if the key does not exist.

getConfigOrFail()

Returns the config for this specific key.


    public
                    getConfigOrFail(string $key) : mixed

The config value for this key must exist, it can never be null.

Parameters

$key : string: The key to get.

Return values

mixed —

Configuration data at the named key

getCrumbs()

Returns the crumb list.


    public
                    getCrumbs() : array<string|int, mixed>

Return values

array<string|int, mixed>

getTemplates()

Gets templates to use or a specific template.


    public
                    getTemplates([string|null $template = null ]) : array<string|int, mixed>|string

Parameters

$template : string|null = null: String for reading a specific template, null for all.

Return values

array<string|int, mixed>|string

getView()

Get the view instance this helper is bound to.


    public
                    getView() : View

Return values

View —

The bound view instance.

implementedEvents()

Get the View callbacks this helper is interested in.


    public
                    implementedEvents() : array<string, mixed>

By defining one of the callback methods a helper is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want helpers to listen to non-standard events.

Return values

array<string, mixed>

initialize()

Constructor hook method.


    public
                    initialize(array<string, mixed> $config) : void

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

$config : array<string, mixed>: The configuration settings provided to this helper.

insertAfter()

Insert a crumb after the first matching crumb with the specified title.


    public
                    insertAfter(string $matchingTitle, string $title[, array<string|int, mixed>|string|null $url = null ][, array<string, mixed> $options = [] ]) : $this

Finds the index of the first crumb that matches the provided class, and inserts the supplied callable before it.

Parameters

$matchingTitle : string

The title of the crumb you want to insert this one after.

$title : string

Title of the crumb.

$url : array<string|int, mixed>|string|null = null

URL of the crumb. Either a string, an array of route params to pass to Url::build() or null / empty if the crumb does not have a link.

$options : array<string, mixed> = []

Array of options. These options will be used as attributes HTML attribute the crumb will be rendered in (a

tag by default). It accepts two special keys:

innerAttrs: An array that allows you to define attributes for the inner element of the crumb (by default, to the link)
templateVars: Specific template vars in case you override the templates provided.

Return values

$this

insertAt()

Insert a crumb at a specific index.


    public
                    insertAt(int $index, string $title[, array<string|int, mixed>|string|null $url = null ][, array<string, mixed> $options = [] ]) : $this

If the index already exists, the new crumb will be inserted, before the existing element, shifting the existing element one index greater than before.

If the index is out of bounds, an exception will be thrown.

Parameters

$index : int

The index to insert at.

$title : string

Title of the crumb.

$url : array<string|int, mixed>|string|null = null

URL of the crumb. Either a string, an array of route params to pass to Url::build() or null / empty if the crumb does not have a link.

$options : array<string, mixed> = []

Array of options. These options will be used as attributes HTML attribute the crumb will be rendered in (a

tag by default). It accepts two special keys:

innerAttrs: An array that allows you to define attributes for the inner element of the crumb (by default, to the link)
templateVars: Specific template vars in case you override the templates provided.

Return values

$this

insertBefore()

Insert a crumb before the first matching crumb with the specified title.


    public
                    insertBefore(string $matchingTitle, string $title[, array<string|int, mixed>|string|null $url = null ][, array<string, mixed> $options = [] ]) : $this

Finds the index of the first crumb that matches the provided class, and inserts the supplied callable before it.

Parameters

$matchingTitle : string

The title of the crumb you want to insert this one before.

$title : string

Title of the crumb.

$url : array<string|int, mixed>|string|null = null

URL of the crumb. Either a string, an array of route params to pass to Url::build() or null / empty if the crumb does not have a link.

$options : array<string, mixed> = []

Array of options. These options will be used as attributes HTML attribute the crumb will be rendered in (a

tag by default). It accepts two special keys:

innerAttrs: An array that allows you to define attributes for the inner element of the crumb (by default, to the link)
templateVars: Specific template vars in case you override the templates provided.

Return values

$this

prepend()

Prepend a crumb to the start of the queue.


    public
                    prepend(array<string|int, mixed>|string $title[, array<string|int, mixed>|string|null $url = null ][, array<string, mixed> $options = [] ]) : $this

Parameters

$title : array<string|int, mixed>|string

title The title of the crumb
link The link of the crumb. If not provided, no link will be made
options Options of the crumb. See description of params option of this method.

$url : array<string|int, mixed>|string|null = null

URL of the crumb. Either a string, an array of route params to pass to Url::build() or null / empty if the crumb does not have a link.

$options : array<string, mixed> = []

Array of options. These options will be used as attributes HTML attribute the crumb will be rendered in (a

tag by default). It accepts two special keys:

innerAttrs: An array that allows you to define attributes for the inner element of the crumb (by default, to the link)
templateVars: Specific template vars in case you override the templates provided.

Return values

$this

render()

Renders the breadcrumbs trail.


    public
                    render([array<string, mixed> $attributes = [] ][, array<string, mixed> $separator = [] ]) : string

Parameters

$attributes : array<string, mixed> = []

Array of attributes applied to the wrapper template. Accepts the templateVars key to allow the insertion of custom template variable in the template.

$separator : array<string, mixed> = []

Array of attributes for the separator template. Possible properties are :

separator The string to be displayed as a separator
templateVars Allows the insertion of custom template variable in the template
innerAttrs To provide attributes in case your separator is divided in two elements.

All other properties will be converted as HTML attributes and will replace the attrs key in the template. If you use the default for this option (empty), it will not render a separator.

Return values

string —

The breadcrumbs trail

reset()

Removes all existing crumbs.


    public
                    reset() : $this

Return values

$this

setConfig()

Sets the config.


    public
                    setConfig(array<string, mixed>|string $key[, mixed|null $value = null ][, bool $merge = true ]) : $this

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

$key : array<string, mixed>|string: The key to set, or a complete array of configs.
$value : mixed|null = null: The value to set.
$merge : bool = true: Whether to recursively merge or overwrite existing config, defaults to true.

Return values

$this

setTemplates()

Sets templates to use.


    public
                    setTemplates(array<string|int, string> $templates) : $this

Parameters

$templates : array<string|int, string>: Templates to be added.

Return values

$this

templater()

Returns the templater instance.


    public
                    templater() : StringTemplate

Return values

StringTemplate

_configDelete()

Deletes a single config key.


    protected
                    _configDelete(string $key) : void

Parameters

$key : string: Key to delete.

_configRead()

Reads a config key.


    protected
                    _configRead(string|null $key) : mixed

Parameters

$key : string|null: Key to read.

_configWrite()

Writes a config key.


    protected
                    _configWrite(array<string, mixed>|string $key, mixed $value[, string|bool $merge = false ]) : void

Parameters

$key : array<string, mixed>|string: Key to write to.
$value : mixed: Value to write.
$merge : string|bool = false: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

_confirm()

Returns a string to be used as onclick handler for confirm dialogs.


    protected
                    _confirm(string $okCode, string $cancelCode) : string

Parameters

$okCode : string: Code to be executed after user chose 'OK'
$cancelCode : string: Code to be executed after user chose 'Cancel'

Return values

string —

"onclick" JS code

findCrumb()

Search a crumb in the current stack which title matches the one provided as argument.


    protected
                    findCrumb(string $title) : int|null

If found, the index of the matching crumb will be returned.

Parameters

$title : string: Title to find.

Return values

int|null —

Index of the crumb found, or null if it can not be found.

BreadcrumbsHelper extends Helper in package Application uses StringTemplateTrait

Table of Contents

Properties

Methods

Properties

$Url

$_config

$_configInitialized

$_defaultConfig

$_helperMap

$_templater

$_View

$crumbs

$helpers

Methods

__call()

Parameters

Return values

__construct()

Parameters

__debugInfo()

Return values

__get()

Parameters

Return values

add()

Parameters

Return values

addClass()

Parameters

Return values

configShallow()

Parameters

Return values

formatTemplate()

Parameters

Return values

getConfig()

Usage

Parameters

Return values

getConfigOrFail()

Parameters

Tags

Return values

getCrumbs()

Return values

getTemplates()

Parameters

Return values

getView()

Return values

implementedEvents()

Return values

initialize()

Parameters

insertAfter()

Parameters

Tags

Return values

insertAt()

Parameters

Tags

Return values

insertBefore()

Parameters

Tags

Return values

prepend()

Parameters

Return values

render()

Parameters

Return values

reset()

Return values

setConfig()

Usage

Parameters

Tags

BreadcrumbsHelper extends Helper
in package

Application

uses StringTemplateTrait