Merge pull request #415 from creocoder/jui-tabs-rework

framework/yii/jui/Tabs.php

@@ -20,15 +20,42 @@ use yii\helpers\Html;
  * echo Tabs::widget(array(
  *     'items' => array(
  *         array(
- *             'header' => 'One',
+ *             'label' => 'Tab one',
  *             'content' => 'Mauris mauris ante, blandit et, ultrices a, suscipit eget...',
  *         ),
  *         array(
- *             'header' => 'Two',
- *             'headerOptions' => array(...),
+ *             'label' => 'Tab two',
  *             'content' => 'Sed non urna. Phasellus eu ligula. Vestibulum sit amet purus...',
- *             'options' => array(...),
+ *             'options' => array(
+ *                 'tag' => 'div',
+ *             ),
+ *             'headerOptions' => array(
+ *                 'class' => 'my-class',
+ *             ),
  *         ),
+ *         array(
+ *             'label' => 'Tab with custom id',
+ *             'content' => 'Morbi tincidunt, dui sit amet facilisis feugiat...',
+ *             'options' => array(
+ *                'id' => 'my-tab',
+ *             ),
+ *         ),
+ *         array(
+ *             'label' => 'Ajax tab',
+ *             'url' => array('ajax/content'),
+ *         ),
+ *     ),
+ *     'options' => array(
+ *         'tag' => 'div',
+ *     ),
+ *     'itemOptions' => array(
+ *         'tag' => 'div',
+ *     ),
+ *     'headerOptions' => array(
+ *         'class' => 'my-class',
+ *     ),
+ *     'clientOptions' => array(
+ *         'collapsible' => false,
  *     ),
  * ));
  * ```
@@ -40,23 +67,44 @@ use yii\helpers\Html;
 class Tabs extends Widget
 {
 	/**
-	 * @var array list of tabs in the tabs widget. Each array element represents a single
-	 * tab with the following structure:
+	 * @var array the HTML attributes for the widget container tag. The following special options are recognized:
 	 *
-	 * ```php
-	 * array(
-	 *     // required, the header (HTML) of the tab
-	 *     'header' => 'Tab label',
-	 *     // required, the content (HTML) of the tab
-	 *     'content' => 'Mauris mauris ante, blandit et, ultrices a, suscipit eget...',
-	 *     // optional the HTML attributes of the tab content container
-	 *     'options'=> array(...),
-	 *     // optional the HTML attributes of the tab header container
-	 *     'headerOptions'=> array(...),
-	 * )
-	 * ```
+	 * - tag: string, defaults to "div", the tag name of the container tag of this widget
+	 */
+	public $options = array();
+	/**
+	 * @var array list of tab items. Each item can be an array of the following structure:
+	 *
+	 * - label: string, required, specifies the header link label. When [[encodeLabels]] is true, the label
+	 *   will be HTML-encoded.
+	 * - content: string, the content to show when corresponding tab is clicked. Can be omitted if url is specified.
+	 * - url: mixed, mixed, optional, the url to load tab contents via AJAX. It is required if no content is specified.
+	 * - template: string, optional, the header link template to render the header link. If none specified
+	 * [[linkTemplate]] will be used instead.
+	 * - options: array, optional, the HTML attributes of the header.
+	 * - headerOptions: array, optional, the HTML attributes for the header container tag.
 	 */
 	public $items = array();
+	/**
+	 * @var array 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.
+	 */
+	public $itemOptions = array();
+	/**
+	 * @var array list of HTML attributes for the header container tags. This will be overwritten
+	 * by the "headerOptions" set in individual [[items]].
+	 */
+	public $headerOptions = array();
+	/**
+	 * @var string the default header template to render the link.
+	 */
+	public $linkTemplate = '<a href="{url}">{label}</a>';
+	/**
+	 * @var boolean whether the labels for header items should be HTML-encoded.
+	 */
+	public $encodeLabels = true;
 
 
 	/**
@@ -64,53 +112,48 @@ class Tabs extends Widget
 	 */
 	public function run()
 	{
-		echo Html::beginTag('div', $this->options) . "\n";
-		echo $this->renderHeaders() . "\n";
-		echo $this->renderContents() . "\n";
-		echo Html::endTag('div') . "\n";
+		$options = $this->options;
+		$tag = ArrayHelper::remove($options, 'tag', 'div');
+		echo Html::beginTag($tag, $options) . "\n";
+		echo $this->renderItems() . "\n";
+		echo Html::endTag($tag) . "\n";
 		$this->registerWidget('tabs');
 	}
 
 	/**
-	 * Renders tabs headers as specified on [[items]].
+	 * Renders tab items as specified on [[items]].
 	 * @return string the rendering result.
 	 * @throws InvalidConfigException.
 	 */
-	protected function renderHeaders()
+	protected function renderItems()
 	{
 		$headers = array();
+		$items = array();
 		foreach ($this->items as $n => $item) {
-			if (!isset($item['header'])) {
-				throw new InvalidConfigException("The 'header' option is required.");
-			}
-			$options = ArrayHelper::getValue($item, 'options', array());
-			$id = isset($options['id']) ? $options['id'] : $this->options['id'] . '-tab' . $n;
-			$headerOptions = ArrayHelper::getValue($item, 'headerOptions', array());
-			$headers[] = Html::tag('li', Html::a($item['header'], "#$id"), $headerOptions);
-		}
-
-		return Html::tag('ul', implode("\n", $headers));
-	}
-
-	/**
-	 * Renders tabs contents as specified on [[items]].
-	 * @return string the rendering result.
-	 * @throws InvalidConfigException.
-	 */
-	protected function renderContents()
-	{
-		$contents = array();
-		foreach ($this->items as $n => $item) {
-			if (!isset($item['content'])) {
-				throw new InvalidConfigException("The 'content' option is required.");
+			if (!isset($item['label'])) {
+				throw new InvalidConfigException("The 'label' option is required.");
 			}
-			$options = ArrayHelper::getValue($item, 'options', array());
-			if (!isset($options['id'])) {
-				$options['id'] = $this->options['id'] . '-tab' . $n;
+			if (isset($item['url'])) {
+				$url = Html::url($item['url']);
+			} else {
+				if (!isset($item['content'])) {
+					throw new InvalidConfigException("The 'content' or 'url' option is required.");
+				}
+				$options = array_merge($this->itemOptions, ArrayHelper::getValue($item, 'options', array()));
+				$tag = ArrayHelper::remove($options, 'tag', 'div');
+				if (!isset($options['id'])) {
+					$options['id'] = $this->options['id'] . '-tab' . $n;
+				}
+				$url = '#' . $options['id'];
+				$items[] = Html::tag($tag, $item['content'], $options);
 			}
-			$contents[] = Html::tag('div', $item['content'], $options);
+			$headerOptions = array_merge($this->headerOptions, ArrayHelper::getValue($item, 'headerOptions', array()));
+			$template = ArrayHelper::getValue($item, 'template', $this->linkTemplate);
+			$headers[] = Html::tag('li', strtr($template, array(
+				'{label}' => $this->encodeLabels ? Html::encode($item['label']) : $item['label'],
+				'{url}' => $url,
+			)), $headerOptions);
 		}
-
-		return implode("\n", $contents);
+		return Html::tag('ul', implode("\n", $headers)) . "\n" . implode("\n", $items);
 	}
 }