Skip to Main Content

Widget: menu

QuickNav

Options

Events

Methods

Type Definitions

menu

A jQuery UI widget that implements either a popup menu or menu bar. The menu bar and menu implementation roughly follows traditional desktop menu UI patterns and the WAI-ARIA menu and menu bar design patterns. A popup menu is typically opened in response to a contextmenu key/click or right click or a button press event external to this widget. See menuButton

Notable differences from desktop UI or WAI-ARIA behavior follow:

  • Does not support access keys for menu bar menu items.
  • Menu items do not support tooltips.
  • Extension to allow split menu bar items. A split item has a label and a drop down icon. Clicking on
    • the label will navigate or perform an action. Clicking on the icon will open the menu. This is to accommodate existing APEX builder menu behavior.
  • Extension to allow a menu bar item to be styled as current. This allows the menu bar to act similar to a tab set. It is useful when the menu bar is primarily used for navigation. This is to accommodate existing APEX builder menu behavior. Note the menu is still a menu and not a tab control for the purpose of UI interaction and accessibility.

The expected markup for a menu or a menu bar is an empty <div>. All the markup is generated by the widget based on the options and menu items configured for the widget. The content of the menu is defined by a nested menu items structure consisting of arrays of menu.Item objects. See menu#items. There are two exceptions:

  1. generating the menu item structure from markup, and
  2. custom menu content. See the sections below for more information.

Menu bars need to be in a container that is high enough that it will not clip the drop down menus. They typically go near or at the top of the page. Popup menus will be moved to the end of the body so that they are not clipped or hidden. Popup or drop down menus content is re-rendered each time it is open. This means that you can modify the menu items before the menu is open to change the content.

Menu placement and size will adjust to fit the browser window. If a menu contains more items than will fit scroll buttons will be added. If a menu bar has the menu#menubarOverflow option set to true and the container is not wide enough to fit all menu bar items the ones that don't fit will be moved to an overflow drop down menu.

Integration with apex.actions

By integrating actions with menus, behavior and state can be centralized and menus can support keyboard shortcuts (also known as menu accelerator keys).

For menu items of type action, toggle, or radioGroup, if the action property is a string it is the name of an action (Note: in this case only, the toggle or radioGroup type supports the action property).

Values for properties: label, icon, iconType, disabled, and accelerator are taken from the action property of the same name except accelerator is taken from the action shortcut property. It is possible to override action values such as label and icon by specifying them in the menu item. Note: When disabled and hide properties come from an action they cannot be functions.

By default items are associated with actions from the global actions context. The menu widget can be supplied with a different context using the menu#actionsContext option.

Menus From Markup

A simple menu or menu bar can be created from markup. The markup is included as the content of the menu widget element. The markup is only used to create the nested structure of items. It is removed once the element is turned into a menu and is not restored even if the widget is destroyed.

Expected markup:
An element with a <ul> child. The <ul> has one or more <li> elements each one representing a menu item. The <li> element can have either an <a> (anchor) or <span> child element for the label.

Menu item property markup source, for menu items based on markup
Menu item propertyComes from
id li[data-id]
label a or span content
href a[href] If href value is "separator" then the type is separator and the href and label are ignored
target a[target] The target window for the href. Typically "_blank" to open in a new tab or window.
hide true when li[data-hide=true] and undefined otherwise
disabled true when li[data-disabled=true] and undefined otherwise
current true when li[data-current=true] and undefined otherwise
icon li[data-icon] if the value has a space the icon is the word after the space otherwise it is the whole value
iconType li[data-icon] if the value has a space the type is the word before the space

The item type is "action" unless there is no <a> or <span> child (no label) or the anchor href="separator" or if the item is a sub menu. The type is sub menu if the <li> has a <ul> child. The sub menu is processed recursively. If the type is "action" and there is an id property and the apex.actions namespace exists and there is an action with the name equal to the id value then the menu item is associated with the action. The attribute data-custom="true" can be used with a menu bar item to create a custom markup menu. The custom markup goes under the list element <li> and must start with an element that has class a-Menu-content.

Rules for custom menu content

This section describes the rules to follow for markup in a custom content menu. See the menu#customContent option.

  • The custom menus are flat; they have no sub menus
  • Toggle and radio items are not supported
  • An element with class a-Menu-content should be the top level element or near the top. It is added if needed.
  • Any elements matching this selector a, button, .a-Menu-label will be a menu item and can receive focus. The class a-Menu-item is added if the element or one of its ancestors doesn't already have the menu item class. The element is given a tabindex=-1 attribute if needed. The class a-Menu-label is added if the focusable element doesn't already have that class or contain an element with that class. Note: for best accessibility all perceivable information should be a menu item.
  • Menu item label elements (these are the elements that receive focus) are given the role 'menuitem'
  • The menu item element is given an id.
  • The menu item element can have attribute data-id just like menus from markup

Keyboard End User Information

List of keyboard shortcuts
KeyAction
Escape Closes the sub menu or if at the top level closes the menu. When the menu closes focus returns to the element that opened the menu, if any.
Up Arrow Move focus to the previous item wrapping around at the top.
Down Arrow Move focus to the next item wrapping around at the bottom.
Enter or Space Activate the menu item. The effect depends on the type of menu item. It may perform some action, cause navigation, open a sub menu, or toggle or choose a setting. With the exception of opening a sub menu after the activation the menu closes and focus returns to the element that opened the menu, if any, and unless the action explicitly set focus.
Right Arrow On a sub menu item opens the sub menu. In a menu bar moves focus to the next menu wrapping at the end and opening it if a menu is already open.
Left Arrow In a sub menu closes the sub menu. In a menu bar moves focus to the previous menu wrapping at the beginning and opening it if a menu is already open.
Tab The behavior depends on the menu#tabBehavior option.
printable character Sets focus to the next menu item with a label that starts with the character.

When the direction is RTL the meanings of the left and right arrow keys are reversed.

When the popup menu is a context menu it is customary to support the Shift+F10 and Context Menu keys to open the menu as well as Right+Click. Processing the context menu events is outside the scope of the menu widget.

Initializer

Creates a menu widget.
Parameters:
Name Type Description
options Object A map of option-value pairs to set on the widget.
Since:
  • 5.0
Examples

Create a popup menu with two trivial action items. The markup is <div id="myMenu"></div>.

$( "#myMenu" ).menu( {
    items:[
        { type:"action", label: "Action 1", action: function() { alert("Action 1"); } },
        { type:"action", label: "Action 2", action: function() { alert("Action 2"); } }
    ]
} );

This example creates a navigation popup menu from markup. Replace the href attribute values with the URLs corresponding to pages A and B.

<div id="myMenu">
    <ul>
        <li><a href="...">Page A</a></li>
        <li><a href="...">Page B</a></li>
    </ul>
</div>
$( "#myMenu" ).menu( {} );

Options

actionsContext :actions

The actions context that this menu is associated with. This option is only applicable to menus that are integrated with actions and when associated with a non-global actions context. See Integration with apex.actions for details.

Type:
Default Value:
  • apex.actions (the global actions context)
Examples

Initialize the menu with the actionsContext option specified.

$( ".selector" ).menu( {
    actionsContext: myContext
} );

Get or set option actionsContext after initialization.

// get
var value = $( ".selector" ).menu( "option", "actionsContext" );
// set
$( ".selector" ).menu( "option", "actionsContext", myContext );

asyncFetchMenu :menu~asyncFetch

Optional callback function used to populate the menu items content asynchronously when the menu opens. This is used in the rare case when the contents of a menu need to be fetched from the server just prior to the menu being opened.

Type:
Default Value:
  • null
Example

Initialize the menu with the asyncFetchMenu option specified.

$( ".selector" ).menu( {
    asyncFetchMenu: function( menu, callback ) {
        var promise = apex.server.process( "MY_GET_MENU_ITEMS", ... );
        promise.done( function( data ) {
            // use data to populate menu.items
            menu.items = ...
            callback();
        }
    }
} );

behaveLikeTabs :boolean

Determines if the menu bar indicates the current menu item as if it were a tab set. If true menu bar items can have a current property to indicate the item is associated with the current "page". This option only applies if this is a menu bar (menu#menubar option is true). See menu.Item current property.

Type:
  • boolean
Default Value:
  • false
Examples

Initialize the menu with the behaveLikeTabs option specified.

$( ".selector" ).menu( {
    behaveLikeTabs: true
} );

Get or set option behaveLikeTabs after initialization.

// get
var value = $( ".selector" ).menu( "option", "behaveLikeTabs" );
// set
$( ".selector" ).menu( "option", "behaveLikeTabs", true );

callout :boolean

Include a callout on top level menus.

Type:
  • boolean
Default Value:
  • false
Example

Initialize the menu with the callout option specified.

$( ".selector" ).menu( {
    callout: true
} );

customContent :boolean|string

Enables custom content. This option is only for popup (context) menus or sub menus of a menu bar. The value is true, false or an element id. See section Rules for custom menu content for details.

  • If false it is a normal menu with items (or menu markup); there is no custom content. The default is false.
  • If true the content of the menu element is the custom markup.
  • If the value is a string then it is the id of an element that contains the custom content. The custom content element is moved to be the only child of the menu (or sub menu) element. This is useful for menu bar sub menus where true would not work.
Type:
  • boolean | string
Default Value:
  • false
Examples

Initialize the menu with the customContent option specified.

$( ".selector" ).menu( {
    customContent: true
} );

Get or set option customContent after initialization.

// get
var value = $( ".selector" ).menu( "option", "customContent" );
// set
$( ".selector" ).menu( "option", "customContent", true );

firstItemIsDefault :boolean

For popup/context menus only. If true the first menu item gets an extra class to indicate it is the default choice. The menu widget is not responsible for implementing any default behavior.

Type:
  • boolean
Default Value:
  • false
Examples

Initialize the menu with the firstItemIsDefault option specified.

$( ".selector" ).menu( {
    firstItemIsDefault: true
} );

Get or set option firstItemIsDefault after initialization.

// get
var value = $( ".selector" ).menu( "option", "firstItemIsDefault" );
// set
$( ".selector" ).menu( "option", "firstItemIsDefault", true );

iconType :string

This is the default icon type for all items. See menu.Item iconType property.

Type:
  • string
Default Value:
  • "a-Icon"

idPrefix :string

Optional string prefix to use for element ids used in the generated menu markup.

Type:
  • string
Default Value:
  • null

items :Array.<menu.Item>

An array of menu.Item objects that define the content of the menu. This option is required when the widget is a menu bar. For popup menus at least one item is required when the widget is initialized unless the menu is fetched asynchronously, defined by custom content, or defined by markup. If the menu items are not known at the time the menu is initialized provide a dummy item that can be replaced later. For example during the menu#event:beforeOpen event.

Type:
Example

Initialize the menu with the items option specified.

$( ".selector" ).menu( {
    items: [
        { type: "action", id: "MyAction1", label: "Action 1", action: function( options, element ) { ... } },
        { type: "separator" },
        { type: "action", label: "Action 2", action: function( options, element ) { ... } }
    ]
} );

Determines if the widget is a menu bar or a popup menu. If true the widget is a menu bar otherwise the widget is a popup menu. This option can only be set at the time the widget is initialized.

Type:
  • boolean
Default Value:
  • false
Example

Initialize the menu with the menubar option specified.

$( ".selector" ).menu( {
    menubar: true
} );

Determines if a menu bar supports an overflow menu. If true the menu bar will respond to window size changes by moving menu bar items that don't fit in to an overflow menu. This option only applies if this is a menu bar (menu#menubar option is true).

Type:
  • boolean
Default Value:
  • false
Examples

Initialize the menu with the menubarOverflow option specified.

$( ".selector" ).menu( {
    menubarOverflow: true
} );

Get or set option menubarOverflow after initialization.

// get
var value = $( ".selector" ).menu( "option", "menubarOverflow" );
// set
$( ".selector" ).menu( "option", "menubarOverflow", true );

Determines if menu bar sub menu items always have a down arrow icon. If true menu bar sub menu items will have a down arrow icon added. This option only applies if this is a menu bar (menu#menubar option is true).

The default is false unless the menu bar has a mix of action and sub menu items in which case it is true. This does not affect split menu items which always show a down arrow with a divider.

Type:
  • boolean
Default Value:
  • false
Examples

Initialize the menu with the menubarShowSubMenuIcon option specified.

$( ".selector" ).menu( {
    menubarShowSubMenuIcon: true
} );

Get or set option menubarShowSubMenuIcon after initialization.

// get
var value = $( ".selector" ).menu( "option", "menubarShowSubMenuIcon" );
// set
$( ".selector" ).menu( "option", "menubarShowSubMenuIcon", true );

slide :boolean

If true menus will open with a slide down annimation otherwise they are shown all at once.

Type:
  • boolean
Default Value:
  • false
Examples

Initialize the menu with the slide option specified.

$( ".selector" ).menu( {
    slide: true
} );

Get or set option slide after initialization.

// get
var value = $( ".selector" ).menu( "option", "slide" );
// set
$( ".selector" ).menu( "option", "slide", true );

tabBehavior :string

Determines what happens when the tab key is pressed while focus is in a menu. The value is one of the following:

  • "EXIT": Tab or shift tab exit (and close) the menu and focus moves to the next (previous) tab stop relative to the item that launched the menu. Not valid for popup menus because they don't have a launch element. This follows the DHTML Style guide recommendation.
  • "NEXT": Tab and shift tab work like the Down and Up arrow keys but does not wrap.
  • "NONE": The tab key does nothing. This is most like normal desktop menus
Type:
  • string
Default Value:
  • "EXIT"
Examples

Initialize the menu with the tabBehavior option specified.

$( ".selector" ).menu( {
    tabBehavior: "NONE"
} );

Get or set option tabBehavior after initialization.

// get
var value = $( ".selector" ).menu( "option", "tabBehavior" );
// set
$( ".selector" ).menu( "option", "tabBehavior", "NONE" );

Determines if navigation menu items are rendered as links. If true action menu items with a href property are rendered with an anchor element. This allows some non-menu but web browser behavior that is expected of links to work (middle or right mouse click, and Shift and Ctrl key modifiers on click or Enter key).

The default is true. Set to false if the menu is mainly for functions and you want a more desktop experience.

Type:
  • boolean
Default Value:
  • true
Examples

Initialize the menu with the useLinks option specified.

$( ".selector" ).menu( {
    useLinks: false
} );

Get or set option useLinks after initialization.

// get
var value = $( ".selector" ).menu( "option", "useLinks" );
// set
$( ".selector" ).menu( "option", "useLinks", false );

Events

afterClose

Triggered after the menu has been closed. In all cases the menu has been closed. In all most all cases the action has already taken place. There is an exception for anchor menu items invoked with the Space key where actionTaken is reporting on the future and actionTookFocus is false when the action may take focus when it happens.
Properties:
Name Type Description
event Event jQuery event object.
ui Object
Properties
Name Type Description
actionTookFocus boolean true if the action set focus.
actionTaken boolean true if menu closed because an action was taken.
launcher element The element that opened the menu if any.
Examples

Initialize the menu with the afterClose callback specified:

$( ".selector" ).menu({
    afterClose: function( event, ui ) {}
});

Bind an event listener to the menuafterclose event:

$( ".selector" ).on( "menuafterclose", function( event, ui ) {} );

beforeOpen

Triggered just before the menu is opened.
Properties:
Name Type Description
event Event jQuery event object.
ui object
Properties
Name Type Description
menu object The menu being opened. The menu has an items array property that you can modify to control all aspects of the items that will be shown in the menu.
Examples

Initialize the menu with the beforeOpen callback specified:

$( ".selector" ).menu({
    beforeOpen: function( event, ui ) {}
});

Bind an event listener to the menubeforeopen event:

$( ".selector" ).on( "menubeforeopen", function( event, ui ) {} );

create

Triggered when the menu is created.
Properties:
Name Type Description
event Event jQuery event object.
ui Object Currently empty
Examples

Initialize the menu with the create callback specified:

$( ".selector" ).menu({
    create: function( event, ui ) {}
});

Bind an event listener to the menucreate event:

$( ".selector" ).on( "menucreate", function( event, ui ) {} );

Methods

find(id) → {menu.Item}

Find a menu item by id.

Parameters:
Name Type Description
id string The id of the menu item. See the id property of menu.Item.
Returns:
The menu item found or null if there is no item with the given id.
Type
menu.Item
Example

This menu finds the menu item with id "MyAction1".

$( ".selector" ).menu( "find", "MyAction1" );

open(x, yopt)

Opens the popup menu or the specified menu of a menu bar. It is more common to use the menu#toggle method.

Parameters:
Name Type Attributes Description
x number | jQuery If this is a popup menu x is either the page X coordinate at which to display the menu or the jQuery object of the launch element to place the menu near (typically under). If this is a menu bar then x is either the index or the jQuery object of the menu bar item to open.
y number | boolean <optional>
 If this is a popup menu y is either the Y coordinate at which to display the menu or if x is the launch element this can be false to not give the menu focus. Not used when this is a menu bar.

refresh()

Call to refresh the menubar if any of the menu bar items change or settings that affect the menubar change. No need to call for popup menus or for changes in any of the menus or sub menus of a menubar.

resize()

Call to resize the menubar if the width of the menubar container changes. This is only needed for menu bars that have option menu#menubarOverflow equal true. Window resize is automatically handled so that if the width automatically changes due to a window resize event there is no need to call resize.

setCurrentMenuItem(item)

Set the current menu bar item. Any previous current property is deleted.
Parameters:
Name Type Description
item menu.Item | string The menu item or id of menu item to make current.

toggle(x, yopt)

If the menu is closed it will be opened and if it is opened it will be closed. This will toggle a popup menu or a specific menu of a menubar. The need to open a menu bar menu should be very rare. Using a menuButton or a menu button in a toolbar removes the need to call this method because toggling the menu is automatic. The most common use of this method is to open a menu in response to a right click or contextmenu event.

Parameters:
Name Type Attributes Description
x number | jQuery If this is a popup menu x is either the page X coordinate at which to display the menu or the jQuery object of the launch element to place the menu near (typically under). If this is a menu bar then x is either the index or the jQuery object of the menu bar item to open.
y number | boolean <optional>
 If this is a popup menu y is either the Y coordinate at which to display the menu or if x is the launch element this can be false to not give the menu focus. Not used when this is a menu bar.
Examples

Toggle the menu in response to a contextmenu event:

$( "#myRegion" ).on( "contextmenu", function( event ) {
    event.preventDefault();
    $( "#myMenu" ).menu( "toggle", event.pageX, event.pageY );
});

Toggle the menu in response to a Shift+F10 keyboard event:

$( "#myRegion" ).on( "keydown", function( event ) {
    var target$, pos;
    // shift F10
    if ( event.shiftKey && event.keyCode === 121 ) {
        event.preventDefault();
        target$ = $( event.target );
        pos = target$.offset();
        $( "#myMenu" ).menu( "toggle", pos.left, pos.top + target$.outerHeight() );
    }
});

Type Definitions

Item

Represents a menu item in a menu bar, popup menu, or sub menu

The menu Item object has one of the following general forms (discriminated by the type property):

  • { type: "separator" }
  • { type: "subMenu", label: text, icon: css-name, menu: {...}, disabled: bool-or-fn }
  • { type: "toggle", label: text, accelerator: text, set: fn, get: fn, onLabel: text, offLabel: text, disabled: bool-or-fn }
  • { type: "action", label: text, accelerator: text, action: fn, icon: css-name, disabled: bool-or-fn }
  • { type: "radioGroup", set: fn, get: fn, choices: [ { label: text, value: string, disabled: bool-or-fn, accelerator: text },... ] }

For toggle menu items only one of label or (onLabel and offLabel) is used. If both are present label is used.

As an alternative to label (or onLabel, offLabel) you can specify labelKey (or onLabelKey, offLabelKey) and the apex.lang.getMessage function will be used each time the menu is rendered to lookup the label text. The localized label text is stored in the respective label, onLabel, or offLabel property.

For action menu items only one of href or action is used. If both are present action is used.

When menu#menubar is true and only for menu bar menu items the subMenu item can have action or href properties. In this case it is a split menu item - it can either drop down the sub menu or perform the action/navigation depending on where it is clicked or what key is entered.

When menu#menubar is true and menu#behaveLikeTabs is true a current property is allowed. If a sub menu item has current equal true the "current" state bubbles up to the parent menu bar item. If current is true the menu item can be styled in a special way to indicate that the menu item is "current".

There is also an item type: "display" that is used internally for custom markup menus. It is similar to an action that has no action which makes it similar to disabled but the intention is different and so should be the visual presentation.

Properties:
Name Type Attributes Description
type string The type of the menu item. One of "separator", "subMenu", "toggle", "action", or "radioGroup"
id string <optional>
 All menu items can have an id property. The id is only used to find the item by id using the menu#find method.
label string <optional>
 The label to display in the menu item.
labelKey string <optional>
 The message key to lookup the localized message to display in the menu item.
offLabel string <optional>
 Only applies to toggle items that act as dynamic antonyms. The label to display when the item value is false.
offLabelKey string <optional>
 The message key to lookup the localized message to display for offLabel.
onLabel string <optional>
 Only applies to toggle items that act as dynamic antonyms. The label to display when the item value is true.
onLabelKey string <optional>
 The message key to lookup the localized message to display for onLabel.
hide boolean | function <optional>
 All menu items can have a hide property. The value is true or false or a function returning true or false. If true the item is ignored. The function is called in the context of the menu item. The menu widget options object is passed as the first argument.
disabled boolean | function <optional>
 The disabled property can either be true or false or a function that returns true or false. If true the item is disabled. The function is called in the context of the menu item. The menu widget options object is passed as the first argument.
iconType string <optional>
 Icon type CSS class name. Not supported for separator, toggle or radioGroup choice items. Not supported on menu bar items. The iconType on action and subMenu items overrides the iconType set in the options object.
icon string <optional>
 Icon CSS class name(s). Not supported for separator, toggle or radioGroup choice items. Not supported on menu bar items. There needs to be corresponding CSS rules to select a particular icon.
iconStyle string <optional>
 If there is an icon then you can also have an iconStyle property with a value such as "color: #FF99AB".
href string <optional>
 A URL to navigate to when the menu item is activated.
target string <optional>
 The target window for the URL href. Only applies when href is provided. Typically "_blank" to open in a new tab or window.
action function | string <optional>
 A function to call when the menu item is activated. The action function is called in the context of the menu item. The widget options object is passed as the first argument. The second argument is the element that focus would normally return to when the menu closes (or null if none). The action should return true if it will take responsibility for setting the focus.
set function <optional>
 The set function receives a single argument which is the value of the checkbox (true/false) or radio button.
get function <optional>
 The get functions must return the value of the checkbox (true/false) or radio button.
accelerator string <optional>
 Name of an accelerator key that will activate the menu item such as "Ctrl+M". The menu widget is only responsible for showing the accelerator text in the menu item. It does not implement the keyboard handling. See Integration with apex.actions.
menu object <optional>
 The menu object contain containing items. Only valid for type subMenu.
Properties
Name Type Description
items Array.<menu.Item> An array of menu.Item objects.
customContent boolean | string Only applicable to menu bar sub menu items. See menu#customContent.
choices Array.<object> <optional>
 Only applies to items of type radioGroup. An array of radio items.
choices[].label string <optional>
 The radioGroup item label.
choices[].labelKey string <optional>
 The message key to lookup for the localized message to display for radioGroup item label.
choices[].value string <optional>
 The value to set when this item is activated.
choices[].disabled boolean | function <optional>
 If true the choice is disabled.
choices[].accelerator string <optional>
 Name of an accelerator key that will activate the radioGroup item.
current boolean <optional>
 If true the menu item reflects the current location within the application. This only applies if the menu#behaveLikeTabs option is true.

asyncFetch(menu, callback)

This function is called to start the asynchronous process to fetch the menu items and when done assigns them to the menu.items array and then calls callback.

The callback takes an optional bool input parameter that is false to indicate that the menu items could not be fetched.

Parameters:
Name Type Description
menu object The menu object to fetch items for.
callback function Call this function with no arguments after menu.items has been assigned. If there is an error getting the menu items call this function with the value false.