1: <?php
2: /**
3: * CMenu class file.
4: *
5: * @author Jonah Turnquist <poppitypop@gmail.com>
6: * @author Qiang Xue <qiang.xue@gmail.com>
7: * @link http://www.yiiframework.com/
8: * @copyright 2008-2013 Yii Software LLC
9: * @license http://www.yiiframework.com/license/
10: */
11:
12: /**
13: * CMenu displays a multi-level menu using nested HTML lists.
14: *
15: * The main property of CMenu is {@link items}, which specifies the possible items in the menu.
16: * A menu item has three main properties: visible, active and items. The "visible" property
17: * specifies whether the menu item is currently visible. The "active" property specifies whether
18: * the menu item is currently selected. And the "items" property specifies the child menu items.
19: *
20: * The following example shows how to use CMenu:
21: * <pre>
22: * $this->widget('zii.widgets.CMenu', array(
23: * 'items'=>array(
24: * // Important: you need to specify url as 'controller/action',
25: * // not just as 'controller' even if default action is used.
26: * array('label'=>'Home', 'url'=>array('site/index')),
27: * // 'Products' menu item will be selected no matter which tag parameter value is since it's not specified.
28: * array('label'=>'Products', 'url'=>array('product/index'), 'items'=>array(
29: * array('label'=>'New Arrivals', 'url'=>array('product/new', 'tag'=>'new')),
30: * array('label'=>'Most Popular', 'url'=>array('product/index', 'tag'=>'popular')),
31: * )),
32: * array('label'=>'Login', 'url'=>array('site/login'), 'visible'=>Yii::app()->user->isGuest),
33: * ),
34: * ));
35: * </pre>
36: *
37: *
38: * @author Jonah Turnquist <poppitypop@gmail.com>
39: * @author Qiang Xue <qiang.xue@gmail.com>
40: * @package zii.widgets
41: * @since 1.1
42: */
43: class CMenu extends CWidget
44: {
45: /**
46: * @var array list of menu items. Each menu item is specified as an array of name-value pairs.
47: * Possible option names include the following:
48: * <ul>
49: * <li>label: string, optional, specifies the menu item label. When {@link encodeLabel} or own encodeLabel option is true, the label
50: * will be HTML-encoded. If the label is not specified, it defaults to an empty string.</li>
51: * <li>encodeLabel: boolean whether the label for menu item should be HTML-encoded.
52: * When this option is set, it will override the global setting {@link encodeLabel}. This option has been available since version 1.1.15.</li>
53: * <li>url: string or array, optional, specifies the URL of the menu item. It is passed to {@link CHtml::normalizeUrl}
54: * to generate a valid URL. If this is not set, the menu item will be rendered as a span text.</li>
55: * <li>visible: boolean, optional, whether this menu item is visible. Defaults to true.
56: * This can be used to control the visibility of menu items based on user permissions.</li>
57: * <li>items: array, optional, specifies the sub-menu items. Its format is the same as the parent items.</li>
58: * <li>active: boolean, optional, whether this menu item is in active state (currently selected).
59: * If a menu item is active and {@link activeClass} is not empty, its CSS class will be appended with {@link activeClass}.
60: * If this option is not set, the menu item will be set active automatically when the current request
61: * is triggered by {@link url}. Note that the GET parameters not specified in the 'url' option will be ignored.</li>
62: * <li>template: string, optional, the template used to render this menu item.
63: * When this option is set, it will override the global setting {@link itemTemplate}.
64: * Please see {@link itemTemplate} for more details. This option has been available since version 1.1.1.</li>
65: * <li>linkOptions: array, optional, additional HTML attributes to be rendered for the link or span tag of the menu item.</li>
66: * <li>itemOptions: array, optional, additional HTML attributes to be rendered for the container tag of the menu item.</li>
67: * <li>submenuOptions: array, optional, additional HTML attributes to be rendered for the container of the submenu if this menu item has one.
68: * When this option is set, the {@link submenuHtmlOptions} property will be ignored for this particular submenu.
69: * This option has been available since version 1.1.6.</li>
70: * </ul>
71: */
72: public $items=array();
73: /**
74: * @var string the template used to render an individual menu item. In this template,
75: * the token "{menu}" will be replaced with the corresponding menu link or text.
76: * If this property is not set, each menu will be rendered without any decoration.
77: * This property will be overridden by the 'template' option set in individual menu items via {@items}.
78: * @since 1.1.1
79: */
80: public $itemTemplate;
81: /**
82: * @var boolean whether the labels for menu items should be HTML-encoded. Defaults to true.
83: */
84: public $encodeLabel=true;
85: /**
86: * @var string the CSS class to be appended to the active menu item. Defaults to 'active'.
87: * If empty, the CSS class of menu items will not be changed.
88: */
89: public $activeCssClass='active';
90: /**
91: * @var boolean whether to automatically activate items according to whether their route setting
92: * matches the currently requested route. Defaults to true.
93: * @since 1.1.3
94: */
95: public $activateItems=true;
96: /**
97: * @var boolean whether to activate parent menu items when one of the corresponding child menu items is active.
98: * The activated parent menu items will also have its CSS classes appended with {@link activeCssClass}.
99: * Defaults to false.
100: */
101: public $activateParents=false;
102: /**
103: * @var boolean whether to hide empty menu items. An empty menu item is one whose 'url' option is not
104: * set and which doesn't contain visible child menu items. Defaults to true.
105: */
106: public $hideEmptyItems=true;
107: /**
108: * @var array HTML attributes for the menu's root container tag
109: */
110: public $htmlOptions=array();
111: /**
112: * @var array HTML attributes for the submenu's container tag.
113: */
114: public $submenuHtmlOptions=array();
115: /**
116: * @var string the HTML element name that will be used to wrap the label of all menu links.
117: * For example, if this property is set as 'span', a menu item may be rendered as
118: * <li><a href="url"><span>label</span></a></li>
119: * This is useful when implementing menu items using the sliding window technique.
120: * Defaults to null, meaning no wrapper tag will be generated.
121: * @since 1.1.4
122: */
123: public $linkLabelWrapper;
124: /**
125: * @var array HTML attributes for the links' wrap element specified in
126: * {@link linkLabelWrapper}.
127: * @since 1.1.13
128: */
129: public $linkLabelWrapperHtmlOptions=array();
130: /**
131: * @var string the CSS class that will be assigned to the first item in the main menu or each submenu.
132: * Defaults to null, meaning no such CSS class will be assigned.
133: * @since 1.1.4
134: */
135: public $firstItemCssClass;
136: /**
137: * @var string the CSS class that will be assigned to the last item in the main menu or each submenu.
138: * Defaults to null, meaning no such CSS class will be assigned.
139: * @since 1.1.4
140: */
141: public $lastItemCssClass;
142: /**
143: * @var string the CSS class that will be assigned to every item.
144: * Defaults to null, meaning no such CSS class will be assigned.
145: * @since 1.1.9
146: */
147: public $itemCssClass;
148:
149: /**
150: * Initializes the menu widget.
151: * This method mainly normalizes the {@link items} property.
152: * If this method is overridden, make sure the parent implementation is invoked.
153: */
154: public function init()
155: {
156: if(isset($this->htmlOptions['id']))
157: $this->id=$this->htmlOptions['id'];
158: else
159: $this->htmlOptions['id']=$this->id;
160: $route=$this->getController()->getRoute();
161: $this->items=$this->normalizeItems($this->items,$route,$hasActiveChild);
162: }
163:
164: /**
165: * Calls {@link renderMenu} to render the menu.
166: */
167: public function run()
168: {
169: $this->renderMenu($this->items);
170: }
171:
172: /**
173: * Renders the menu items.
174: * @param array $items menu items. Each menu item will be an array with at least two elements: 'label' and 'active'.
175: * It may have three other optional elements: 'items', 'linkOptions' and 'itemOptions'.
176: */
177: protected function renderMenu($items)
178: {
179: if(count($items))
180: {
181: echo CHtml::openTag('ul',$this->htmlOptions)."\n";
182: $this->renderMenuRecursive($items);
183: echo CHtml::closeTag('ul');
184: }
185: }
186:
187: /**
188: * Recursively renders the menu items.
189: * @param array $items the menu items to be rendered recursively
190: */
191: protected function renderMenuRecursive($items)
192: {
193: $count=0;
194: $n=count($items);
195: foreach($items as $item)
196: {
197: $count++;
198: $options=isset($item['itemOptions']) ? $item['itemOptions'] : array();
199: $class=array();
200: if($item['active'] && $this->activeCssClass!='')
201: $class[]=$this->activeCssClass;
202: if($count===1 && $this->firstItemCssClass!==null)
203: $class[]=$this->firstItemCssClass;
204: if($count===$n && $this->lastItemCssClass!==null)
205: $class[]=$this->lastItemCssClass;
206: if($this->itemCssClass!==null)
207: $class[]=$this->itemCssClass;
208: if($class!==array())
209: {
210: if(empty($options['class']))
211: $options['class']=implode(' ',$class);
212: else
213: $options['class'].=' '.implode(' ',$class);
214: }
215:
216: echo CHtml::openTag('li', $options);
217:
218: $menu=$this->renderMenuItem($item);
219: if(isset($this->itemTemplate) || isset($item['template']))
220: {
221: $template=isset($item['template']) ? $item['template'] : $this->itemTemplate;
222: echo strtr($template,array('{menu}'=>$menu));
223: }
224: else
225: echo $menu;
226:
227: if(isset($item['items']) && count($item['items']))
228: {
229: echo "\n".CHtml::openTag('ul',isset($item['submenuOptions']) ? $item['submenuOptions'] : $this->submenuHtmlOptions)."\n";
230: $this->renderMenuRecursive($item['items']);
231: echo CHtml::closeTag('ul')."\n";
232: }
233:
234: echo CHtml::closeTag('li')."\n";
235: }
236: }
237:
238: /**
239: * Renders the content of a menu item.
240: * Note that the container and the sub-menus are not rendered here.
241: * @param array $item the menu item to be rendered. Please see {@link items} on what data might be in the item.
242: * @return string
243: * @since 1.1.6
244: */
245: protected function renderMenuItem($item)
246: {
247: if(isset($item['url']))
248: {
249: $label=$this->linkLabelWrapper===null ? $item['label'] : CHtml::tag($this->linkLabelWrapper, $this->linkLabelWrapperHtmlOptions, $item['label']);
250: return CHtml::link($label,$item['url'],isset($item['linkOptions']) ? $item['linkOptions'] : array());
251: }
252: else
253: return CHtml::tag('span',isset($item['linkOptions']) ? $item['linkOptions'] : array(), $item['label']);
254: }
255:
256: /**
257: * Normalizes the {@link items} property so that the 'active' state is properly identified for every menu item.
258: * @param array $items the items to be normalized.
259: * @param string $route the route of the current request.
260: * @param boolean $active whether there is an active child menu item.
261: * @return array the normalized menu items
262: */
263: protected function normalizeItems($items,$route,&$active)
264: {
265: foreach($items as $i=>$item)
266: {
267: if(isset($item['visible']) && !$item['visible'])
268: {
269: unset($items[$i]);
270: continue;
271: }
272: if(!isset($item['label']))
273: $item['label']='';
274: $encodeLabel = isset($item['encodeLabel']) ? $item['encodeLabel'] : $this->encodeLabel;
275: if($encodeLabel)
276: $items[$i]['label']=CHtml::encode($item['label']);
277: $hasActiveChild=false;
278: if(isset($item['items']))
279: {
280: $items[$i]['items']=$this->normalizeItems($item['items'],$route,$hasActiveChild);
281: if(empty($items[$i]['items']) && $this->hideEmptyItems)
282: {
283: unset($items[$i]['items']);
284: if(!isset($item['url']))
285: {
286: unset($items[$i]);
287: continue;
288: }
289: }
290: }
291: if(!isset($item['active']))
292: {
293: if($this->activateParents && $hasActiveChild || $this->activateItems && $this->isItemActive($item,$route))
294: $active=$items[$i]['active']=true;
295: else
296: $items[$i]['active']=false;
297: }
298: elseif($item['active'])
299: $active=true;
300: }
301: return array_values($items);
302: }
303:
304: /**
305: * Checks whether a menu item is active.
306: * This is done by checking if the currently requested URL is generated by the 'url' option
307: * of the menu item. Note that the GET parameters not specified in the 'url' option will be ignored.
308: * @param array $item the menu item to be checked
309: * @param string $route the route of the current request
310: * @return boolean whether the menu item is active
311: */
312: protected function isItemActive($item,$route)
313: {
314: if(isset($item['url']) && is_array($item['url']) && !strcasecmp(trim($item['url'][0],'/'),$route))
315: {
316: unset($item['url']['#']);
317: if(count($item['url'])>1)
318: {
319: foreach(array_splice($item['url'],1) as $name=>$value)
320: {
321: if(!isset($_GET[$name]) || $_GET[$name]!=$value)
322: return false;
323: }
324: }
325: return true;
326: }
327: return false;
328: }
329: }
330: