Class yii\bootstrap\Tabs
| Inheritance | yii\ |
|---|---|
| Uses Traits | yii\ |
| Available since extension's version | 2.0 |
| Source Code | https://github.com/yiisoft/yii2-bootstrap/blob/master/src/Tabs.php |
Tabs renders a Tab bootstrap javascript component.
For example:
echo Tabs::widget([
'items' => [
[
'label' => 'One',
'content' => 'Anim pariatur cliche...',
'active' => true
],
[
'label' => 'Two',
'content' => 'Anim pariatur cliche...',
'headerOptions' => [...],
'options' => ['id' => 'myveryownID'],
],
[
'label' => 'Example',
'url' => 'http://www.example.com',
],
[
'label' => 'Dropdown',
'items' => [
[
'label' => 'DropdownA',
'content' => 'DropdownA, Anim pariatur cliche...',
],
[
'label' => 'DropdownB',
'content' => 'DropdownB, Anim pariatur cliche...',
],
[
'label' => 'External Link',
'url' => 'http://www.example.com',
],
],
],
],
]);
See also http://getbootstrap.com/javascript/#tabs.
Public Properties
| Property | Type | Description | Defined By |
|---|---|---|---|
| $clientEvents | array | The event handlers for the underlying Bootstrap JS plugin. | yii\ |
| $clientOptions | array | The options for the underlying Bootstrap JS plugin. | yii\ |
| $dropdownClass | string | Name of a class to use for rendering dropdowns withing this widget. | yii\ |
| $encodeLabels | boolean | Whether the labels for header items should be HTML-encoded. | yii\ |
| $headerOptions | array | List of HTML attributes for the header container tags. | yii\ |
| $itemOptions | array | List of HTML attributes for the item container tags. | yii\ |
| $items | array | List of tabs in the tabs widget. | yii\ |
| $linkOptions | array | List of HTML attributes for the tab header link tags. | yii\ |
| $navType | string | Specifies the Bootstrap tab styling. | yii\ |
| $options | array | The HTML attributes for the widget container tag. | yii\ |
| $renderTabContent | boolean | Whether to render the tab-content container and its content. |
yii\ |
| $tabContentOptions | array | List of HTML attributes for the tab-content container. |
yii\ |
| $template | string | Template for layout for the headers and the panes. | yii\ |
Public Methods
| Method | Description | Defined By |
|---|---|---|
| getView() | yii\ |
|
| init() | Initializes the widget. | yii\ |
| renderPanes() | Renders tab panes. | yii\ |
| run() | Renders the widget. | yii\ |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| activateFirstVisibleTab() | Sets the first visible tab as active. | yii\ |
| hasActiveTab() | yii\ |
|
| registerClientEvents() | Registers JS event handlers that are listed in $clientEvents. | yii\ |
| registerPlugin() | Registers a specific Bootstrap plugin and the related events | yii\ |
| renderDropdown() | Normalizes dropdown item options by removing tab specific keys content and contentOptions, and also
configure panes accordingly. |
yii\ |
| renderItems() | Renders tab items as specified on $items. | yii\ |
Property Details
Name of a class to use for rendering dropdowns withing this widget. Defaults to yii\
Whether the labels for header items should be HTML-encoded.
List of HTML attributes for the header container tags. This will be overwritten by the "headerOptions" set in individual $items.
See also \
List of HTML attributes for the item container tags. This will be overwritten by the "options" set in individual $items. The following special options are recognized:
- tag: string, defaults to "div", the tag name of the item container tags.
See also \
List of tabs in the tabs widget. Each array element represents a single tab with the following structure:
- label: string, required, the tab header label.
- encode: bool, optional, whether this label should be HTML-encoded. This param will override
global
$this->encodeLabelsparam. - headerOptions: array, optional, the HTML attributes of the tab header.
- linkOptions: array, optional, the HTML attributes of the tab header link tags.
- content: string, optional, the content (HTML) of the tab pane.
- url: string, optional, an external URL. When this is specified, clicking on this tab will bring the browser to this URL. This option is available since version 2.0.4.
- options: array, optional, the HTML attributes of the tab pane container.
- active: bool, optional, whether this item tab header and pane should be active. If no item is marked as 'active' explicitly - the first one will be activated.
- visible: bool, optional, whether the item tab header and pane should be visible or not. Defaults to true.
- items: array, optional, can be used instead of
contentto specify a dropdown items configuration array. Each item can hold three extra keys, besides the above ones:- active: bool, optional, whether the item tab header and pane should be visible or not.
- content: string, required if
itemsis not set. The content (HTML) of the tab pane. - contentOptions: optional, array, the HTML attributes of the tab content container.
List of HTML attributes for the tab header link tags. This will be overwritten by the "linkOptions" set in individual $items.
See also \
Whether to render the tab-content container and its content. You may set this property
to be false so that you can manually render tab-content yourself in case your tab contents are complex.
List of HTML attributes for the tab-content container. This will always contain the CSS class tab-content.
See also \
Method Details
Sets the first visible tab as active.
This method activates the first tab that is visible and
not explicitly set to inactive ('active' => false).
| protected mixed activateFirstVisibleTab ( ) |
protected function activateFirstVisibleTab()
{
foreach ($this->items as $i => $item) {
$active = ArrayHelper::getValue($item, 'active', null);
$visible = ArrayHelper::getValue($item, 'visible', true);
if ($visible && $active !== false) {
$this->items[$i]['active'] = true;
return;
}
}
}
| public abstract \ | ||
| return | \ |
The view object that can be used to render views or view files. |
|---|---|---|
abstract function getView();
| protected boolean hasActiveTab ( ) | ||
| return | boolean |
If there's active tab defined |
|---|---|---|
protected function hasActiveTab()
{
foreach ($this->items as $item) {
if (isset($item['active']) && $item['active'] === true) {
return true;
}
}
return false;
}
Initializes the widget.
| public mixed init ( ) |
public function init()
{
parent::init();
Html::addCssClass($this->options, ['widget' => 'nav', $this->navType]);
Html::addCssClass($this->tabContentOptions, 'tab-content');
}
Defined in:
yii\
Registers JS event handlers that are listed in $clientEvents.
| protected mixed registerClientEvents ( ) |
protected function registerClientEvents()
{
if (!empty($this->clientEvents)) {
$id = $this->options['id'];
$js = [];
foreach ($this->clientEvents as $event => $handler) {
$js[] = "jQuery('#$id').on('$event', $handler);";
}
$this->getView()->registerJs(implode("\n" , $js));
}
}
Defined in:
yii\
Registers a specific Bootstrap plugin and the related events
| protected mixed registerPlugin ( string $name ) | ||
| $name | string |
The name of the Bootstrap plugin |
protected function registerPlugin($name)
{
$view = $this->getView();
BootstrapPluginAsset::register($view);
$id = $this->options['id'];
if ($this->clientOptions !== false) {
$options = empty($this->clientOptions) ? '' : Json::htmlEncode($this->clientOptions);
$js = "jQuery('#$id').$name($options);";
$view->registerJs($js);
}
$this->registerClientEvents();
}
Normalizes dropdown item options by removing tab specific keys content and contentOptions, and also
configure panes accordingly.
| protected boolean renderDropdown ( string $itemNumber, array &$items, array &$panes ) | ||
| $itemNumber | string |
Number of the item |
| $items | array |
The dropdown items configuration. |
| $panes | array |
The panes reference array. |
| return | boolean |
Whether any of the dropdown items is |
|---|---|---|
| throws | \ |
|
protected function renderDropdown($itemNumber, &$items, &$panes)
{
$itemActive = false;
foreach ($items as $n => &$item) {
if (is_string($item)) {
continue;
}
if (isset($item['visible']) && !$item['visible']) {
continue;
}
if (!(array_key_exists('content', $item) xor array_key_exists('url', $item))) {
throw new InvalidConfigException("Either the 'content' or the 'url' option is required, but only one can be set.");
}
if (array_key_exists('url', $item)) {
continue;
}
$content = ArrayHelper::remove($item, 'content');
$options = ArrayHelper::remove($item, 'contentOptions', []);
Html::addCssClass($options, ['widget' => 'tab-pane']);
if (ArrayHelper::remove($item, 'active')) {
Html::addCssClass($options, 'active');
Html::addCssClass($item['options'], 'active');
$itemActive = true;
}
$options['id'] = ArrayHelper::getValue($options, 'id', $this->options['id'] . '-dd' . $itemNumber . '-tab' . $n);
$item['url'] = '#' . $options['id'];
if (!isset($item['linkOptions']['data-toggle'])) {
$item['linkOptions']['data-toggle'] = 'tab';
}
$panes[] = Html::tag('div', $content, $options);
unset($item);
}
return $itemActive;
}
Renders tab items as specified on $items.
| protected string renderItems ( ) | ||
| return | string |
The rendering result. |
|---|---|---|
| throws | \ |
|
protected function renderItems()
{
$headers = [];
$panes = [];
if (!$this->hasActiveTab()) {
$this->activateFirstVisibleTab();
}
foreach ($this->items as $n => $item) {
if (!ArrayHelper::remove($item, 'visible', true)) {
continue;
}
if (!array_key_exists('label', $item)) {
throw new InvalidConfigException("The 'label' option is required.");
}
$encodeLabel = isset($item['encode']) ? $item['encode'] : $this->encodeLabels;
$label = $encodeLabel ? Html::encode($item['label']) : $item['label'];
$headerOptions = array_merge($this->headerOptions, ArrayHelper::getValue($item, 'headerOptions', []));
$linkOptions = array_merge($this->linkOptions, ArrayHelper::getValue($item, 'linkOptions', []));
if (isset($item['items'])) {
$label .= ' <b class="caret"></b>';
Html::addCssClass($headerOptions, ['widget' => 'dropdown']);
if ($this->renderDropdown($n, $item['items'], $panes)) {
Html::addCssClass($headerOptions, 'active');
}
Html::addCssClass($linkOptions, ['widget' => 'dropdown-toggle']);
if (!isset($linkOptions['data-toggle'])) {
$linkOptions['data-toggle'] = 'dropdown';
}
/** @var Widget $dropdownClass */
$dropdownClass = $this->dropdownClass;
$header = Html::a($label, "#", $linkOptions) . "\n"
. $dropdownClass::widget(['items' => $item['items'], 'clientOptions' => false, 'view' => $this->getView()]);
} else {
$options = array_merge($this->itemOptions, ArrayHelper::getValue($item, 'options', []));
$options['id'] = ArrayHelper::getValue($options, 'id', $this->options['id'] . '-tab' . $n);
Html::addCssClass($options, ['widget' => 'tab-pane']);
if (ArrayHelper::remove($item, 'active')) {
Html::addCssClass($options, 'active');
Html::addCssClass($headerOptions, 'active');
}
if (isset($item['url'])) {
$header = Html::a($label, $item['url'], $linkOptions);
} else {
if (!isset($linkOptions['data-toggle'])) {
$linkOptions['data-toggle'] = 'tab';
}
$header = Html::a($label, '#' . $options['id'], $linkOptions);
}
if ($this->renderTabContent) {
$tag = ArrayHelper::remove($options, 'tag', 'div');
$panes[] = Html::tag($tag, isset($item['content']) ? $item['content'] : '', $options);
}
}
$headers[] = Html::tag('li', $header, $headerOptions);
}
$headersHtml = Html::tag('ul', implode("\n" , $headers), $this->options);
$panesHtml = $this->renderPanes($panes);
return strtr($this->template, [
'{headers}' => $headersHtml,
'{panes}' => $panesHtml,
]);
}
Renders tab panes.
| public string renderPanes ( array $panes ) | ||
| $panes | array | |
| return | string |
The rendering result. |
|---|---|---|
public function renderPanes($panes)
{
return $this->renderTabContent ? "\n" . Html::tag('div', implode("\n" , $panes), $this->tabContentOptions) : '';
}