Class yii\bootstrap5\Carousel
| Inheritance | yii\ |
|---|---|
| Uses Traits | yii\ |
| Source Code | https://github.com/yiisoft/yii2-bootstrap5/blob/master/src/Carousel.php |
Carousel renders a carousel bootstrap javascript component.
For example:
echo Carousel::widget([
'items' => [
// the item contains only the image
'<img src="https://twitter.github.io/bootstrap/assets/img/bootstrap-mdo-sfmoma-01.jpg"/>',
// equivalent to the above
['content' => '<img src="https://twitter.github.io/bootstrap/assets/img/bootstrap-mdo-sfmoma-02.jpg"/>'],
// the item contains both the image and the caption
[
'content' => '<img src="https://twitter.github.io/bootstrap/assets/img/bootstrap-mdo-sfmoma-03.jpg"/>',
'caption' => '<h4>This is title</h4><p>This is the caption text</p>',
'captionOptions' => ['class' => ['d-none', 'd-md-block']]
'options' => [...],
],
]
]);
See also https://getbootstrap.com/docs/5.1/components/carousel/.
Public Properties
| Property | Type | Description | Defined By |
|---|---|---|---|
| $clientEvents | array | The event handlers for the underlying Bootstrap JS plugin. | yii\ |
| $clientOptions | array|false | The options for the underlying Bootstrap JS plugin/component. | yii\ |
| $controls | array|null | The labels for the previous and the next control buttons. | yii\ |
| $crossfade | boolean | Animate slides with a fade transition instead of a slide. | yii\ |
| $items | array | List of slides in the carousel. | yii\ |
| $options | yii\ |
||
| $showIndicators | boolean | Whether carousel indicators (
|
yii\ |
Public Methods
| Method | Description | Defined By |
|---|---|---|
| init() | yii\ |
|
| renderControls() | Renders previous and next control buttons. | yii\ |
| renderIndicators() | Renders carousel indicators. | yii\ |
| renderItem() | Renders a single carousel item | yii\ |
| renderItems() | Renders carousel items as specified on $items. | yii\ |
| run() | yii\ |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| registerClientEvents() | Registers JS event handlers that are listed in $clientEvents. | yii\ |
| registerPlugin() | Registers a specific Bootstrap plugin/component and the related events. | yii\ |
Property Details
The labels for the previous and the next control buttons. If null, it means the previous and the next control buttons should not be displayed.
Animate slides with a fade transition instead of a slide. Defaults to false
List of slides in the carousel. Each array element represents a single slide with the following structure:
[
// required, slide content (HTML), such as an image tag
'content' => '<img src="https://twitter.github.io/bootstrap/assets/img/bootstrap-mdo-sfmoma-01.jpg"/>',
// optional, the caption (HTML) of the slide
'caption' => '<h4>This is title</h4><p>This is the caption text</p>',
// optional the HTML attributes of the slide container
'options' => [],
]
Whether carousel indicators (
- tag with anchors to items) should be displayed or not.
Method Details
| public void init ( ) | ||
| throws | \ |
|
|---|---|---|
public function init(): void
{
parent::init();
Html::addCssClass($this->options, [
'widget' => 'carousel slide',
]);
if ($this->crossfade) {
Html::addCssClass($this->options, [
'animation' => 'carousel-fade',
]);
}
}
Defined in:
yii\
Registers JS event handlers that are listed in $clientEvents.
| protected void registerClientEvents ( ?string $name = null ) | ||
| $name | ?string | |
protected function registerClientEvents(?string $name = null): void
{
if (!empty($this->clientEvents)) {
$id = $this->options['id'];
$js = [];
$appendix = ($name === 'dropdown') ? '.parentElement' : '';
foreach ($this->clientEvents as $event => $handler) {
$js[] = "document.getElementById('$id')$appendix.addEventListener('$event', $handler);";
}
$this->getView()->registerJs(implode("\n" , $js));
}
}
Defined in:
yii\
Registers a specific Bootstrap plugin/component and the related events.
| protected void registerPlugin ( string $name ) | ||
| $name | string |
The name of the Bootstrap plugin |
protected function registerPlugin(string $name): void
{
/**
* @see https://github.com/twbs/bootstrap/blob/v5.2.0/js/index.esm.js
*/
$jsPlugins = [
'alert',
'button',
'carousel',
'collapse',
'dropdown',
'modal',
'offcanvas',
'popover',
'scrollspy',
'tab',
'toast',
'tooltip',
];
if (in_array($name, $jsPlugins, true)) {
$view = $this->getView();
BootstrapPluginAsset::register($view);
// 'popover', 'toast' and 'tooltip' plugins not activates via data attributes
if ($this->clientOptions !== false || in_array($name, ['popover', 'toast', 'tooltip'], true)) {
$name = ucfirst($name);
$id = $this->options['id'];
$options = empty($this->clientOptions) ? '{}' : Json::htmlEncode($this->clientOptions);
$view->registerJs("(new bootstrap.$name('#$id', $options));");
}
$this->registerClientEvents($name);
}
}
Renders previous and next control buttons.
| public string renderControls ( ) | ||
| return | string |
The rendered controls |
|---|---|---|
| throws | \ |
if $controls is invalid. |
public function renderControls(): string
{
if (isset($this->controls[0], $this->controls[1])) {
return Html::button($this->controls[0], [
'class' => 'carousel-control-prev',
'data' => [
'bs-target' => '#' . $this->options['id'],
'bs-slide' => 'prev',
],
'type' => 'button',
]) . "\n"
. Html::button($this->controls[1], [
'class' => 'carousel-control-next',
'data' => [
'bs-target' => '#' . $this->options['id'],
'bs-slide' => 'next',
],
'type' => 'button',
]);
} elseif ($this->controls === false) {
return '';
} else {
throw new InvalidConfigException('The "controls" property must be either false or an array of two elements.');
}
}
Renders carousel indicators.
| public string renderIndicators ( ) | ||
| return | string |
The rendering result |
|---|---|---|
public function renderIndicators(): string
{
if ($this->showIndicators === false) {
return '';
}
$indicators = [];
for ($i = 0, $count = count($this->items); $i < $count; $i++) {
$options = [
'data' => [
'bs-target' => '#' . $this->options['id'],
'bs-slide-to' => $i,
],
'type' => 'button',
];
if ($i === 0) {
Html::addCssClass($options, [
'activate' => 'active',
]);
$options['aria']['current'] = 'true';
}
$indicators[] = Html::tag('button', '', $options);
}
return Html::tag('div', implode("\n" , $indicators), [
'class' => ['carousel-indicators'],
]);
}
Renders a single carousel item
| public string renderItem ( string|array $item, integer $index ) | ||
| $item | string|array |
A single item from $items |
| $index | integer |
The item index as the first item should be set to |
| return | string |
The rendering result |
|---|---|---|
| throws | \ |
if the item is invalid |
| throws | Exception | |
public function renderItem($item, int $index): string
{
if (is_string($item)) {
$content = $item;
$caption = null;
$options = [];
} elseif (isset($item['content'])) {
$content = $item['content'];
$caption = ArrayHelper::getValue($item, 'caption');
if ($caption !== null) {
$captionOptions = ArrayHelper::remove($item, 'captionOptions', []);
Html::addCssClass($captionOptions, [
'widget' => 'carousel-caption',
]);
$caption = Html::tag('div', $caption, $captionOptions);
}
$options = ArrayHelper::getValue($item, 'options', []);
} else {
throw new InvalidConfigException('The "content" option is required.');
}
Html::addCssClass($options, [
'widget' => 'carousel-item',
]);
if ($index === 0) {
Html::addCssClass($options, [
'activate' => 'active',
]);
}
return Html::tag('div', $content . "\n" . $caption, $options);
}
Renders carousel items as specified on $items.
| public string renderItems ( ) | ||
| return | string |
The rendering result |
|---|---|---|
| throws | \ |
|
public function renderItems(): string
{
$items = [];
for ($i = 0, $count = count($this->items); $i < $count; $i++) {
$items[] = $this->renderItem($this->items[$i], $i);
}
return Html::tag('div', implode("\n" , $items), [
'class' => 'carousel-inner',
]);
}