BootstrapWidgetTrait

API reference › Bootstrap 6 › BootstrapWidgetTrait

trait	`yii2\extensions\bootstrap6\BootstrapWidgetTrait`
Source	`src/BootstrapWidgetTrait.php`

Used by 2 types

Provides Bootstrap plugin registration, client options, and client events for widgets.

The using class must declare a public $options array; the trait fills $options['id'] when it is not set. Plugins initialize through a dynamic import() of the same module URL that BootstrapPluginAsset registers, so the browser evaluates the bundle once and no global is required.

Properties

Property	Type	Description	Defined by
`$clientEvents`	`array<string,` `yii\web\JsExpression\|string>`	Event handlers attached to the widget element, as event name => JavaScript handler source. Default: `[]`.	`BootstrapWidgetTrait`
`$clientOptions`	`array<string, mixed>\|false`	Options passed to the plugin constructor, or `false` to skip the JavaScript initialization. Default: `[]`.	`BootstrapWidgetTrait`

Methods

Method	Description	Defined by
`init()`	Initializes the widget and assigns an `id` to `$options` when it is not set.	`BootstrapWidgetTrait`
`pluginInitialization()` protected	Returns the JavaScript that initializes a plugin with its normalized constructor options.	`BootstrapWidgetTrait`
`registerClientEvents()` protected	Registers the JavaScript event handlers listed in `$clientEvents` at `View::POS_END`.	`BootstrapWidgetTrait`
`registerPlugin()` protected	Registers the plugin asset, the plugin initialization when needed, and the `$clientEvents`.	`BootstrapWidgetTrait`

Property details

$clientEvents

public array<string, yii\web\JsExpression|string> $clientEvents = []

Event handlers attached to the widget element, as event name => JavaScript handler source.

For example, ['shown.bs.toast' => 'function (event) { ... }'].

$clientOptions

public array<string, mixed>|false $clientOptions = []

Options passed to the plugin constructor, or false to skip the JavaScript initialization.

Enum cases at any depth are encoded as their value (backed) or name (pure), and Stringable values as their string; JsExpression values are emitted as raw JavaScript.

Method details

init()

public function init(): void

Initializes the widget and assigns an id to $options when it is not set.

pluginInitialization()

protected function pluginInitialization(string $name, string $element, string $options): string

Returns the JavaScript that initializes a plugin with its normalized constructor options.

Parameters

Parameter	Type	Description
`$name`	`string`	Plugin class exported by the bundle.
`$element`	`string`	JavaScript expression selecting the plugin element.
`$options`	`string`	JSON-encoded constructor options.

Returns

string

registerClientEvents()

protected function registerClientEvents(): void

Registers the JavaScript event handlers listed in $clientEvents at View::POS_END.

registerPlugin()

protected function registerPlugin(string $name, bool $always = false): void

Registers the plugin asset, the plugin initialization when needed, and the $clientEvents.

The initialization is emitted when $clientOptions is a non-empty array, or when $always is true and $clientOptions is not false.

Parameters

Parameter	Type	Description
`$name`	`string`	Plugin class exported by the bundle, for example `Toast`.
`$always`	`bool`	Whether to initialize the plugin even when `$clientOptions` is empty.

Throws

yii\base\InvalidArgumentException: if the bundle does not export the plugin.