0 follower

Final Class Yiisoft\Bootstrap5\Dropdown

InheritanceYiisoft\Bootstrap5\Dropdown » Yiisoft\Widget\Widget

Dropdown renders a Bootstrap dropdown menu component.

For example,

<?= Dropdown::widget()
        ->items(
            DropdownItem::link('Action', '#'),
            DropdownItem::link('Another action', '#'),
            DropdownItem::link('Something else here', '#'),
            DropdownItem::divider(),
            DropdownItem::link('Separated link', '#'),
        )
        ->toggleContent('Toggle dropdown')
        ->toggleVariant(ButtonVariant::DANGER)
        ->toggleSplit()
        ->toggleSplitContent('Danger')
        ->toggleSizeLarge()
?>

Public Methods

Hide inherited methods

Method Description Defined By
addAttributes() Adds a sets of attributes. Yiisoft\Bootstrap5\Dropdown
addClass() Adds one or more CSS classes to the existing classes. Yiisoft\Bootstrap5\Dropdown
addCssStyle() Adds a CSS style. Yiisoft\Bootstrap5\Dropdown
addTogglerAttribute() Adds toggler attribute value. Yiisoft\Bootstrap5\Dropdown
addTogglerClass() Adds one or more CSS classes to the existing toggler classes. Yiisoft\Bootstrap5\Dropdown
addTogglerCssStyle() Adds a toggler CSS style. Yiisoft\Bootstrap5\Dropdown
alignment() Sets the alignment. Yiisoft\Bootstrap5\Dropdown
attribute() Adds a sets attribute value. Yiisoft\Bootstrap5\Dropdown
attributes() Sets the HTML attributes. Yiisoft\Bootstrap5\Dropdown
autoClose() Sets the auto-close setting. Yiisoft\Bootstrap5\Dropdown
class() Replaces all existing CSS classes with the specified one(s). Yiisoft\Bootstrap5\Dropdown
container() Whether to render in a container <div> tag. Yiisoft\Bootstrap5\Dropdown
containerClasses() Sets the CSS classes for the container. Yiisoft\Bootstrap5\Dropdown
direction() Set the direction. Yiisoft\Bootstrap5\Dropdown
getCssClasses() Returns the CSS classes for the container. Yiisoft\Bootstrap5\Dropdown
getItems() Returns the list of links to appear in the dropdown. Yiisoft\Bootstrap5\Dropdown
items() List of links. If this property is empty, the widget will not render anything. Yiisoft\Bootstrap5\Dropdown
render() Run the widget. Yiisoft\Bootstrap5\Dropdown
theme() Sets the theme. Yiisoft\Bootstrap5\Dropdown
toggler() Sets the toggler custom element. Yiisoft\Bootstrap5\Dropdown
togglerAsLink() Whether to render the toggler as a link. Yiisoft\Bootstrap5\Dropdown
togglerAttributes() Sets the HTML attributes for the toggler. Yiisoft\Bootstrap5\Dropdown
togglerClass() Replaces all existing CSS classes with the specified one(s). Yiisoft\Bootstrap5\Dropdown
togglerContent() Sets the content of the toggler. Yiisoft\Bootstrap5\Dropdown
togglerId() Sets the ID for the toggler. Yiisoft\Bootstrap5\Dropdown
togglerSize() Sets the size for the toggler. Yiisoft\Bootstrap5\Dropdown
togglerSplit() Whether to render the toggler as a split. Yiisoft\Bootstrap5\Dropdown
togglerSplitContent() Sets the content of the toggler split. Yiisoft\Bootstrap5\Dropdown
togglerUrl() Sets the URL for the toggler link. Yiisoft\Bootstrap5\Dropdown
togglerVariant() Sets the variant for the toggler. Yiisoft\Bootstrap5\Dropdown

Constants

Hide inherited constants

Constant Value Description Defined By
NAME 'dropdown' Yiisoft\Bootstrap5\Dropdown

Method Details

Hide inherited methods

addAttributes() public method

Adds a sets 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.

Example usage: `php $dropdown->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->cssClasses = [...$this->cssClasses, ...$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 $dropdown->addCssStyle('color: red');

// or $dropdown->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 $dropdown->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 $dropdown->addTogglerCssStyle('color: red');

// or $dropdown->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;
}

            
alignment() public method

Sets the alignment.

public self alignment ( \Yiisoft\Bootstrap5\DropdownAlignment|null $alignment )
$alignment \Yiisoft\Bootstrap5\DropdownAlignment|null

The alignment. If null, the alignment will not be set.

return self

A new instance with the specified alignment.

Example usage: `php $dropdown->alignment(DropdownAlignment::END()); `

                public function alignment(DropdownAlignment|null ...$alignment): self
{
    $new = clone $this;
    $new->alignmentClasses = $alignment;
    return $new;
}

            
attribute() public method

Adds a 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 $dropdown->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;
}

            
autoClose() public method

Sets the auto-close setting.

public self autoClose ( \Yiisoft\Bootstrap5\DropdownAutoClose $autoClose )
$autoClose \Yiisoft\Bootstrap5\DropdownAutoClose

The auto-close setting.

return self

A new instance with the specified auto-close setting.

Example usage: `php $dropdown->autoClose(DropdownAutoClose::OUTSIDE()); `

                public function autoClose(DropdownAutoClose $autoClose): self
{
    return $this->addTogglerAttribute('data-bs-auto-close', $autoClose->value);
}

            
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.

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

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

            
container() public method

Whether to render in a container <div> tag.

public self container ( boolean $enabled )
$enabled boolean

Whether to render in a container <div> tag. By default, it will be rendered in a container <div> tag. If set to false, the container will not be rendered.

return self

A new instance with the specified container setting.

Example usage: `php $dropdown->container(false); `

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

            
containerClasses() public method

Sets the CSS classes for the container.

public self containerClasses ( \BackedEnum|string $classes )
$classes \BackedEnum|string

The CSS class for the container.

return self

A new instance with the specified CSS class for the container.

Example usage: `php $dropdown->containerClasses(BackGroundColor::PRIMARY(), 'custom-class'); `

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

            
direction() public method

Set the direction.

public self direction ( \Yiisoft\Bootstrap5\DropdownDirection $direction )
$direction \Yiisoft\Bootstrap5\DropdownDirection

The direction.

return self

A new instance with the specified direction.

Example usage: `php $dropdown->direction(DropdownDirection::DOWN()); `

                public function direction(DropdownDirection $direction): self
{
    $new = clone $this;
    $new->containerClasses = [$direction];
    return $new;
}

            
getCssClasses() public method

Returns the CSS classes for the container.

public array getCssClasses ( )
return array

The CSS classes for the container.

                public function getCssClasses(): array
{
    return $this->cssClasses;
}

            
getItems() public method

Returns the list of links to appear in the dropdown.

public Yiisoft\Bootstrap5\DropdownItem[] getItems ( )
return Yiisoft\Bootstrap5\DropdownItem[]

The links to appear in the dropdown.

                public function getItems(): array
{
    return $this->items;
}

            
items() public method

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

public self items ( array $items )
$items array

The links.

return self

A new instance with the specified links.

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

            
render() public method

Run the widget.

public string render ( )
return string

The HTML representation of the element.

                public function render(): string
{
    $attributes = $this->attributes;
    $classes = $attributes['class'] ?? null;
    $containerClasses = $this->containerClasses;
    if ($this->items === []) {
        return '';
    }
    $togglerId = $this->getTogglerId();
    unset($attributes['class'], $attributes['id']);
    if ($this->togglerSplit) {
        $containerClasses = [self::DROPDOWN_TOGGLER_CONTAINER_CLASS];
    }
    $renderToggler = match ($this->togglerSplit) {
        true => $this->renderTogglerSplit() . "\n" . $this->renderToggler($togglerId),
        false => $this->renderToggler($togglerId),
    };
    $renderItems = $this->renderItems($togglerId);
    return match ($this->container) {
        true => Div::tag()
            ->addAttributes($attributes)
            ->addClass(...$containerClasses)
            ->addClass($classes)
            ->addClass(...$this->cssClasses)
            ->addContent(
                "\n",
                $renderToggler,
                "\n",
                $renderItems,
                "\n",
            )
            ->encode(false)
            ->render(),
        false => $renderToggler . "\n" . $renderItems,
    };
}

            
theme() public method

Sets the theme.

public self theme ( string $theme )
$theme string

The theme.

return self

A new instance with the specified theme.

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

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

            
toggler() public method

Sets the toggler custom element.

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

The toggler custom element.

return self

A new instance with the specified toggler custom element.

Example usage: `php $dropdown->toggler(

Button::tag()
    ->addAttributes(
        [
            'data-bs-toggle' => 'dropdown',
            'aria-expanded' => 'false',
        ],
    )
    ->addClass('btn btn-primary dropdown-toggle')
    ->content('Dropdown custom button'),

); `

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

            
togglerAsLink() public method

Whether to render the toggler as a link.

public self togglerAsLink ( boolean $enable true )
$enable boolean

Whether to render the toggler as a link. If set to true, the toggler will be rendered as a link. If set to false, the toggler will be rendered as a button.

return self

A new instance with the specified toggler as a link setting.

Example usage: `php $dropdown->togglerAsLink(); `

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;
}

            
togglerClass() 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 togglerClass ( \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 for the toggler.

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

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

            
togglerContent() public method

Sets the content of the toggler.

public self togglerContent ( string|\Stringable $content )
$content string|\Stringable

The content of the toggler.

return self

A new instance with the specified content of the toggler.

Example usage: `php $dropdown->togglerContent('Toggler dropdown'); `

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

            
togglerId() public method

Sets the ID for the toggler.

public self togglerId ( 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 for the toggler.

Example usage: `php $dropdown->togglerId(true); `

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

            
togglerSize() public method

Sets the size for the toggler.

public self togglerSize ( \Yiisoft\Bootstrap5\ButtonSize|null $size )
$size \Yiisoft\Bootstrap5\ButtonSize|null

The size. If null, the size will not be set.

return self

A new instance with the specified size for the toggler.

Example usage: `php $dropdown->togglerSize(ButtonSize::SMALL()); `

                public function togglerSize(ButtonSize|null $size): self
{
    $new = clone $this;
    $new->togglerSize = $size?->value;
    return $new;
}

            
togglerSplit() public method

Whether to render the toggler as a split.

public self togglerSplit ( boolean $enable true )
$enable boolean

Whether to render the toggler as a split. If set to true, the toggler will be rendered as a split. If set to false, the toggler will be rendered as normal.

return self

A new instance with the specified the toggler split setting.

Example usage: `php $dropdown->togglerSplit(); `

                public function togglerSplit(bool $enable = true): self
{
    $new = clone $this;
    $new->togglerSplit = $enable;
    return $new;
}

            
togglerSplitContent() public method

Sets the content of the toggler split.

public self togglerSplitContent ( string|\Stringable $content )
$content string|\Stringable

The content of the toggler split.

return self

A new instance with the specified content of the toggler split.

Example usage: `php $dropdown->togglerSplitContent('Action'); `

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

            
togglerUrl() public method

Sets the URL for the toggler link.

public self togglerUrl ( string $url )
$url string

The URL for the toggler link.

return self

A new instance with the specified URL for the toggler link.

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

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

            
togglerVariant() public method

Sets the variant for the toggler.

public self togglerVariant ( \Yiisoft\Bootstrap5\ButtonVariant|null $variant )
$variant \Yiisoft\Bootstrap5\ButtonVariant|null

The variant for the toggler. If null, the variant will not be set.

return self

A new instance with the specified variant for the toggler.

                public function togglerVariant(ButtonVariant|null $variant): self
{
    $new = clone $this;
    $new->togglerVariant = $variant;
    return $new;
}