0 follower

Final Class Yiisoft\Bootstrap5\NavBar

All Classes | Methods | Constants
InheritanceYiisoft\Bootstrap5\NavBar » Yiisoft\Widget\Widget

NavBar renders a navbar HTML component.

Any content enclosed between the {@see \Yiisoft\Bootstrap5\begin()} and {@see \Yiisoft\Bootstrap5\end()} calls of NavBar is treated as the content of the navbar. You may use widgets such as {@see \Yiisoft\Bootstrap5\Nav} or {@see \Yiisoft\Widget\Menu} to build up such content. For example,

<?= NavBar::widget()
        ->addClass(BackgroundColor::BODY_TERTIARY)
        ->brandText('NavBar')
        ->brandUrl('#')
        ->id('navbarSupportedContent')
?>
<?= Nav::widget()
        ->items(
            NavLink::item('Home', '#', active: true),
            NavLink::item(label: 'Link', url: '#'),
            Dropdown::widget()
                 ->items(
                     DropdownItem::link('Action', '#'),
                     DropdownItem::link('Another action', '#'),
                     DropdownItem::divider(),
                     DropdownItem::link('Something else here', '#'),
                 ),
            NavLink::item('Disabled', '#', disabled: true),
        )
        ->styles(NavStyle::NAVBAR)
?>
<?= NavBar::end() ?>

Public Methods

Hide inherited methods

Method Description Defined By
addAttributes() Adds a set of attributes. Yiisoft\Bootstrap5\NavBar
addClass() Adds one or more CSS classes to the existing classes. Yiisoft\Bootstrap5\NavBar
addCssStyle() Adds a CSS style. Yiisoft\Bootstrap5\NavBar
addTogglerAttribute() Adds toggler attribute value. Yiisoft\Bootstrap5\NavBar
addTogglerClass() Adds one or more CSS classes to the existing toggler classes. Yiisoft\Bootstrap5\NavBar
addTogglerCssStyle() Adds a toggler CSS style. Yiisoft\Bootstrap5\NavBar
attribute() Sets attribute value. Yiisoft\Bootstrap5\NavBar
attributes() Sets the HTML attributes. Yiisoft\Bootstrap5\NavBar
begin() Begins the rendering of the navbar. Yiisoft\Bootstrap5\NavBar
brand() Sets the brand. Yiisoft\Bootstrap5\NavBar
brandAttributes() Sets the HTML attributes for the brand tag of the navbar component. Yiisoft\Bootstrap5\NavBar
brandImage() Sets the brand image. Yiisoft\Bootstrap5\NavBar
brandImageAttributes() Sets the HTML attributes for the brand image of the navbar component. Yiisoft\Bootstrap5\NavBar
brandText() Sets the brand text for the navbar component. Yiisoft\Bootstrap5\NavBar
brandUrl() Sets the brand URL for the navbar component. Yiisoft\Bootstrap5\NavBar
class() Replaces all existing CSS classes with the specified one(s). Yiisoft\Bootstrap5\NavBar
container() Sets whether the navbar contains navigation content in a container. Yiisoft\Bootstrap5\NavBar
containerAttributes() Sets the HTML attributes for the container of the navbar component. Yiisoft\Bootstrap5\NavBar
expand() Sets the expansion breakpoint class for the navigation bar. Yiisoft\Bootstrap5\NavBar
id() Sets the ID. Yiisoft\Bootstrap5\NavBar
innerContainer() Whether to use an inner container for the navbar component. Yiisoft\Bootstrap5\NavBar
innerContainerAttributes() Sets the HTML attributes for the inner container of the navbar component. Yiisoft\Bootstrap5\NavBar
placement() Sets the placement. Yiisoft\Bootstrap5\NavBar
render() Run the navbar widget. Yiisoft\Bootstrap5\NavBar
tag() Sets the tag name for the navbar component. Yiisoft\Bootstrap5\NavBar
theme() Sets the theme for the navbar component. Yiisoft\Bootstrap5\NavBar
toggler() Sets the toggle button. Yiisoft\Bootstrap5\NavBar
togglerAttributes() Sets the HTML attributes for the toggler. Yiisoft\Bootstrap5\NavBar

Constants

Hide inherited constants

Constant Value Description Defined By
NAME 'navbar' Yiisoft\Bootstrap5\NavBar

Method Details

Hide inherited methods

addAttributes() public method

Adds a set of attributes.

public self addAttributes ( array $attributes )
$attributes array

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

A new instance with the specified attributes added.

Usage example: `php $navBar->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 self addClass ( \BackedEnum|string|null $class )
$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->cssClass = [...$this->cssClass, ...$class];
    return $new;
}
addCssStyle() public method

Adds a CSS style.

public self addCssStyle ( array|string $style, boolean $overwrite = true )
$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 $navBar->addCssStyle('color: red');

// or $navBar->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;
}
addTogglerAttribute() public method

Adds toggler attribute value.

public self addTogglerAttribute ( string $name, mixed $value )
$name string

The attribute name.
$value mixed

The attribute value.
return self

A new instance with the specified attribute added.

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

 

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

Adds one or more CSS classes to the existing toggler classes.

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

public self addTogglerClass ( \BackedEnum|string|null $class )
$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 addTogglerClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    foreach ($class as $item) {
        Html::addCssClass($new->togglerAttributes, $item);
    }
    return $new;
}
addTogglerCssStyle() public method

Adds a toggler CSS style.

public self addTogglerCssStyle ( array|string $style, boolean $overwrite = true )
$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 $navbar->addTogglerCssStyle('color: red');

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

 

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

Sets attribute value.

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

The attribute name.
$value mixed

The attribute value.
return self

A new instance with the specified attribute added.

Example usage: `php $navBar->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 self attributes ( array $attributes )
$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;
}
begin() public method

Begins the rendering of the navbar.

public string begin ( )
return string

The opening HTML tags for the navbar.
throws InvalidArgumentException

if the tag is an empty string.

 

                public function begin(): string
{
    parent::begin();
    $attributes = $this->attributes;
    $classes = $attributes['class'] ?? null;
    $htmlBegin = '';
    $innerContainerAttributes = $this->innerContainerAttributes;
    $innerContainerClasses = $innerContainerAttributes['class'] ?? null;
    $id = match ($this->id) {
        true => $attributes['id'] ?? Html::generateId(self::NAME . '-'),
        '', false => throw new InvalidArgumentException('The "id" property must be specified.'),
        default => $this->id,
    };
    unset($attributes['class'], $attributes['id'], $innerContainerAttributes['class']);
    if ($this->tag === '') {
        throw new InvalidArgumentException('Tag cannot be empty string.');
    }
    Html::addCssClass($attributes, [self::NAME, $this->expand, $classes, ...$this->cssClass]);
    if ($this->container) {
        $htmlBegin = Html::openTag('div', $this->containerAttributes) . "\n";
    }
    if ($this->navId !== false) {
        $attributes['id'] = $this->navId;
    }
    $htmlBegin .= Html::openTag($this->tag, $attributes) . "\n";
    if ($this->innerContainer) {
        Html::addCssClass($innerContainerAttributes, [$innerContainerClasses ?? self::NAV_INNER_CONTAINER]);
        $htmlBegin .= Html::openTag($this->innerContainerTag, $innerContainerAttributes) . "\n";
    }
    $renderBrand = $this->renderBrand();
    if ($renderBrand !== '') {
        $htmlBegin .= $renderBrand . "\n";
    }
    $htmlBegin .= $this->renderToggler($id) . "\n";
    $htmlBegin .= Html::openTag('div', ['class' => self::NAV_CONTAINER, 'id' => $id]);
    return $htmlBegin . "\n";
}
brand() public method

Sets the brand.

public self brand ( string|\Stringable $brand )
$brand string|\Stringable

The brand to use.
return self

A new instance with the specified brand.

Example usage: `php $navBar->brand('My Brand'); `

 

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

Sets the HTML attributes for the brand tag of the navbar component.

public self brandAttributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names.
return self

A new instance with the specified attributes.

 

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

Sets the brand image.

public self brandImage ( string|\Stringable $image )
$image string|\Stringable

The brand image to use. If null, the brand image will not be displayed.
return self

A new instance with the specified brand image.

Example usage: `php $navBar->brandImage('path/to/image.png');

// or $navBar->brandImage(Img::tag()->src('path/to/image.png')); `

 

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

Sets the HTML attributes for the brand image of the navbar component.

public self brandImageAttributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names.
return self

A new instance with the specified attributes.

 

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

Sets the brand text for the navbar component.

public self brandText ( string|\Stringable $text )
$text string|\Stringable

The brand text for the navbar component. If null, the brand text will not be displayed.
return self

A new instance with the specified brand text.

Example usage: `php $navBar->brandText('My Brand'); `

 

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

Sets the brand URL for the navbar component.

public self brandUrl ( string $url )
$url string

The brand URL for the navbar component. If null, the brand URL will not be displayed.
return self

A new instance with the specified brand URL.

Example usage: `php $navBar->brandUrl('https://example.com'); `

 

                public function brandUrl(string $url): self
{
    $new = clone $this;
    $new->brandUrl = $url;
    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 self class ( \BackedEnum|string|null $class )
$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.

$navBar->class('custom-class', null, 'another-class');


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

Sets whether the navbar contains navigation content in a container.

public self container ( boolean $enabled )
$enabled boolean

Whether to use container for navigation content. If true navigation content will be wrapped in a container. If false navigation content spans full width.
return self

A new instance with the specified container setting.

Example usage: `php $navBar->container(true); `

 

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

Sets the HTML attributes for the container of the navbar component.

public self containerAttributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names.
return self

A new instance with the specified attributes.

 

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

Sets the expansion breakpoint class for the navigation bar.

public self expand ( \Yiisoft\Bootstrap5\NavBarExpand $class )
$class \Yiisoft\Bootstrap5\NavBarExpand

The breakpoint class at which the navbar will expand.
return self

A new instance with the specified expansion breakpoint.

Example usage: `php $navBar->expand(NavBarExpand::MD); `

 

                public function expand(NavBarExpand $class): self
{
    $new = clone $this;
    $new->expand = $class;
    return $new;
}
id() public method

Sets the ID.

public self id ( boolean|string $id )
$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 $navBar->id('navbarId'); `
throws InvalidArgumentException

if the ID is an empty string or false.

 

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

Whether to use an inner container for the navbar component.

public self innerContainer ( boolean $enabled )
$enabled boolean

'true' to use an inner container for the navbar component, 'false' otherwise.
return self

A new instance with the specified inner container setting.

Example usage: `php $navBar->innerContainer(true); `

 

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

Sets the HTML attributes for the inner container of the navbar component.

public self innerContainerAttributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names.
return self

A new instance with the specified attributes.

 

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

Sets the placement.

See also https://getbootstrap.com/docs/5.3/components/navbar/#placement Example usage: `php $navBar->placement(NavBarPlacement::FIXED_TOP); `.

public self placement ( \Yiisoft\Bootstrap5\NavBarPlacement $value )
$value \Yiisoft\Bootstrap5\NavBarPlacement

The placement.
return self

A new instance with the specified placement.

 

                public function placement(NavBarPlacement $value): self
{
    return $this->addClass($value);
}
render() public method

Run the navbar widget.

public string render ( )
return string

The HTML representation of the element.

 

                public function render(): string
{
    $htmlRender = '';
    if ($this->innerContainer) {
        $htmlRender .= "\n" . Html::closeTag($this->innerContainerTag) . "\n";
    }
    $htmlRender .= Html::closeTag('div') . "\n";
    $htmlRender .= Html::closeTag($this->tag);
    if ($this->container) {
        $htmlRender .= "\n" . Html::closeTag('div');
    }
    return $htmlRender;
}
tag() public method

Sets the tag name for the navbar component.

public self tag ( string $tag )
$tag string

The tag name for the navbar component.
return self

A new instance with the specified tag name.

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

 

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

Sets the theme for the navbar component.

public self theme ( string $theme )
$theme string

The theme for the navbar component.
return self

A new instance with the specified theme.

Example usage: `php $navBar->theme('dark'); `

 

                public function theme(string $theme): self
{
    return $this->addAttributes(['data-bs-theme' => $theme === '' ? null : $theme]);
}
toggler() public method

Sets the toggle button.

public self toggler ( string|\Stringable $toggle )
$toggle string|\Stringable

The toggle button.
return self

A new instance with the specified toggle button.

Example usage: `php $navBar->toggler('Toggle');

// or $navBar->toggler(Button::button('Toggle')); `

 

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

Sets the HTML attributes for the toggler.

public self togglerAttributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names.
return self

A new instance with the specified attributes for the toggler.

 

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