Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.

333 lines
14KB

  1. <?php
  2. /**
  3. * @link http://www.yiiframework.com/
  4. * @copyright Copyright (c) 2008 Yii Software LLC
  5. * @license http://www.yiiframework.com/license/
  6. */
  7. namespace yii\widgets;
  8. use Yii;
  9. use yii\base\Widget;
  10. use yii\helpers\ArrayHelper;
  11. use yii\helpers\Url;
  12. use yii\helpers\Html;
  13. /**
  14. * Menu displays a multi-level menu using nested HTML lists.
  15. *
  16. * The main property of Menu is [[items]], which specifies the possible items in the menu.
  17. * A menu item can contain sub-items which specify the sub-menu under that menu item.
  18. *
  19. * Menu checks the current route and request parameters to toggle certain menu items
  20. * with active state.
  21. *
  22. * Note that Menu only renders the HTML tags about the menu. It does do any styling.
  23. * You are responsible to provide CSS styles to make it look like a real menu.
  24. *
  25. * The following example shows how to use Menu:
  26. *
  27. * ```php
  28. * echo Menu::widget([
  29. * 'items' => [
  30. * // Important: you need to specify url as 'controller/action',
  31. * // not just as 'controller' even if default action is used.
  32. * ['label' => 'Home', 'url' => ['site/index']],
  33. * // 'Products' menu item will be selected as long as the route is 'product/index'
  34. * ['label' => 'Products', 'url' => ['product/index'], 'items' => [
  35. * ['label' => 'New Arrivals', 'url' => ['product/index', 'tag' => 'new']],
  36. * ['label' => 'Most Popular', 'url' => ['product/index', 'tag' => 'popular']],
  37. * ]],
  38. * ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest],
  39. * ],
  40. * ]);
  41. * ```
  42. *
  43. * @author Qiang Xue <qiang.xue@gmail.com>
  44. * @since 2.0
  45. */
  46. class Menu extends Widget
  47. {
  48. /**
  49. * @var array list of menu items. Each menu item should be an array of the following structure:
  50. *
  51. * - label: string, optional, specifies the menu item label. When [[encodeLabels]] is true, the label
  52. * will be HTML-encoded. If the label is not specified, an empty string will be used.
  53. * - encode: boolean, optional, whether this item`s label should be HTML-encoded. This param will override
  54. * global [[encodeLabels]] param.
  55. * - url: string or array, optional, specifies the URL of the menu item. It will be processed by [[Url::to]].
  56. * When this is set, the actual menu item content will be generated using [[linkTemplate]];
  57. * otherwise, [[labelTemplate]] will be used.
  58. * - visible: boolean, optional, whether this menu item is visible. Defaults to true.
  59. * - items: array, optional, specifies the sub-menu items. Its format is the same as the parent items.
  60. * - active: boolean, optional, whether this menu item is in active state (currently selected).
  61. * If a menu item is active, its CSS class will be appended with [[activeCssClass]].
  62. * If this option is not set, the menu item will be set active automatically when the current request
  63. * is triggered by `url`. For more details, please refer to [[isItemActive()]].
  64. * - template: string, optional, the template used to render the content of this menu item.
  65. * The token `{url}` will be replaced by the URL associated with this menu item,
  66. * and the token `{label}` will be replaced by the label of the menu item.
  67. * If this option is not set, [[linkTemplate]] or [[labelTemplate]] will be used instead.
  68. * - submenuTemplate: string, optional, the template used to render the list of sub-menus.
  69. * The token `{items}` will be replaced with the rendered sub-menu items.
  70. * If this option is not set, [[submenuTemplate]] will be used instead.
  71. * - options: array, optional, the HTML attributes for the menu container tag.
  72. */
  73. public $items = [];
  74. /**
  75. * @var array list of HTML attributes shared by all menu [[items]]. If any individual menu item
  76. * specifies its `options`, it will be merged with this property before being used to generate the HTML
  77. * attributes for the menu item tag. The following special options are recognized:
  78. *
  79. * - tag: string, defaults to "li", the tag name of the item container tags.
  80. * Set to false to disable container tag.
  81. * See also [[\yii\helpers\Html::tag()]].
  82. *
  83. * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
  84. */
  85. public $itemOptions = [];
  86. /**
  87. * @var string the template used to render the body of a menu which is a link.
  88. * In this template, the token `{url}` will be replaced with the corresponding link URL;
  89. * while `{label}` will be replaced with the link text.
  90. * This property will be overridden by the `template` option set in individual menu items via [[items]].
  91. */
  92. public $linkTemplate = '<a href="{url}">{label}</a>';
  93. /**
  94. * @var string the template used to render the body of a menu which is NOT a link.
  95. * In this template, the token `{label}` will be replaced with the label of the menu item.
  96. * This property will be overridden by the `template` option set in individual menu items via [[items]].
  97. */
  98. public $labelTemplate = '{label}';
  99. /**
  100. * @var string the template used to render a list of sub-menus.
  101. * In this template, the token `{items}` will be replaced with the rendered sub-menu items.
  102. */
  103. public $submenuTemplate = "\n<ul>\n{items}\n</ul>\n";
  104. /**
  105. * @var boolean whether the labels for menu items should be HTML-encoded.
  106. */
  107. public $encodeLabels = true;
  108. /**
  109. * @var string the CSS class to be appended to the active menu item.
  110. */
  111. public $activeCssClass = 'active';
  112. /**
  113. * @var boolean whether to automatically activate items according to whether their route setting
  114. * matches the currently requested route.
  115. * @see isItemActive()
  116. */
  117. public $activateItems = true;
  118. /**
  119. * @var boolean whether to activate parent menu items when one of the corresponding child menu items is active.
  120. * The activated parent menu items will also have its CSS classes appended with [[activeCssClass]].
  121. */
  122. public $activateParents = false;
  123. /**
  124. * @var boolean whether to hide empty menu items. An empty menu item is one whose `url` option is not
  125. * set and which has no visible child menu items.
  126. */
  127. public $hideEmptyItems = true;
  128. /**
  129. * @var array the HTML attributes for the menu's container tag. The following special options are recognized:
  130. *
  131. * - tag: string, defaults to "ul", the tag name of the item container tags. Set to false to disable container tag.
  132. * See also [[\yii\helpers\Html::tag()]].
  133. *
  134. * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
  135. */
  136. public $options = [];
  137. /**
  138. * @var string the CSS class that will be assigned to the first item in the main menu or each submenu.
  139. * Defaults to null, meaning no such CSS class will be assigned.
  140. */
  141. public $firstItemCssClass;
  142. /**
  143. * @var string the CSS class that will be assigned to the last item in the main menu or each submenu.
  144. * Defaults to null, meaning no such CSS class will be assigned.
  145. */
  146. public $lastItemCssClass;
  147. /**
  148. * @var string the route used to determine if a menu item is active or not.
  149. * If not set, it will use the route of the current request.
  150. * @see params
  151. * @see isItemActive()
  152. */
  153. public $route;
  154. /**
  155. * @var array the parameters used to determine if a menu item is active or not.
  156. * If not set, it will use `$_GET`.
  157. * @see route
  158. * @see isItemActive()
  159. */
  160. public $params;
  161. /**
  162. * Renders the menu.
  163. */
  164. public function run()
  165. {
  166. if ($this->route === null && Yii::$app->controller !== null) {
  167. $this->route = Yii::$app->controller->getRoute();
  168. }
  169. if ($this->params === null) {
  170. $this->params = Yii::$app->request->getQueryParams();
  171. }
  172. $items = $this->normalizeItems($this->items, $hasActiveChild);
  173. if (!empty($items)) {
  174. $options = $this->options;
  175. $tag = ArrayHelper::remove($options, 'tag', 'ul');
  176. echo Html::tag($tag, $this->renderItems($items), $options);
  177. }
  178. }
  179. /**
  180. * Recursively renders the menu items (without the container tag).
  181. * @param array $items the menu items to be rendered recursively
  182. * @return string the rendering result
  183. */
  184. protected function renderItems($items)
  185. {
  186. $n = count($items);
  187. $lines = [];
  188. foreach ($items as $i => $item) {
  189. $options = array_merge($this->itemOptions, ArrayHelper::getValue($item, 'options', []));
  190. $tag = ArrayHelper::remove($options, 'tag', 'li');
  191. $class = [];
  192. if ($item['active']) {
  193. $class[] = $this->activeCssClass;
  194. }
  195. if ($i === 0 && $this->firstItemCssClass !== null) {
  196. $class[] = $this->firstItemCssClass;
  197. }
  198. if ($i === $n - 1 && $this->lastItemCssClass !== null) {
  199. $class[] = $this->lastItemCssClass;
  200. }
  201. if (!empty($class)) {
  202. if (empty($options['class'])) {
  203. $options['class'] = implode(' ', $class);
  204. } else {
  205. $options['class'] .= ' ' . implode(' ', $class);
  206. }
  207. }
  208. $menu = $this->renderItem($item);
  209. if (!empty($item['items'])) {
  210. $submenuTemplate = ArrayHelper::getValue($item, 'submenuTemplate', $this->submenuTemplate);
  211. $menu .= strtr($submenuTemplate, [
  212. '{items}' => $this->renderItems($item['items']),
  213. ]);
  214. }
  215. $lines[] = Html::tag($tag, $menu, $options);
  216. }
  217. return implode("\n", $lines);
  218. }
  219. /**
  220. * Renders the content of a menu item.
  221. * Note that the container and the sub-menus are not rendered here.
  222. * @param array $item the menu item to be rendered. Please refer to [[items]] to see what data might be in the item.
  223. * @return string the rendering result
  224. */
  225. protected function renderItem($item)
  226. {
  227. if (isset($item['url'])) {
  228. $template = ArrayHelper::getValue($item, 'template', $this->linkTemplate);
  229. return strtr($template, [
  230. '{url}' => Html::encode(Url::to($item['url'])),
  231. '{label}' => $item['label'],
  232. ]);
  233. } else {
  234. $template = ArrayHelper::getValue($item, 'template', $this->labelTemplate);
  235. return strtr($template, [
  236. '{label}' => $item['label'],
  237. ]);
  238. }
  239. }
  240. /**
  241. * Normalizes the [[items]] property to remove invisible items and activate certain items.
  242. * @param array $items the items to be normalized.
  243. * @param boolean $active whether there is an active child menu item.
  244. * @return array the normalized menu items
  245. */
  246. protected function normalizeItems($items, &$active)
  247. {
  248. foreach ($items as $i => $item) {
  249. if (isset($item['visible']) && !$item['visible']) {
  250. unset($items[$i]);
  251. continue;
  252. }
  253. if (!isset($item['label'])) {
  254. $item['label'] = '';
  255. }
  256. $encodeLabel = isset($item['encode']) ? $item['encode'] : $this->encodeLabels;
  257. $items[$i]['label'] = $encodeLabel ? Html::encode($item['label']) : $item['label'];
  258. $hasActiveChild = false;
  259. if (isset($item['items'])) {
  260. $items[$i]['items'] = $this->normalizeItems($item['items'], $hasActiveChild);
  261. if (empty($items[$i]['items']) && $this->hideEmptyItems) {
  262. unset($items[$i]['items']);
  263. if (!isset($item['url'])) {
  264. unset($items[$i]);
  265. continue;
  266. }
  267. }
  268. }
  269. if (!isset($item['active'])) {
  270. if ($this->activateParents && $hasActiveChild || $this->activateItems && $this->isItemActive($item)) {
  271. $active = $items[$i]['active'] = true;
  272. } else {
  273. $items[$i]['active'] = false;
  274. }
  275. } elseif ($item['active']) {
  276. $active = true;
  277. }
  278. }
  279. return array_values($items);
  280. }
  281. /**
  282. * Checks whether a menu item is active.
  283. * This is done by checking if [[route]] and [[params]] match that specified in the `url` option of the menu item.
  284. * When the `url` option of a menu item is specified in terms of an array, its first element is treated
  285. * as the route for the item and the rest of the elements are the associated parameters.
  286. * Only when its route and parameters match [[route]] and [[params]], respectively, will a menu item
  287. * be considered active.
  288. * @param array $item the menu item to be checked
  289. * @return boolean whether the menu item is active
  290. */
  291. protected function isItemActive($item)
  292. {
  293. if (isset($item['url']) && is_array($item['url']) && isset($item['url'][0])) {
  294. $route = Yii::getAlias($item['url'][0]);
  295. if ($route[0] !== '/' && Yii::$app->controller) {
  296. $route = Yii::$app->controller->module->getUniqueId() . '/' . $route;
  297. }
  298. if (ltrim($route, '/') !== $this->route) {
  299. return false;
  300. }
  301. unset($item['url']['#']);
  302. if (count($item['url']) > 1) {
  303. $params = $item['url'];
  304. unset($params[0]);
  305. foreach ($params as $name => $value) {
  306. if ($value !== null && (!isset($this->params[$name]) || $this->params[$name] != $value)) {
  307. return false;
  308. }
  309. }
  310. }
  311. return true;
  312. }
  313. return false;
  314. }
  315. }