4.11.4 The menu element

Categories:
Flow content.
If the element's type attribute is in the toolbar state: Interactive content.
If the element's type attribute is in the toolbar state or the list state: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Either: Zero or more li elements.
Or: Flow content.
Content attributes:
Global attributes
type
label
DOM interface:
interface HTMLMenuElement : HTMLElement {
           attribute DOMString type;
           attribute DOMString label;
};

The menu element represents a list of commands.

The type attribute is an enumerated attribute indicating the kind of menu being declared. The attribute has three states. The context keyword maps to the context menu state, in which the element is declaring a context menu. The toolbar keyword maps to the toolbar state, in which the element is declaring a toolbar. The attribute may also be omitted. The missing value default is the list state, which indicates that the element is merely a list of commands that is neither declaring a context menu nor defining a toolbar.

If a menu element's type attribute is in the context menu state, then the element represents the commands of a context menu, and the user can only interact with the commands if that context menu is activated.

If a menu element's type attribute is in the toolbar state, then the element represents a list of active commands that the user can immediately interact with.

If a menu element's type attribute is in the list state, then the element either represents an unordered list of items (each represented by an li element), each of which represents a command that the user can perform or activate, or, if the element has no li element children, flow content describing available commands.

The label attribute gives the label of the menu. It is used by user agents to display nested menus in the UI. For example, a context menu containing another menu would use the nested menu's label attribute for the submenu's menu label.

The type and label IDL attributes must reflect the respective content attributes of the same name.

This section is non-normative.

The menu element is used to define context menus and toolbars.

For example, the following represents a toolbar with three menu buttons on it, each of which has a dropdown menu with a series of options:

<menu type="toolbar">
 <li>
  <menu label="File">
   <button type="button" onclick="fnew()">New...</button>
   <button type="button" onclick="fopen()">Open...</button>
   <button type="button" onclick="fsave()">Save</button>
   <button type="button" onclick="fsaveas()">Save as...</button>
  </menu>
 </li>
 <li>
  <menu label="Edit">
   <button type="button" onclick="ecopy()">Copy</button>
   <button type="button" onclick="ecut()">Cut</button>
   <button type="button" onclick="epaste()">Paste</button>
  </menu>
 </li>
 <li>
  <menu label="Help">
   <li><a href="help.html">Help</a></li>
   <li><a href="about.html">About</a></li>
  </menu>
 </li>
</menu>

In a supporting user agent, this might look like this:

A toolbar with three buttons, labeled 'File', 'Edit', and 'Help'; where if you select the 'Edit' button you get a drop-down menu with three more options, 'Copy', 'Cut', and 'Paste'.

In a legacy user agent, the above would look like a bulleted list with three items, the first of which has four buttons, the second of which has three, and the third of which has two nested bullet points with two items consisting of links.

The following implements a similar toolbar, with a single button whose values, when selected, redirect the user to Web sites.

<form action="redirect.cgi">
 <menu type="toolbar">
  <label for="goto">Go to...</label>
  <menu label="Go">
   <select id="goto">
    <option value="" selected="selected"> Select site: </option>
    <option value="http://www.apple.com/"> Apple </option>
    <option value="http://www.mozilla.org/"> Mozilla </option>
    <option value="http://www.opera.com/"> Opera </option>
   </select>
   <span><input type="submit" value="Go"></span>
  </menu>
 </menu>
</form>

The behavior in supporting user agents is similar to the example above, but here the legacy behavior consists of a single select element with a submit button. The submit button doesn't appear in the toolbar, because it is not a child of the menu element or of its li children.

4.11.4.2 Building menus and toolbars

A menu (or toolbar) consists of a list of zero or more of the following components:

The list corresponding to a particular menu element is built by iterating over its child nodes. For each child node in tree order, the required behavior depends on what the node is, as follows:

An element that defines a command
Append the command to the menu, respecting its facets.
An hr element
An option element that has a value attribute set to the empty string, and has a disabled attribute, and whose textContent consists of a string of one or more hyphens (U+002D HYPHEN-MINUS)
Append a separator to the menu.
An li element
A label element
Iterate over the children of the element.
A menu element with no label attribute
A select element
Append a separator to the menu, then iterate over the children of the menu or select element, then append another separator.
A menu element with a label attribute
An optgroup element with a label attribute
Append a submenu to the menu, using the value of the element's label attribute as the label of the menu. The submenu must be constructed by taking the element and creating a new menu for it using the complete process described in this section.
Any other node
Ignore the node.

Once all the nodes have been processed as described above, the user agent must the post-process the menu as follows:

  1. Except for separators, any menu item with no label, or whose label is the empty string, must be removed.
  2. Any sequence of two or more separators in a row must be collapsed to a single separator.
  3. Any separator at the start or end of the menu must be removed.
4.11.4.3 Context menus

The contextmenu attribute gives the element's context menu. The value must be the ID of a menu element in the DOM. If the node that would be obtained by invoking the getElementById() method using the attribute's value as the only argument is null or not a menu element, then the element has no assigned context menu. Otherwise, the element's assigned context menu is the element so identified.

When an element's context menu is requested (e.g. by the user right-clicking the element, or pressing a context menu key), the user agent must apply the appropriate rules from the following list:

If the user requested a context menu using a pointing device

The user agent must fire an event with the name contextmenu, that bubbles and is cancelable, and that uses the MouseEvent interface, at the element for which the menu was requested. The context information of the event must be initialized to the same values as the last MouseEvent user interaction event that was fired as part of the gesture that that was interpreted as a request for the context menu.

Otherwise

The user agent must fire a synthetic mouse event named contextmenu that bubbles and is cancelable at the element for which the menu was requested.

Typically, therefore, the firing of the contextmenu event will be the default action of a mouseup or keyup event. The exact sequence of events is UA-dependent, as it will vary based on platform conventions.

The default action of the contextmenu event depends on whether the element or one of its ancestors has a context menu assigned (using the contextmenu attribute) or not. If there is no context menu assigned, the default action must be for the user agent to show its default context menu, if it has one.

If the element or one of its ancestors does have a context menu assigned, then the user agent must fire a simple event named show at the menu element of the context menu of the nearest ancestor (including the element itself) with one assigned.

The default action of this event is that the user agent must show a context menu built from the menu element.

The user agent may also provide access to its default context menu, if any, with the context menu shown. For example, it could merge the menu items from the two menus together, or provide the page's context menu as a submenu of the default menu.

If the user dismisses the menu without making a selection, nothing in particular happens.

If the user selects a menu item that represents a command, then the UA must invoke that command's Action.

Context menus must not, while being shown, reflect changes in the DOM; they are constructed as the default action of the show event and must remain as constructed until dismissed.

User agents may provide means for bypassing the context menu processing model, ensuring that the user can always access the UA's default context menus. For example, the user agent could handle right-clicks that have the Shift key depressed in such a way that it does not fire the contextmenu event and instead always shows the default context menu.

The contextMenu IDL attribute must reflect the contextmenu content attribute.

Here is an example of a context menu for an input control:

<form name="npc">
 <label>Character name: <input name=char type=text contextmenu=namemenu required></label>
 <menu type=context id=namemenu>
  <command label="Pick random name" onclick="document.forms.npc.elements.char.value = getRandomName()">
  <command label="Prefill other fields based on name" onclick="prefillFields(document.forms.npc.elements.char.value)">
 </menu>
</form>

This adds two items to the control's context menu, one called "Pick random name", and one called "Prefill other fields based on name". They invoke scripts that are not shown in the example above.

4.11.4.4 Toolbars

When a menu element has a type attribute in the toolbar state, then the user agent must build the menu for that menu element, and use the result in the rendering.

The user agent must reflect changes made to the menu's DOM, by immediately rebuilding the menu.