Class yii\bootstrap\Nav

Inheritanceyii\bootstrap\Nav » yii\bootstrap\Widget » yii\base\Widget
Uses Traitsyii\bootstrap\BootstrapWidgetTrait
Available since extension's version2.0
Source Code https://github.com/yiisoft/yii2-bootstrap/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' => '#'],
                 '<li class="divider"></li>',
                 '<li class="dropdown-header">Dropdown Header</li>',
                 ['label' => 'Level 1 - Dropdown B', 'url' => '#'],
            ],
        ],
        [
            'label' => 'Login',
            'url' => ['site/login'],
            'visible' => Yii::$app->user->isGuest
        ],
    ],
    'options' => ['class' =>'nav-pills'], // set this to nav-tab to get tab-styled navigation
]);

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

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\bootstrap\Nav
$activateParents boolean Whether to activate parent menu items when one of the corresponding child menu items is active. yii\bootstrap\Nav
$clientEvents array The event handlers for the underlying Bootstrap JS plugin. yii\bootstrap\BootstrapWidgetTrait
$clientOptions array The options for the underlying Bootstrap JS plugin. yii\bootstrap\BootstrapWidgetTrait
$dropDownCaret string This property allows you to customize the HTML which is used to generate the drop down caret symbol, which is displayed next to the button text to indicate the drop down functionality. yii\bootstrap\Nav
$dropdownClass string Name of a class to use for rendering dropdowns within this widget. yii\bootstrap\Nav
$encodeLabels boolean Whether the nav items labels should be HTML-encoded. yii\bootstrap\Nav
$items array List of items in the nav widget. yii\bootstrap\Nav
$options array The HTML attributes for the widget container tag. yii\bootstrap\Widget
$params array The parameters used to determine if a menu item is active or not. yii\bootstrap\Nav
$route string The route used to determine if a menu item is active or not. yii\bootstrap\Nav

Public Methods

Hide inherited methods

Method Description Defined By
getView() yii\bootstrap\BootstrapWidgetTrait
init() Initializes the widget. yii\bootstrap\Nav
renderItem() Renders a widget's item. yii\bootstrap\Nav
renderItems() Renders widget items. yii\bootstrap\Nav
run() Renders the widget. yii\bootstrap\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\bootstrap\Nav
isItemActive() Checks whether a menu item is active. yii\bootstrap\Nav
registerClientEvents() Registers JS event handlers that are listed in $clientEvents. yii\bootstrap\BootstrapWidgetTrait
registerPlugin() Registers a specific Bootstrap plugin and the related events yii\bootstrap\BootstrapWidgetTrait
renderDropdown() Renders the given items as a dropdown. yii\bootstrap\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
$dropDownCaret public property

This property allows you to customize the HTML which is used to generate the drop down caret symbol, which is displayed next to the button text to indicate the drop down functionality. Defaults to null which means <span class="caret"></span> will be used. To disable the caret, set this property to be an empty string.

public string $dropDownCaret null
$dropdownClass public property (available since version 2.0.7)

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

public string $dropdownClass 'yii\bootstrap\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.
  • 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\bootstrap\Dropdown widget.
  • items: array|string, optional, the configuration array for creating a yii\bootstrap\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\bootstrap\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();
    }
    if ($this->dropDownCaret === null) {
        $this->dropDownCaret = '<span class="caret"></span>';
    }
    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 (ArrayHelper::remove($items[$i], 'active', false) || $this->isItemActive($child)) {
            Html::addCssClass($items[$i]['options'], 'active');
            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'], '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['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 (available since version 2.0.2)

Defined in: yii\bootstrap\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\bootstrap\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 (available since version 2.0.1)

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\bootstrap\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.

                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

                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', []);
    if (isset($item['active'])) {
        $active = ArrayHelper::remove($item, 'active', false);
    } else {
        $active = $this->isItemActive($item);
    }
    if (empty($items)) {
        $items = '';
    } else {
        $linkOptions['data-toggle'] = 'dropdown';
        Html::addCssClass($options, ['widget' => 'dropdown']);
        Html::addCssClass($linkOptions, ['widget' => 'dropdown-toggle']);
        if ($this->dropDownCaret !== '') {
            $label .= ' ' . $this->dropDownCaret;
        }
        if (is_array($items)) {
            $items = $this->isChildActive($items, $active);
            $items = $this->renderDropdown($items, $item);
        }
    }
    if ($active) {
        Html::addCssClass($options, 'active');
    }
    return Html::tag('li', Html::a($label, $url, $linkOptions) . $items, $options);
}

            
renderItems() public method

Renders widget items.

public void renderItems ( )

                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 ( )

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