0 follower

Final Class Yiisoft\Bootstrap5\Nav

InheritanceYiisoft\Bootstrap5\Nav » Yiisoft\Widget\Widget

Nav renders a Bootstrap navigation component.

For example:

// Basic navigation
<?= Nav::widget()
        ->items(
            NavLink::to('Home', '#', active: true),
            NavLink::to('Link', '#'),
            NavLink::to('Disabled', '#', disabled: true),
        )
?>

// Tabs navigation
<?= Nav::widget()
        ->items(
            NavLink::tab('Tab 1', 'Content 1', active: true),
            NavLink::tab('Tab 2', 'Content 2'),
            NavLink::tab('Tab 3', 'Content 3', disabled: true),
        )
        ->styles(NavStyle::TABS)
        ->withFade()
?>

Public Methods

Hide inherited methods

Method Description Defined By
activateItems() Whether to activate items by matching the currentPath with the url option in the nav items. Yiisoft\Bootstrap5\Nav
activateParents() Whether to activate the parent dropdown item when one of its child items is active. Yiisoft\Bootstrap5\Nav
addAttributes() Adds a set of attributes. Yiisoft\Bootstrap5\Nav
addClass() Adds one or more CSS classes to the existing classes. Yiisoft\Bootstrap5\Nav
addCssStyle() Adds a CSS style. Yiisoft\Bootstrap5\Nav
addDropdownClass() Adds one or more CSS classes to the existing classes for dropdown. Yiisoft\Bootstrap5\Nav
attribute() Sets attribute value. Yiisoft\Bootstrap5\Nav
attributes() Sets the HTML attributes. Yiisoft\Bootstrap5\Nav
class() Replaces all existing CSS classes with the specified one(s). Yiisoft\Bootstrap5\Nav
currentPath() The currentPath to be used to check the active state of the nav items. Yiisoft\Bootstrap5\Nav
fade() Whether to fade the navigation items when toggling between them. Yiisoft\Bootstrap5\Nav
id() Sets the ID. Yiisoft\Bootstrap5\Nav
items() List of links to appear in the nav. If this property is empty, the widget will not render anything. Yiisoft\Bootstrap5\Nav
paneAttributes() Sets the HTML attributes for the content panes. Yiisoft\Bootstrap5\Nav
render() Run the nav widget. Yiisoft\Bootstrap5\Nav
styles() Change the style of .navs component with modifiers and utilities. Mix and match as needed, or build your own. Yiisoft\Bootstrap5\Nav
tag() Set the tag name for the nav component. Yiisoft\Bootstrap5\Nav

Constants

Hide inherited constants

Constant Value Description Defined By
NAME 'nav' Yiisoft\Bootstrap5\Nav

Method Details

Hide inherited methods

activateItems() public method

Whether to activate items by matching the currentPath with the url option in the nav items.

public activateItems( boolean $enabled ): self
$enabled boolean

Whether to activate items. Defaults to true.

return self

A new instance with the specified activated items value.

Example usage: `php $nav->activateItems(false); `

                public function activateItems(bool $enabled): self
{
    $new = clone $this;
    $new->activateItems = $enabled;
    return $new;
}

            
activateParents() public method

Whether to activate the parent dropdown item when one of its child items is active.

When set to true, if a dropdown item's URL matches currentPath(), the dropdown toggle (parent) will also receive the active CSS class.

public activateParents( boolean $enabled ): self
$enabled boolean

Whether to activate parent items. Defaults to false.

return self

A new instance with the specified activate parents value.

Example usage: `php $nav->activateParents(true); `

                public function activateParents(bool $enabled): self
{
    $new = clone $this;
    $new->activateParents = $enabled;
    return $new;
}

            
addAttributes() public method

Adds a set of attributes.

public addAttributes( array $attributes ): self
$attributes array

Attribute values indexed by attribute names. for example, ['id' => 'my-id'].

return self

A new instance with the specified attributes added.

Example usage: `php $nav->addAttributes(['data-id' => '123']); `

                public function addAttributes(array $attributes): self
{
    $new = clone $this;
    $new->attributes = [...$this->attributes, ...$attributes];
    return $new;
}

            
addClass() public method

Adds one or more CSS classes to the existing classes.

Multiple classes can be added by passing them as separate arguments. null values are filtered out automatically.

public addClass( \BackedEnum|string|null $class ): self
$class \BackedEnum|string|null

One or more CSS class names to add. Pass null to skip adding a class.

return self

A new instance with the specified CSS classes added to existing ones.

                public function addClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->cssClasses = [...$this->cssClasses, ...$class];
    return $new;
}

            
addCssStyle() public method

Adds a CSS style.

public addCssStyle( array|string $style, boolean $overwrite true ): self
$style array|string

The CSS style. If the value is an array, a space will separate the values. For example, ['color' => 'red', 'font-weight' => 'bold'] will be rendered as color: red; font-weight: bold;. If it is a string, it will be added as is, for example, color: red.

$overwrite boolean

Whether to overwrite existing styles with the same name. If false, the new value will be appended to the existing one.

return self

A new instance with the specified CSS style value added.

Example usage: `php $nav->addCssStyle('color: red');

// or $nav->addCssStyle(['color' => 'red', 'font-weight' => 'bold']); `

                public function addCssStyle(array|string $style, bool $overwrite = true): self
{
    $new = clone $this;
    Html::addCssStyle($new->attributes, $style, $overwrite);
    return $new;
}

            
addDropdownClass() public method

Adds one or more CSS classes to the existing classes for dropdown.

Multiple classes can be added by passing them as separate arguments. null values are filtered out automatically.

public addDropdownClass( \BackedEnum|string|null $class ): self
$class \BackedEnum|string|null

One or more CSS class names to add. Pass null to skip adding a class.

return self

A new instance with the specified CSS classes added to existing ones for dropdown.

                public function addDropdownClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->dropdownCssClasses = [...$this->dropdownCssClasses, ...$class];
    return $new;
}

            
attribute() public method

Sets attribute value.

public attribute( string $name, mixed $value ): self
$name string

The attribute name.

$value mixed

The attribute value.

return self

A new instance with the specified attribute added.

Example usage: `php $nav->attribute('data-id', '123'); `

                public function attribute(string $name, mixed $value): self
{
    $new = clone $this;
    $new->attributes[$name] = $value;
    return $new;
}

            
attributes() public method

Sets the HTML attributes.

public attributes( array $attributes ): self
$attributes array

Attribute values indexed by attribute names.

return self

A new instance with the specified attributes.

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

            
class() public method

Replaces all existing CSS classes with the specified one(s).

Multiple classes can be added by passing them as separate arguments. null values are filtered out automatically.

public class( \BackedEnum|string|null $class ): self
$class \BackedEnum|string|null

One or more CSS class names to set. Pass null to skip setting a class.

return self

A new instance with the specified CSS classes set.

Example usage: `php $nav->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY); `

                public function class(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->cssClasses = $class;
    return $new;
}

            
currentPath() public method

The currentPath to be used to check the active state of the nav items.

public currentPath( string $path ): self
$path string

The current path to be used to check the active state of the nav items.

return self

A new instance with the specified current path.

Example usage: `php $nav->currentPath('/current/path'); `

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

            
fade() public method

Whether to fade the navigation items when toggling between them.

public fade( boolean $enabled ): self
$enabled boolean

Whether to fade the navigation items when toggling between them.

return self

A new instance with the specified fade value.

Example usage: `php $nav->fade(true); `

                public function fade(bool $enabled): self
{
    if ($enabled && $this->isTabsOrPills() === false) {
        throw new RuntimeException('Fade effect can only be used with tabs or pills.');
    }
    $new = clone $this;
    $new->fade = $enabled;
    return $new;
}

            
id() public method

Sets the ID.

public id( boolean|string $id ): self
$id boolean|string

The ID of the component. If true, an ID will be generated automatically.

return self

A new instance with the specified ID.

Example usage: `php $nav->id('my-id'); `

                public function id(bool|string $id): self
{
    $new = clone $this;
    $new->id = $id;
    return $new;
}

            
items() public method

List of links to appear in the nav. If this property is empty, the widget will not render anything.

public items( array $items ): self
$items array

The links to appear in the nav.

return self

A new instance with the specified links to appear in the nav.

                public function items(Dropdown|NavLink ...$items): self
{
    $new = clone $this;
    $new->items = $items;
    return $new;
}

            
paneAttributes() public method

Sets the HTML attributes for the content panes.

public paneAttributes( array $attributes ): self
$attributes array

Attribute values indexed by attribute names.

return self

A new instance with the specified pane attributes.

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

            
render() public method

Run the nav widget.

public render( ): string
return string

The HTML representation of the element.

                public function render(): string
{
    if ($this->items === []) {
        return '';
    }
    $attributes = $this->attributes;
    $classes = $attributes['class'] ?? null;
    $tabContent = '';
    /** @psalm-var non-empty-string|null $id */
    $id = match ($this->id) {
        true => $attributes['id'] ?? Html::generateId(self::NAME . '-'),
        '', false => null,
        default => $this->id,
    };
    unset($attributes['class'], $attributes['id']);
    if (in_array(NavStyle::NAVBAR, $this->styleClasses, true)) {
        Html::addCssClass($attributes, [...$this->styleClasses, ...$this->cssClasses, $classes]);
    } else {
        Html::addCssClass($attributes, [self::NAME, ...$this->styleClasses, ...$this->cssClasses, $classes]);
    }
    if ($this->isTabsOrPills()) {
        $tabContent = $this->renderTabContent();
    }
    if ($tabContent !== '') {
        $attributes['role'] = 'tablist';
    }
    $html = $this->tag === ''
        ? Ul::tag()->addAttributes($attributes)->id($id)->items(...$this->renderItems())->render()
        : Html::tag($this->tag)
            ->addAttributes($attributes)
            ->addContent("\n", implode("\n", $this->createLinks()), "\n")
            ->encode(false)
            ->render();
    return $html . $tabContent;
}

            
styles() public method

Change the style of .navs component with modifiers and utilities. Mix and match as needed, or build your own.

Multiple classes can be added by passing them as separate arguments. null values are filtered out automatically.

public styles( \Yiisoft\Bootstrap5\NavLayout|\Yiisoft\Bootstrap5\NavStyle|null $styles ): self
$styles \Yiisoft\Bootstrap5\NavLayout|\Yiisoft\Bootstrap5\NavStyle|null

One or more CSS style class names to add. Pass null to skip adding a class.

return self

A new instance with the specified CSS style classes added.

Example usage: `php $nav->styles(NavStyle::TABS); `

                public function styles(NavLayout|NavStyle|null ...$styles): self
{
    $new = clone $this;
    $new->styleClasses = [...$this->styleClasses, ...$styles];
    return $new;
}

            
tag() public method

Set the tag name for the nav component.

public tag( string|\Stringable $tag ): self
$tag string|\Stringable

The tag name for the nav component.

return self

A new instance with the specified tag name.

Example usage: `php $nav->tag('div'); `

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