Menu.php 11.3 KB
Newer Older
Qiang Xue committed
1 2 3 4 5 6 7 8 9
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\widgets;

10
use Yii;
Qiang Xue committed
11
use yii\base\Widget;
12
use yii\helpers\ArrayHelper;
13
use yii\helpers\Url;
Qiang Xue committed
14 15 16
use yii\helpers\Html;

/**
17
 * Menu displays a multi-level menu using nested HTML lists.
Qiang Xue committed
18
 *
19 20
 * The main property of Menu is [[items]], which specifies the possible items in the menu.
 * A menu item can contain sub-items which specify the sub-menu under that menu item.
21
 *
22 23
 * Menu checks the current route and request parameters to toggle certain menu items
 * with active state.
24
 *
25 26 27 28
 * Note that Menu only renders the HTML tags about the menu. It does do any styling.
 * You are responsible to provide CSS styles to make it look like a real menu.
 *
 * The following example shows how to use Menu:
29
 *
30
 * ~~~
Alexander Makarov committed
31 32
 * echo Menu::widget([
 *     'items' => [
33
 *         // Important: you need to specify url as 'controller/action',
34
 *         // not just as 'controller' even if default action is used.
Alexander Makarov committed
35
 *         ['label' => 'Home', 'url' => ['site/index']],
36
 *         // 'Products' menu item will be selected as long as the route is 'product/index'
Alexander Makarov committed
37
 *         ['label' => 'Products', 'url' => ['product/index'], 'items' => [
Alexander Makarov committed
38 39 40 41
 *             ['label' => 'New Arrivals', 'url' => ['product/index', 'tag' => 'new']],
 *             ['label' => 'Most Popular', 'url' => ['product/index', 'tag' => 'popular']],
 *         ]],
 *         ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest],
Alexander Makarov committed
42 43
 *     ],
 * ]);
44
 * ~~~
45
 *
Qiang Xue committed
46 47 48 49 50 51
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class Menu extends Widget
{
	/**
52 53 54 55
	 * @var array list of menu items. Each menu item should be an array of the following structure:
	 *
	 * - label: string, optional, specifies the menu item label. When [[encodeLabels]] is true, the label
	 *   will be HTML-encoded. If the label is not specified, an empty string will be used.
56
	 * - url: string or array, optional, specifies the URL of the menu item. It will be processed by [[Url::to]].
57 58 59 60 61 62 63 64 65 66 67
	 *   When this is set, the actual menu item content will be generated using [[linkTemplate]];
	 *   otherwise, [[labelTemplate]] will be used.
	 * - visible: boolean, optional, whether this menu item is visible. Defaults to true.
	 * - items: array, optional, specifies the sub-menu items. Its format is the same as the parent items.
	 * - active: boolean, optional, whether this menu item is in active state (currently selected).
	 *   If a menu item is active, its CSS class will be appended with [[activeCssClass]].
	 *   If this option is not set, the menu item will be set active automatically when the current request
	 *   is triggered by [[url]]. For more details, please refer to [[isItemActive()]].
	 * - template: string, optional, the template used to render the content of this menu item.
	 *   The token `{url}` will be replaced by the URL associated with this menu item,
	 *   and the token `{label}` will be replaced by the label of the menu item.
Qiang Xue committed
68 69
	 *   If this option is not set, [[linkTemplate]] or [[labelTemplate]] will be used instead.
	 * - options: array, optional, the HTML attributes for the menu container tag.
Qiang Xue committed
70
	 */
Alexander Makarov committed
71
	public $items = [];
72 73 74 75 76
	/**
	 * @var array list of HTML attributes for the menu container tag. This will be overwritten
	 * by the "options" set in individual [[items]]. The following special options are recognized:
	 *
	 * - tag: string, defaults to "li", the tag name of the item container tags.
77
	 *
78
	 * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
79
	 */
Alexander Makarov committed
80
	public $itemOptions = [];
Qiang Xue committed
81
	/**
82 83 84 85 86 87 88 89 90 91
	 * @var string the template used to render the body of a menu which is a link.
	 * In this template, the token `{url}` will be replaced with the corresponding link URL;
	 * while `{label}` will be replaced with the link text.
	 * This property will be overridden by the `template` option set in individual menu items via [[items]].
	 */
	public $linkTemplate = '<a href="{url}">{label}</a>';
	/**
	 * @var string the template used to render the body of a menu which is NOT a link.
	 * In this template, the token `{label}` will be replaced with the label of the menu item.
	 * This property will be overridden by the `template` option set in individual menu items via [[items]].
Qiang Xue committed
92
	 */
93
	public $labelTemplate = '{label}';
Qiang Xue committed
94
	/**
95 96
	 * @var string the template used to render a list of sub-menus.
	 * In this template, the token `{items}` will be replaced with the renderer sub-menu items.
Qiang Xue committed
97
	 */
98
	public $submenuTemplate = "\n<ul>\n{items}\n</ul>\n";
Qiang Xue committed
99
	/**
100 101 102 103 104
	 * @var boolean whether the labels for menu items should be HTML-encoded.
	 */
	public $encodeLabels = true;
	/**
	 * @var string the CSS class to be appended to the active menu item.
Qiang Xue committed
105 106 107 108
	 */
	public $activeCssClass = 'active';
	/**
	 * @var boolean whether to automatically activate items according to whether their route setting
109
	 * matches the currently requested route.
110
	 * @see isItemActive()
Qiang Xue committed
111 112 113 114
	 */
	public $activateItems = true;
	/**
	 * @var boolean whether to activate parent menu items when one of the corresponding child menu items is active.
115
	 * The activated parent menu items will also have its CSS classes appended with [[activeCssClass]].
Qiang Xue committed
116 117 118
	 */
	public $activateParents = false;
	/**
119 120
	 * @var boolean whether to hide empty menu items. An empty menu item is one whose `url` option is not
	 * set and which has no visible child menu items.
Qiang Xue committed
121 122 123
	 */
	public $hideEmptyItems = true;
	/**
124 125 126
	 * @var array the HTML attributes for the menu's container tag. The following special options are recognized:
	 *
	 * - tag: string, defaults to "ul", the tag name of the item container tags.
127
	 *
128
	 * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
Qiang Xue committed
129
	 */
Alexander Makarov committed
130
	public $options = [];
Qiang Xue committed
131 132 133 134 135 136 137 138 139 140 141
	/**
	 * @var string the CSS class that will be assigned to the first item in the main menu or each submenu.
	 * Defaults to null, meaning no such CSS class will be assigned.
	 */
	public $firstItemCssClass;
	/**
	 * @var string the CSS class that will be assigned to the last item in the main menu or each submenu.
	 * Defaults to null, meaning no such CSS class will be assigned.
	 */
	public $lastItemCssClass;
	/**
142
	 * @var string the route used to determine if a menu item is active or not.
143
	 * If not set, it will use the route of the current request.
144
	 * @see params
145
	 * @see isItemActive()
Qiang Xue committed
146
	 */
147
	public $route;
Qiang Xue committed
148
	/**
149 150 151
	 * @var array the parameters used to determine if a menu item is active or not.
	 * If not set, it will use `$_GET`.
	 * @see route
152
	 * @see isItemActive()
Qiang Xue committed
153
	 */
154 155
	public $params;

Qiang Xue committed
156 157

	/**
158
	 * Renders the menu.
Qiang Xue committed
159 160 161
	 */
	public function run()
	{
162 163 164 165
		if ($this->route === null && Yii::$app->controller !== null) {
			$this->route = Yii::$app->controller->getRoute();
		}
		if ($this->params === null) {
166
			$this->params = Yii::$app->request->getQueryParams();
Qiang Xue committed
167
		}
168
		$items = $this->normalizeItems($this->items, $hasActiveChild);
169 170 171
		$options = $this->options;
		$tag = ArrayHelper::remove($options, 'tag', 'ul');
		echo Html::tag($tag, $this->renderItems($items), $options);
Qiang Xue committed
172 173 174
	}

	/**
175
	 * Recursively renders the menu items (without the container tag).
Qiang Xue committed
176
	 * @param array $items the menu items to be rendered recursively
177
	 * @return string the rendering result
Qiang Xue committed
178 179 180 181
	 */
	protected function renderItems($items)
	{
		$n = count($items);
Alexander Makarov committed
182
		$lines = [];
183
		foreach ($items as $i => $item) {
Alexander Makarov committed
184
			$options = array_merge($this->itemOptions, ArrayHelper::getValue($item, 'options', []));
185
			$tag = ArrayHelper::remove($options, 'tag', 'li');
Alexander Makarov committed
186
			$class = [];
187
			if ($item['active']) {
Qiang Xue committed
188 189
				$class[] = $this->activeCssClass;
			}
190
			if ($i === 0 && $this->firstItemCssClass !== null) {
Qiang Xue committed
191 192
				$class[] = $this->firstItemCssClass;
			}
193
			if ($i === $n - 1 && $this->lastItemCssClass !== null) {
Qiang Xue committed
194 195
				$class[] = $this->lastItemCssClass;
			}
196
			if (!empty($class)) {
Qiang Xue committed
197 198 199 200 201 202 203 204
				if (empty($options['class'])) {
					$options['class'] = implode(' ', $class);
				} else {
					$options['class'] .= ' ' . implode(' ', $class);
				}
			}

			$menu = $this->renderItem($item);
205
			if (!empty($item['items'])) {
Alexander Makarov committed
206
				$menu .= strtr($this->submenuTemplate, [
207
					'{items}' => $this->renderItems($item['items']),
Alexander Makarov committed
208
				]);
Qiang Xue committed
209
			}
210
			$lines[] = Html::tag($tag, $menu, $options);
Qiang Xue committed
211
		}
212
		return implode("\n", $lines);
Qiang Xue committed
213 214 215 216 217
	}

	/**
	 * Renders the content of a menu item.
	 * Note that the container and the sub-menus are not rendered here.
218 219
	 * @param array $item the menu item to be rendered. Please refer to [[items]] to see what data might be in the item.
	 * @return string the rendering result
Qiang Xue committed
220 221 222 223
	 */
	protected function renderItem($item)
	{
		if (isset($item['url'])) {
224
			$template = ArrayHelper::getValue($item, 'template', $this->linkTemplate);
Alexander Makarov committed
225
			return strtr($template, [
226
				'{url}' => Url::to($item['url']),
227
				'{label}' => $item['label'],
Alexander Makarov committed
228
			]);
Qiang Xue committed
229
		} else {
230
			$template = ArrayHelper::getValue($item, 'template', $this->labelTemplate);
Alexander Makarov committed
231
			return strtr($template, [
232
				'{label}' => $item['label'],
Alexander Makarov committed
233
			]);
Qiang Xue committed
234 235 236 237
		}
	}

	/**
238
	 * Normalizes the [[items]] property to remove invisible items and activate certain items.
Qiang Xue committed
239 240 241 242
	 * @param array $items the items to be normalized.
	 * @param boolean $active whether there is an active child menu item.
	 * @return array the normalized menu items
	 */
243
	protected function normalizeItems($items, &$active)
Qiang Xue committed
244 245 246 247 248 249 250 251 252
	{
		foreach ($items as $i => $item) {
			if (isset($item['visible']) && !$item['visible']) {
				unset($items[$i]);
				continue;
			}
			if (!isset($item['label'])) {
				$item['label'] = '';
			}
253
			if ($this->encodeLabels) {
Qiang Xue committed
254 255 256 257
				$items[$i]['label'] = Html::encode($item['label']);
			}
			$hasActiveChild = false;
			if (isset($item['items'])) {
yiidevelop committed
258
				$items[$i]['items'] = $this->normalizeItems($item['items'], $hasActiveChild);
Qiang Xue committed
259 260 261 262 263 264 265 266 267
				if (empty($items[$i]['items']) && $this->hideEmptyItems) {
					unset($items[$i]['items']);
					if (!isset($item['url'])) {
						unset($items[$i]);
						continue;
					}
				}
			}
			if (!isset($item['active'])) {
268
				if ($this->activateParents && $hasActiveChild || $this->activateItems && $this->isItemActive($item)) {
Qiang Xue committed
269 270 271 272 273 274 275 276 277 278 279 280 281
					$active = $items[$i]['active'] = true;
				} else {
					$items[$i]['active'] = false;
				}
			} elseif ($item['active']) {
				$active = true;
			}
		}
		return array_values($items);
	}

	/**
	 * Checks whether a menu item is active.
282 283 284 285 286
	 * This is done by checking if [[route]] and [[params]] match that specified in the `url` option of the menu item.
	 * When the `url` option of a menu item is specified in terms of an array, its first element is treated
	 * as the route for the item and the rest of the elements are the associated parameters.
	 * Only when its route and parameters match [[route]] and [[params]], respectively, will a menu item
	 * be considered active.
Qiang Xue committed
287 288 289
	 * @param array $item the menu item to be checked
	 * @return boolean whether the menu item is active
	 */
290
	protected function isItemActive($item)
Qiang Xue committed
291
	{
292 293 294 295 296 297 298 299
		if (isset($item['url']) && is_array($item['url']) && isset($item['url'][0])) {
			$route = $item['url'][0];
			if ($route[0] !== '/' && Yii::$app->controller) {
				$route = Yii::$app->controller->module->getUniqueId() . '/' . $route;
			}
			if (ltrim($route, '/') !== $this->route) {
				return false;
			}
Qiang Xue committed
300 301 302
			unset($item['url']['#']);
			if (count($item['url']) > 1) {
				foreach (array_splice($item['url'], 1) as $name => $value) {
Qiang Xue committed
303
					if ($value !== null && (!isset($this->params[$name]) || $this->params[$name] != $value)) {
Qiang Xue committed
304 305 306 307 308 309 310 311 312
						return false;
					}
				}
			}
			return true;
		}
		return false;
	}
}