Class yii\bootstrap4\Nav

All Classes | Properties | Methods
Inheritanceyii\bootstrap4\Nav » yii\bootstrap4\Widget » yii\base\Widget
Uses Traitsyii\bootstrap4\BootstrapWidgetTrait
Source Code https://github.com/yiisoft/yii2-bootstrap4/blob/master/src/Nav.php

Nav renders a nav HTML component.

For example:

echo Nav::widget([
    'items' => [
        [
            'label' => 'Home',
            'url' => ['site/index'],
            'linkOptions' => [...],
        ],
        [
            'label' => 'Dropdown',
            'items' => [
                 ['label' => 'Level 1 - Dropdown A', 'url' => '#'],
                 '<div class="dropdown-divider"></div>',
                 '<div class="dropdown-header">Dropdown Header</div>',
                 ['label' => 'Level 1 - Dropdown B', 'url' => '#'],
            ],
        ],
        [
            'label' => 'Login',
            'url' => ['site/login'],
            'visible' => Yii::$app->user->isGuest
        ],
    ],
    'options' => ['class' =>'nav-pills'], // set this to nav-tabs to get tab-styled navigation
]);

Note: Multilevel dropdowns beyond Level 1 are not supported in Bootstrap 4.

See also:

Public Properties

Hide inherited properties

Property Type Description Defined By
$activateItems boolean Whether to automatically activate items according to whether their route setting matches the currently requested route. yii\bootstrap4\Nav
$activateParents boolean Whether to activate parent menu items when one of the corresponding child menu items is active. yii\bootstrap4\Nav
$clientEvents array The event handlers for the underlying Bootstrap JS plugin. yii\bootstrap4\BootstrapWidgetTrait
$clientOptions array The options for the underlying Bootstrap JS plugin. yii\bootstrap4\BootstrapWidgetTrait
$dropdownClass string Name of a class to use for rendering dropdowns within this widget. yii\bootstrap4\Nav
$encodeLabels boolean Whether the nav items labels should be HTML-encoded. yii\bootstrap4\Nav
$items array List of items in the nav widget. yii\bootstrap4\Nav
$options array The HTML attributes for the widget container tag. yii\bootstrap4\Widget
$params array The parameters used to determine if a menu item is active or not. yii\bootstrap4\Nav
$route string The route used to determine if a menu item is active or not. yii\bootstrap4\Nav

Public Methods

Hide inherited methods

Method Description Defined By
getView() yii\bootstrap4\BootstrapWidgetTrait
init() Initializes the widget. yii\bootstrap4\Nav
renderItem() Renders a widget's item. yii\bootstrap4\Nav
renderItems() Renders widget items. yii\bootstrap4\Nav
run() Renders the widget. yii\bootstrap4\Nav

Protected Methods

Hide inherited methods

Method Description Defined By
isChildActive() Check to see if a child item is active optionally activating the parent. yii\bootstrap4\Nav
isItemActive() Checks whether a menu item is active. yii\bootstrap4\Nav
registerClientEvents() Registers JS event handlers that are listed in $clientEvents. yii\bootstrap4\BootstrapWidgetTrait
registerPlugin() Registers a specific Bootstrap plugin and the related events yii\bootstrap4\BootstrapWidgetTrait
renderDropdown() Renders the given items as a dropdown. yii\bootstrap4\Nav

Property Details

Hide inherited properties

$activateItems public property

Whether to automatically activate items according to whether their route setting matches the currently requested route.

See also isItemActive().

public boolean $activateItems = true
$activateParents public property

Whether to activate parent menu items when one of the corresponding child menu items is active.

public boolean $activateParents = false
$dropdownClass public property

Name of a class to use for rendering dropdowns within this widget. Defaults to yii\bootstrap4\Dropdown.

public string $dropdownClass = 'yii\bootstrap4\Dropdown'
$encodeLabels public property

Whether the nav items labels should be HTML-encoded.

public boolean $encodeLabels = true
$items public property

List of items in the nav widget. Each array element represents a single menu item which can be either a string or an array with the following structure:

  • label: string, required, the nav item label.
  • url: optional, the item's URL. Defaults to "#".
  • visible: bool, optional, whether this menu item is visible. Defaults to true.
  • disabled: bool, optional, whether this menu item is disabled. Defaults to false.
  • linkOptions: array, optional, the HTML attributes of the item's link.
  • options: array, optional, the HTML attributes of the item container (LI).
  • active: bool, optional, whether the item should be on active state or not.
  • dropdownOptions: array, optional, the HTML options that will passed to the yii\bootstrap4\Dropdown widget.
  • items: array|string, optional, the configuration array for creating a yii\bootstrap4\Dropdown widget, or a string representing the dropdown menu. Note that Bootstrap does not support sub-dropdown menus.
  • encode: bool, optional, whether the label will be HTML-encoded. If set, supersedes the $encodeLabels option for only this item.

If a menu item is a string, it will be rendered directly without HTML encoding.

public array $items = []
$params public property

The parameters used to determine if a menu item is active or not. If not set, it will use $_GET.

See also:

public array $params = null
$route public property

The route used to determine if a menu item is active or not. If not set, it will use the route of the current request.

See also:

public string $route = null

Method Details

Hide inherited methods

getView() public abstract method

Defined in: yii\bootstrap4\BootstrapWidgetTrait::getView()

See also \yii\base\Widget::getView().

public abstract \yii\web\View getView ( )
return \yii\web\View

The view object that can be used to render views or view files.

 

                abstract function getView();
init() public method

Initializes the widget.

public void init ( )

                public function init()
{
    parent::init();
    if ($this->route === null && Yii::$app->controller !== null) {
        $this->route = Yii::$app->controller->getRoute();
    }
    if ($this->params === null) {
        $this->params = Yii::$app->request->getQueryParams();
    }
    Html::addCssClass($this->options, ['widget' => 'nav']);
}
isChildActive() protected method

Check to see if a child item is active optionally activating the parent.

protected array isChildActive ( $items, &$active )
$items array

@see items
$active boolean

Should the parent be active too
return array

@see items

 

                protected function isChildActive($items, &$active)
{
    foreach ($items as $i => $child) {
        if (is_array($child) && !ArrayHelper::getValue($child, 'visible', true)) {
            continue;
        }
        if ($this->isItemActive($child)) {
            ArrayHelper::setValue($items[$i], 'active', true);
            if ($this->activateParents) {
                $active = true;
            }
        }
        $childItems = ArrayHelper::getValue($child, 'items');
        if (is_array($childItems)) {
            $activeParent = false;
            $items[$i]['items'] = $this->isChildActive($childItems, $activeParent);
            if ($activeParent) {
                Html::addCssClass($items[$i]['options'], ['activate' => 'active']);
                $active = true;
            }
        }
    }
    return $items;
}
isItemActive() protected method

Checks whether a menu item is active.

This is done by checking if $route and $params match that specified in the url option of the menu item. When the url option of a menu item is specified in terms of an array, its first element is treated as the route for the item and the rest of the elements are the associated parameters. Only when its route and parameters match $route and $params, respectively, will a menu item be considered active.

protected boolean isItemActive ( $item )
$item array

The menu item to be checked
return boolean

Whether the menu item is active

 

                protected function isItemActive($item)
{
    if (!$this->activateItems) {
        return false;
    }
    if (isset($item['active'])) {
        return ArrayHelper::getValue($item, 'active', false);
    }
    if (isset($item['url']) && is_array($item['url']) && isset($item['url'][0])) {
        $route = $item['url'][0];
        if ($route[0] !== '/' && Yii::$app->controller) {
            $route = Yii::$app->controller->module->getUniqueId() . '/' . $route;
        }
        if (ltrim($route, '/') !== $this->route) {
            return false;
        }
        unset($item['url']['#']);
        if (count($item['url']) > 1) {
            $params = $item['url'];
            unset($params[0]);
            foreach ($params as $name => $value) {
                if ($value !== null && (!isset($this->params[$name]) || $this->params[$name] != $value)) {
                    return false;
                }
            }
        }
        return true;
    }
    return false;
}
registerClientEvents() protected method

Defined in: yii\bootstrap4\BootstrapWidgetTrait::registerClientEvents()

Registers JS event handlers that are listed in $clientEvents.

protected void registerClientEvents ( )

                protected function registerClientEvents()
{
    if (!empty($this->clientEvents)) {
        $id = $this->options['id'];
        $js = [];
        foreach ($this->clientEvents as $event => $handler) {
            $js[] = "jQuery('#$id').on('$event', $handler);";
        }
        $this->getView()->registerJs(implode("\n", $js));
    }
}
registerPlugin() protected method

Defined in: yii\bootstrap4\BootstrapWidgetTrait::registerPlugin()

Registers a specific Bootstrap plugin and the related events

protected void registerPlugin ( $name )
$name string

The name of the Bootstrap plugin

 

                protected function registerPlugin($name)
{
    $view = $this->getView();
    BootstrapPluginAsset::register($view);
    $id = $this->options['id'];
    if ($this->clientOptions !== false) {
        $options = empty($this->clientOptions) ? '' : Json::htmlEncode($this->clientOptions);
        $js = "jQuery('#$id').$name($options);";
        $view->registerJs($js);
    }
    $this->registerClientEvents();
}
renderDropdown() protected method

Renders the given items as a dropdown.

This method is called to create sub-menus.

protected string renderDropdown ( $items, $parentItem )
$items array

The given items. Please refer to yii\bootstrap4\Dropdown::$items for the array structure.
$parentItem array

The parent item information. Please refer to $items for the structure of this array.
return string

The rendering result.
throws Exception 

                protected function renderDropdown($items, $parentItem)
{
    /** @var Widget $dropdownClass */
    $dropdownClass = $this->dropdownClass;
    return $dropdownClass::widget([
        'options' => ArrayHelper::getValue($parentItem, 'dropdownOptions', []),
        'items' => $items,
        'encodeLabels' => $this->encodeLabels,
        'clientOptions' => false,
        'view' => $this->getView(),
    ]);
}
renderItem() public method

Renders a widget's item.

public string renderItem ( $item )
$item string|array

The item to render.
return string

The rendering result.
throws \yii\base\InvalidConfigException
throws Exception 

                public function renderItem($item)
{
    if (is_string($item)) {
        return $item;
    }
    if (!isset($item['label'])) {
        throw new InvalidConfigException("The 'label' option is required.");
    }
    $encodeLabel = isset($item['encode']) ? $item['encode'] : $this->encodeLabels;
    $label = $encodeLabel ? Html::encode($item['label']) : $item['label'];
    $options = ArrayHelper::getValue($item, 'options', []);
    $items = ArrayHelper::getValue($item, 'items');
    $url = ArrayHelper::getValue($item, 'url', '#');
    $linkOptions = ArrayHelper::getValue($item, 'linkOptions', []);
    $disabled = ArrayHelper::getValue($item, 'disabled', false);
    $active = $this->isItemActive($item);
    if (empty($items)) {
        $items = '';
        Html::addCssClass($options, ['widget' => 'nav-item']);
        Html::addCssClass($linkOptions, ['widget' => 'nav-link']);
    } else {
        $linkOptions['data-toggle'] = 'dropdown';
        Html::addCssClass($options, ['widget' => 'dropdown nav-item']);
        Html::addCssClass($linkOptions, ['widget' => 'dropdown-toggle nav-link']);
        if (is_array($items)) {
            $items = $this->isChildActive($items, $active);
            $items = $this->renderDropdown($items, $item);
        }
    }
    if ($disabled) {
        ArrayHelper::setValue($linkOptions, 'tabindex', '-1');
        ArrayHelper::setValue($linkOptions, 'aria-disabled', 'true');
        Html::addCssClass($linkOptions, ['disable' => 'disabled']);
    } elseif ($this->activateItems && $active) {
        Html::addCssClass($linkOptions, ['activate' => 'active']);
    }
    return Html::tag('li', Html::a($label, $url, $linkOptions) . $items, $options);
}
renderItems() public method

Renders widget items.

public void renderItems ( )
throws \yii\base\InvalidConfigException 

                public function renderItems()
{
    $items = [];
    foreach ($this->items as $i => $item) {
        if (isset($item['visible']) && !$item['visible']) {
            continue;
        }
        $items[] = $this->renderItem($item);
    }
    return Html::tag('ul', implode("\n", $items), $this->options);
}
run() public method

Renders the widget.

public void run ( )
throws \yii\base\InvalidConfigException 

                public function run()
{
    BootstrapAsset::register($this->getView());
    return $this->renderItems();
}