Jump to content

Guides

ips.ui.menu

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


×