0 follower

Final Class Yiisoft\Yii\Widgets\Breadcrumbs

All Classes | Methods

Inheritance	Yiisoft\Yii\Widgets\Breadcrumbs » Yiisoft\Widget\Widget

Breadcrumbs displays a list of items indicating the position of the current page in the whole site hierarchy.

For example, breadcrumbs like "Home / Sample Post / Edit" means the user is viewing an edit page for the "Sample Post". He can click on "Sample Post" to view that page, or he can click on "Home" to return to the homepage.

To use Breadcrumbs, you need to configure its {@see \Yiisoft\Yii\Widgets\Breadcrumbs::items()} method, which specifies the items to be displayed. For example:

// $this is the view object currently being used
echo Breadcrumbs::widget()
    -> itemTemplate() => "<li><i>{link}</i></li>\n", // template for all links
    -> items() => [
        [
            'label' => 'Post Category',
            'url' => 'post-category/view?id=10',
            'template' => "<li><b>{link}</b></li>\n", // template for this link only
        ],
        ['label' => 'Sample Post', 'url' => 'post/edit?id=1'],
        'Edit',
    ];

Because breadcrumbs usually appears in nearly every page of a website, you may consider placing it in a layout view. You can use a view common parameter (e.g. $this->getCommonParameter('breadcrumbs')) to configure the items in different views. In the layout view, you assign this view parameter to the {@see \Yiisoft\Yii\Widgets\Breadcrumbs::items()} method like the following:

// $this is the view object currently being used
echo Breadcrumbs::widget()->items($this->getCommonParameter('breadcrumbs', []));

Public Methods

Hide inherited methods

Method	Description	Defined By
activeItemTemplate()	Returns a new instance with the specified active item template.	Yiisoft\Yii\Widgets\Breadcrumbs
attributes()	Returns a new instance with the HTML attributes. The following special options are recognized.	Yiisoft\Yii\Widgets\Breadcrumbs
homeItem()	Returns a new instance with the specified first item in the breadcrumbs (called home link).	Yiisoft\Yii\Widgets\Breadcrumbs
itemTemplate()	Returns a new instance with the specified item template.	Yiisoft\Yii\Widgets\Breadcrumbs
items()	Returns a new instance with the specified list of items.	Yiisoft\Yii\Widgets\Breadcrumbs
render()	Renders the widget.	Yiisoft\Yii\Widgets\Breadcrumbs
tag()	Returns a new instance with the specified tag.	Yiisoft\Yii\Widgets\Breadcrumbs

Method Details

Hide inherited methods

activeItemTemplate() public method

Returns a new instance with the specified active item template.

public self activeItemTemplate ( string $value )
$value	string	The template used to render each active item in the breadcrumbs. The token `{link}` will be replaced with the actual HTML link for each active item.

Source code

                public function activeItemTemplate(string $value): self
{
    $new = clone $this;
    $new->activeItemTemplate = $value;
    return $new;
}

attributes() public method

Returns a new instance with the HTML attributes. The following special options are recognized.

public self attributes ( array $valuesMap )
$valuesMap	array	Attribute values indexed by attribute names.

Source code

                public function attributes(array $valuesMap): self
{
    $new = clone $this;
    $new->attributes = $valuesMap;
    return $new;
}

homeItem() public method

Returns a new instance with the specified first item in the breadcrumbs (called home link).

If a null is specified, the home item will not be rendered.

public self homeItem ( array\|null $value )
$value	array\|null	Please refer to {@see \Yiisoft\Yii\Widgets\items()} on the format.
throws	InvalidArgumentException	If an empty array is specified.

Source code

                public function homeItem(?array $value): self
{
    if ($value === []) {
        throw new InvalidArgumentException(
            'The home item cannot be an empty array. To disable rendering of the home item, specify null.',
        );
    }
    $new = clone $this;
    $new->homeItem = $value;
    return $new;
}

itemTemplate() public method

Returns a new instance with the specified item template.

public self itemTemplate ( string $value )
$value	string	The template used to render each inactive item in the breadcrumbs. The token `{link}` will be replaced with the actual HTML link for each inactive item.

Source code

                public function itemTemplate(string $value): self
{
    $new = clone $this;
    $new->itemTemplate = $value;
    return $new;
}

items() public method

Returns a new instance with the specified list of items.

public self items ( array $value )
$value	array	List of items to appear in the breadcrumbs. If this property is empty, the widget will not render anything. Each array element represents a single item in the breadcrumbs with the following structure: `[ 'label' => 'label of the item', // required 'url' => 'url of the item', // optional 'template' => 'own template of the item', // optional, if not set $this->itemTemplate will be used ]` If an item is active, you only need to specify its "label", and instead of writing `['label' => $label]`, you may simply use `$label`. Additional array elements for each item will be treated as the HTML attributes for the hyperlink tag. For example, the following item specification will generate a hyperlink with CSS class `external`: `[ 'label' => 'demo', 'url' => 'http://example.com', 'class' => 'external', ]` To disable encode for a specific item, you can set the encode option to false: `[ 'label' => '<strong>Hello!</strong>', 'encode' => false, ]`

Source code

                public function items(array $value): self
{
    $new = clone $this;
    $new->items = $value;
    return $new;
}

render() public method

Renders the widget.

public string render ( )
return	string	The result of widget execution to be outputted.

Source code

                public function render(): string
{
    if ($this->items === []) {
        return '';
    }
    $items = [];
    if ($this->homeItem !== null) {
        $items[] = $this->renderItem($this->homeItem, $this->itemTemplate);
    }
    foreach ($this->items as $item) {
        if (!is_array($item)) {
            $item = ['label' => $item];
        }
        if ($item !== []) {
            $items[] = $this->renderItem(
                $item,
                isset($item['url']) ? $this->itemTemplate : $this->activeItemTemplate
            );
        }
    }
    $body = implode('', $items);
    return empty($this->tag)
        ? $body
        : Html::normalTag($this->tag, PHP_EOL . $body, $this->attributes)->encode(false)->render();
}

tag() public method

Returns a new instance with the specified tag.

public self tag ( string $value )
$value	string	The tag name.

Source code

                public function tag(string $value): self
{
    $new = clone $this;
    $new->tag = $value;
    return $new;
}