This is a snapshot of an early working draft and has therefore been superseded by the HTML standard.

This document will not be further updated.

HTML 5

Call For Comments — 27 October 2007

3.18.3. The command element

Metadata element, and strictly inline-level content.

Contexts in which this element may be used:
Where metadata elements are expected.
Where strictly inline-level content is allowed.
Content model:
Empty.
Element-specific attributes:
type
label
icon
hidden
disabled
checked
radiogroup
default
Also, the title attribute has special semantics on this element.
DOM interface:
interface HTMLCommandElement : HTMLElement {
           attribute DOMString type;
           attribute DOMString label;
           attribute DOMString icon;
           attribute boolean hidden;
           attribute boolean disabled;
           attribute boolean checked;
           attribute DOMString radiogroup;
           attribute boolean default;
 void click(); // shadows HTMLElement.click()
};

The Command interface must also be implemented by this element.

The command element represents a command that the user can invoke.

The type attribute indicates the kind of command: either a normal command with an associated action, or a state or option that can be toggled, or a selection of one item from a list of items.

The attribute's value must be either "command", "checkbox", or "radio", denoting each of these three types of commands respectively. The attribute may also be omitted if the element is to represent the first of these types, a simple command.

The label attribute gives the name of the command, as shown to the user.

The title attribute gives a hint describing the command, which might be shown to the user to help him.

The icon attribute gives a picture that represents the command. If the attribute is specified, the attribute's value must contain a URI (or IRI).

The hidden attribute is a boolean attribute that, if present, indicates that the command is not relevant and is to be hidden.

The disabled attribute is a boolean attribute that, if present, indicates that the command is not available in the current state.

The distinction between Disabled State and Hidden State is subtle. A command should be Disabled if, in the same context, it could be enabled if only certain aspects of the situation were changed. A command should be marked as Hidden if, in that situation, the command will never be enabled. For example, in the context menu for a water faucet, the command "open" might be Disabled if the faucet is already open, but the command "eat" would be marked Hidden since the faucet could never be eaten.

The checked attribute is a boolean attribute that, if present, indicates that the command is selected.

The radiogroup attribute gives the name of the group of commands that will be toggled when the command itself is toggled, for commands whose type attribute has the value "radio". The scope of the name is the child list of the parent element.

If the command element is used when generating a context menu, then the default attribute indicates, if present, that the command is the one that would have been invoked if the user had directly activated the menu's subject instead of using its context menu. The default attribute is a boolean attribute.

Need an example that shows an element that, if double-clicked, invokes an action, but that also has a context menu, showing the various command attributes off, and that has a default command.

The type, label, icon, hidden, disabled, checked, radiogroup, and default DOM attributes must reflect their respective namesake content attributes.

The click() method's behaviour depends on the value of the type attribute of the element, as follows:

If the type attribute has the value checkbox

If the element has a checked attribute, the UA must remove that attribute. Otherwise, the UA must add a checked attribute, with the literal value checked. The UA must then fire a click event at the element.

If the type attribute has the value radio

If the element has a parent, then the UA must walk the list of child nodes of that parent element, and for each node that is a command element, if that element has a radiogroup attribute whose value exactly matches the current element's (treating missing radiogroup attributes as if they were the empty string), and has a checked attribute, must remove that attribute and fire a click event at the element.

Then, the element's checked attribute attribute must be set to the literal value checked and a click event must be fired at the element.

Otherwise

The UA must fire a click event at the element.

Firing a synthetic click event at the element does not cause any of the actions described above to happen.

should change all the above so it actually is just trigged by a click event, then we could remove the shadowing click() method and rely on actual events.

Need to define the command="" attribute

command elements are not rendered unless they form part of a menu.

Block-level element, and structured inline-level element.

Contexts in which this element may be used:
Where block-level elements are expected.
Where structured inline-level elements are allowed.
Content model:
Zero or more li elements, or inline-level content (but not both).
Element-specific attributes:
type
label
autosubmit
DOM interface:
interface HTMLMenuElement : HTMLElement {
           attribute DOMString type;
           attribute DOMString label;
           attribute boolean autosubmit;
};

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 tool bar state, in which the element is declaraing a tool bar. 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 tool bar.

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 tool bar 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 may perform or activate, or, if the element has no li element children, a paragraph 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 autosubmit attribute is a boolean attribute that, if present, indicates that selections made to form controls in this menu are to result in the control's form being immediately submitted.

If a change event bubbles through a menu element, then, in addition to any other default action that that event might have, the UA must act as if the following was an additional default action for that event: if (when it comes time to execute the default action) the menu element has an autosubmit attribute, and the target of the event is an input element, and that element has a type attribute whose value is either radio or checkbox, and the input element in question has a non-null form DOM attribute, then the UA must invoke the submit() method of the form element indicated by that DOM attribute.

This section is non-normative.

...

3.18.4.2. Building menus and tool bars

A menu (or tool bar) 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 behaviour depends on what the node is, as follows:

An element that defines a command
Append the command to the menu. If the element is a command element with a default attribute, mark the command as being a default command.
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
Iterate over the children of the li 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
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.

We should support label in the algorithm above -- just iterate through the contents like with li, to support input elements in label elements. Also, optgroup elements without labels should be ignored (maybe? or at least should say they have no label so that they are dropped below), and select elements inside label elements may need special processing.

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

  1. 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.
3.18.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 the 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 UA must fire a contextmenu event on 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 has a context menu assigned (using the contextmenu attribute) or not. If it does not, the default action must be for the user agent to show its default context menu, if it has one.

If the element does have a context menu assigned, then the user agent must fire a show event on the relevant menu element.

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 like that 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 attribute must reflect the contextmenu content attribute.

3.18.4.4. Toolbars

Toolbars are a kind of menu that is always visible.

When a menu element has a type attribute with the value toolbar, then the user agent must build the menu for that menu element and render it in the document in a position appropriate for that menu element.

The user agent must reflect changes made to the menu's DOM immediately in the UI.

3.18.5. Commands

A command is the abstraction behind menu items, buttons, and links. Once a command is defined, other parts of the interface can refer to the same command, allowing many access points to a single feature to share aspects such as the disabled state.

Commands are defined to have the following facets:

Type
The kind of command: "command", meaning it is a normal command; "radio", meaning that triggering the command will, amongst other things, set the Checked State to true (and probably uncheck some other commands); or "checkbox", meaning that triggering the command will, amongst other things, toggle the value of the Checked State.
ID
The name of the command, for referring to the command from the markup or from script. If a command has no ID, it is an anonymous command.
Label
The name of the command as seen by the user.
Hint
A helpful or descriptive string that can be shown to the user.
Icon
A graphical image that represents the action.
Hidden State
Whether the command is hidden or not (basically, whether it should be shown in menus).
Disabled State
Whether the command can be triggered or not. If the Hidden State is true (hidden) then the Disabled State will be true (disabled) regardless. We could make this into a string value that acts as a Hint for why the command is disabled.
Checked State
Whether the command is checked or not.
Action
The actual effect that triggering the command will have. This could be a scripted event handler, a URI to which to navigate, or a form submission.
Triggers
The list of elements that can trigger the command. The element defining a command is always in the list of elements that can trigger the command. For anonymous commands, only the element defining the command is on the list, since other elements have no way to refer to it.

Commands are represented by elements in the DOM. Any element that can define a command also implements the Command interface:

interface Command {
  readonly attribute DOMString commandType;          
  readonly attribute DOMString id;
  readonly attribute DOMString label;
  readonly attribute DOMString title;
  readonly attribute DOMString icon;
  readonly attribute boolean hidden;
  readonly attribute boolean disabled;              
  readonly attribute boolean checked;              
  void click();
  readonly attribute HTMLCollection triggers;
  readonly attribute Command command;
};

The Command interface is implemented by any element capable of defining a command. (If an element can define a command, its definition will list this interface explicitly.) All the attributes of the Command interface are read-only. Elements implementing this interface may implement other interfaces that have attributes with identical names but that are mutable; in bindings that simply flatten all supported interfaces on the object, the mutable attributes must shadow the readonly attributes defined in the Command interface.

The commandType attribute must return a string whose value is either "command", "radio", or "checked", depending on whether the Type of the command defined by the element is "command", "radio", or "checked" respectively. If the element does not define a command, it must return null.

The id attribute must return the command's ID, or null if the element does not define a command or defines an anonymous command. This attribute will be shadowed by the id DOM attribute on the HTMLElement interface.

The label attribute must return the command's Label, or null if the element does not define a command or does not specify a Label. This attribute will be shadowed by the label DOM attribute on option and command elements.

The title attribute must return the command's Hint, or null if the element does not define a command or does not specify a Hint. This attribute will be shadowed by the title DOM attribute on the HTMLElement interface.

The icon attribute must return an absolute URI to the command's Icon. If the element does not specify an icon, or if the element does not define a command, then the attribute must return null. This attribute will be shadowed by the icon DOM attribute on command elements.

The hidden attribute must return true if the command's Hidden State is that the command is hidden, and false if it is that the command is not hidden. If the element does not define a command, the attribute must return false. This attribute will be shadowed by the hidden DOM attribute on command elements.

The disabled attribute must return true if the command's Disabled State is that the command is disabled, and false if the command is not disabled. This attribute is not affected by the command's Hidden State. If the element does not define a command, the attribute must return false. This attribute will be shadowed by the disabled attribute on button, input, option, and command elements.

The checked attribute must return true if the command's Checked State is that the command is checked, and false if it is that the command is not checked. If the element does not define a command, the attribute must return false. This attribute will be shadowed by the checked attribute on input and command elements.

The click() method must trigger the Action for the command. If the element does not define a command, this method must do nothing. This method will be shadowed by the click() method on HTML elements, and is included only for completeness.

The triggers attribute must return a list containing the elements that can trigger the command (the command's Triggers). The list must be live. While the element does not define a command, the list must be empty.

The commands attribute of the document's HTMLDocument interface must return an HTMLCollection rooted at the Document node, whose filter matches only elements that define commands and have IDs.

The following elements can define commands: a, button, input, option, command.

3.18.5.1. Using the a element to define a command

An a element with an href attribute defines a command.

The Type of the command is "command".

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the string given by the element's textContent DOM attribute.

The Hint of the command is the value of the title attribute of the a element. If the attribute is not present, the Hint is the empty string.

The Icon of the command is the absolute URI of the first image in the element. Specifically, in a depth-first search of the children of the element, the first element that is img element with a src attribute is the one that is used as the image. The URI must be taken from the element's src attribute. Relative URIs must be resolved relative to the base URI of the image element. If no image is found, then the Icon facet is left blank.

The Hidden State and Disabled State facets of the command are always false. (The command is always enabled.)

The Checked State of the command is always false. (The command is never checked.)

The Action of the command is to fire a click event at the element.

3.18.5.2. Using the button element to define a command

A button element always defines a command.

The Type, ID, Label, Hint, Icon, Hidden State, Checked State, and Action facets of the command are determined as for a elements (see the previous section).

The Disabled State of the command mirrors the disabled state of the button. Typically this is given by the element's disabled attribute, but certain button types become disabled at other times too (for example, the move-up button type is disabled when it would have no effect).

3.18.5.3. Using the input element to define a command

An input element whose type attribute is one of submit, reset, button, radio, checkbox, move-up, move-down, add, and remove defines a command.

The Type of the command is "radio" if the type attribute has the value radio, "checkbox" if the type attribute has the value checkbox, and "command" otherwise.

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command depends on the Type of the command:

If the Type is "command", then it is the string given by the value attribute, if any, and a UA-dependent value that the UA uses to label the button itself if the attribute is absent.

Otherwise, the Type is "radio" or "checkbox". If the element has a label element associated with it, the textContent of the first such element is the Label (in DOM terms, this the string given by element.labels[0].textContent). Otherwise, the value of the value attribute, if present, is the Label. Otherwise, the Label is the empty string.

The Hint of the command is the value of the title attribute of the input element. If the attribute is not present, the Hint is the empty string.

There is no Icon for the command.

The Hidden State of the command is always false. (The command is never hidden.)

The Disabled State of the command mirrors the disabled state of the control. Typically this is given by the element's disabled attribute, but certain input types become disabled at other times too (for example, the move-up input type is disabled when it would have no effect).

The Checked State of the command is true if the command is of Type "radio" or "checkbox" and the element has a checked attribute, and false otherwise.

The Action of the command is to fire a click event at the element.

3.18.5.4. Using the option element to define a command

An option element with an ancestor select element and either no value attribute or a value attribute that is not the empty string defines a command.

The Type of the command is "radio" if the option's nearest ancestor select element has no multiple attribute, and "checkbox" if it does.

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the value of the option element's label attribute, if there is one, or the value of the option element's textContent DOM attribute if it doesn't.

The Hint of the command is the string given by the element's title attribute, if any, and the empty string if the attribute is absent.

There is no Icon for the command.

The Hidden State of the command is always false. (The command is never hidden.)

The Disabled State of the command is true (disabled) if the element has a disabled attribute, and false otherwise.

The Checked State of the command is true (checked) if the element's selected DOM attribute is true, and false otherwise.

The Action of the command depends on its Type. If the command is of Type "radio" then this must set the selected DOM attribute of the option element to true, otherwise it must toggle the state of the selected DOM attribute (set it to true if it is false and vice versa). Then a change event must be fired on the option element's nearest ancestor select element (if there is one), as if the selection had been changed directly.

3.18.5.5. Using the command element to define a command

A command element defines a command.

The Type of the command is "radio" if the command's type attribute is "radio", "checkbox" if the attribute's value is "checkbox", and "command" otherwise.

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the value of the element's label attribute, if there is one, or the empty string if it doesn't.

The Hint of the command is the string given by the element's title attribute, if any, and the empty string if the attribute is absent.

The Icon for the command is the absolute URI resulting from resolving the value of the element's icon attribute as a URI relative to the element's base URI. If the element has no icon attribute then the command has no Icon.

The Hidden State of the command is true (hidden) if the element has a hidden attribute, and false otherwise.

The Disabled State of the command is true (disabled) if the element has either a disabled attribute or a hidden attribute (or both), and false otherwise.

The Checked State of the command is true (checked) if the element has a checked attribute, and false otherwise.

The Action of the command is to invoke the behaviour described in the definition of the click() method of the HTMLCommandElement interface.