Description
The menu widget adds interactivity to menu elements created with HTML & CSS. Menus present a list of options for the user to choose from as a popup 'attached' to the trigger element. Menus can optionally allow users to check one or more of the options.
Usage
The menu widget does not build the menu element itself; it should exist in the page as an HTML element with the appropriate CSS classes already added to it (a decision made so that menus can be accessible even without javascript enabled). The attributes to initialize the menu should be added to the trigger element - that is, the element a user will click to show the menu. Typically this would be a link or button.
The menu element should have the same ID as the trigger element, but suffixed with _menu; e.g. if the trigger has the ID 'trigger', the ID on the menu element should be 'trigger_menu'.
With these conditions met, initializing the menu simply consists of adding the widget attribute to the trigger.
<!-- The trigger --> <a href='#elMyMenu_menu' id='elMyMenu' data-ipsMenu>Open Menu</a> <!-- The menu --> <ul id='elMyMenu_menu' class='ipsMenu'> ... </ul>
Pinging URLs from menu items
The menu widget provides a mechanism for pinging the menu item URL via AJAX instead of following the link directly. To use this behavior, provide the data-action data attribute on the menu list item:
<li class='ipsMenu_item' data-action='ipsMenu_ping'><a href='...'>Menu item</a></li>
Providing menu values
By including the attribute data-ipsMenuValue on your menu item, you can provide a value which will be passed by events, and can be used by event handlers to identify the menu item:
<li class='ipsMenu_item' data-ipsMenuValue='itemID'><a href='...'>Menu item</a></li>
Options
className
(String; optional; default 'ipsMenu')
Provides the base menu classname that the widget will use. By default this is the standard ipsMenu class, but by passing a different classname, alternative menu styles can be built.
closeOnClick
(Boolean; optional; default true)
Determines whether the menu element will close when an item is clicked.
closeOnBlur
(Boolean; optional; default true)
Determines whether the menu element will close when somewhere other than the menu is clicked or focused (e.g. the document).
appendTo
(Selector; optional)
By default, the menu element is moved and appended to the global container element (body, usually). By using this option, you can control which element the menu will be inserted into - useful when a menu is being created inside a popup for example.
activeClass
(String; optional)
Specifies a classname that will be applied to the trigger element when the menu is opened.
selectable
(Mixed; optional; default false)
Specifies whether the menu will have 'selectable' functionality, allowing items to be checked and unchecked. If the value passed is radio, only one item will be selectable at once. If value passed is checkbox, multiple items can be selected. Note that the menu must have the correct CSS classes already for selectable functionality to work.
withStem
(Boolean; optional; default true)
Determines whether the menu will have a stem to indicate its relationship to the trigger.
stemOffset
(Number; optional; default 15)
A value that indicates the offset of the stem, i.e. the distance from the edge to the center point of the stem. Should rarely need to be set unless the CSS classes are changed significantly.
stopLinks
(Boolean; optional; default false)
Stops menu item links from being followed by the browser by calling preventDefault on the event.
above
(Boolean; optional; default false)
By default, menus will prefer to open below the trigger. Setting this option to true will cause this menu to prefer being above the trigger instead.
Events emitted by ips.ui.menu
Events are emitted on the trigger element.
menuOpened
Triggered when the user opens a menu by clicking on the trigger
Event data:
-
elemID
The ID of the trigger element this menu belongs to -
originalEvent
The original event object from the click (useful for calling originalEvent.preventDefault() to prevent the default browser action) -
menu
Reference to the menu element
menuClosed
Triggered when the menu closes
Event data:
-
elemID
The ID of the trigger element this menu belongs to
menuPingSuccessful
Triggered when the menu closes
No event data.
menuItemSelected
Triggered when the user selects an item within the menu
Event data:
-
triggerElem
Reference to the trigger element -
triggerID
ID of the trigger element -
menuElem
Reference to the menu element -
originalEvent
The raw javascript event object from the click -
selectedItemID
String containing the value of the selected menu item, if it provided a data-ipsMenuValue attribute. -
selectedItems
Object containing references to checked items, when menu is selectable
Events to which ips.ui.menu responds
closeMenu
Can be fired on the menu or trigger element elements to close the menu.
Report Guide