4.11 Interactive elements

4.11.1 The details element

Categories:
Flow content.
Sectioning root.
Interactive content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
One summary element followed by flow content.
Content attributes:
Global attributes
open
DOM interface:
interface HTMLDetailsElement : HTMLElement {
           attribute boolean open;
};

The details element represents a disclosure widget from which the user can obtain additional information or controls.

The details element is not appropriate for footnotes. Please see the section on footnotes for details on how to mark up footnotes.

The summary element child of the element, if any, represents the summary or legend of the details.

The rest of the element's contents represents the additional information or controls.

The open content attribute is a boolean attribute. If present, it indicates that both the summary and the additional information is to be shown to the user. If the attribute is absent, only the summary is to be shown.

The following example shows the details element being used to hide technical details in a progress report.

<section class="progress window">
 <h1>Copying "Really Achieving Your Childhood Dreams"</h1>
 <details>
  <summary>Copying... <progress max="375505392" value="97543282"></progress> 25%</summary>
  <dl>
   <dt>Transfer rate:</dt> <dd>452KB/s</dd>
   <dt>Local filename:</dt> <dd>/home/rpausch/raycd.m4v</dd>
   <dt>Remote filename:</dt> <dd>/var/www/lectures/raycd.m4v</dd>
   <dt>Duration:</dt> <dd>01:16:27</dd>
   <dt>Color profile:</dt> <dd>SD (6-1-6)</dd>
   <dt>Dimensions:</dt> <dd>320×240</dd>
  </dl>
 </details>
</section>

The following shows how a details element can be used to hide some controls by default:

<details>
 <summary><label for=fn>Name & Extension:</label></summary>
 <p><input type=text id=fn name=fn value="Pillar Magazine.pdf">
 <p><label><input type=checkbox name=ext checked> Hide extension</label>
</details>

One could use this in conjunction with other details in a list to allow the user to collapse a set of fields down to a small set of headings, with the ability to open each one.

In these examples, the summary really just summarises what the controls can change, and not the actual values, which is less than ideal.

Because the open attribute is added and removed automatically as the user interacts with the control, it can be used in CSS to style the element differently based on its state. Here, a stylesheet is used to animate the color of the summary when the element is opened or closed:

<style>
 details > summary { transition: color 1s; color: black; }
 details[open] > summary { color: red; }
</style>
<details>
 <summary>Automated Status: Operational</summary>
 <p>Velocity: 12m/s</p>
 <p>Direction: North</p>
</details>

4.11.2 The summary element

Categories:
None.
Contexts in which this element can be used:
As the first child of a details element.
Content model:
Phrasing content.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

The summary element represents a summary, caption, or legend for the rest of the contents of the summary element's parent details element.

4.11.3 The command element

Categories:
Metadata content.
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where metadata content is expected.
Where phrasing content is expected.
Content model:
Empty.
Content attributes:
Global attributes
type
label
icon
disabled
checked
radiogroup
command
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 disabled;
           attribute boolean checked;
           attribute DOMString radiogroup;
  readonly attribute HTMLElement? command;
};

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

A command can be explicitly part of a context menu or toolbar, using the menu element. It can also be put anywhere else on a page, either just to define a keyboard shortcut, or to define a command that is then referenced from other command elements.

A command element that uses the type, label, icon, disabled, checked, radiogroup, and title attributes defines a new command. A command element that uses the command attribute defines a command by reference to another one. This allows authors to define a command once, and set its state (e.g. whether it is active or disabled) in one place, and have all references to that command in the user interface change at the same time.

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 is an enumerated attribute with three keywords and states. The "command" keyword maps to the Command state, the "checkbox" keyword maps to the Checkbox state, and the "radio" keyword maps to the Radio state. The missing value default is the Command state.

The Command state

The element represents a normal command with an associated action.

The Checkbox state

The element represents a state or option that can be toggled.

The Radio state

The element represents a selection of one item from a list of items.

The label attribute gives the name of the command, as shown to the user. The label attribute must be specified and must have a value that is not the empty string.

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 valid non-empty URL potentially surrounded by spaces.

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 and hidden is subtle. A command would be disabled if, in the same context, it could be enabled if only certain aspects of the situation were changed. A command would 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 attribute must be omitted unless the type attribute is in either the Checkbox state or the Radio state.

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. The attribute must be omitted unless the type attribute is in the Radio state.

If a command element slave has a command attribute, and slave is in a Document, and there is an element in that Document whose ID has a value equal to the value of slave's command attribute, and the first such element in tree order, hereafter master, itself defines a command and either is not a command element or does not itself have a command attribute, then the master command of slave is master.

An element with a command attribute must have a master command and must not have any type, label, icon, disabled, checked, or radiogroup attributes.

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

Here is an example of a toolbar with three buttons that let the user toggle between left, center, and right alignment. One could imagine such a toolbar as part of a text editor. The toolbar also has a separator followed by another button labeled "Publish", though that button is disabled.

<menu type="toolbar">
 <command type="radio" radiogroup="alignment" checked="checked"
          label="Left" icon="icons/alL.png" onclick="setAlign('left')">
 <command type="radio" radiogroup="alignment"
          label="Center" icon="icons/alC.png" onclick="setAlign('center')">
 <command type="radio" radiogroup="alignment"
          label="Right" icon="icons/alR.png" onclick="setAlign('right')">
 <hr>
 <command type="command" disabled
          label="Publish" icon="icons/pub.png" onclick="publish()">
</menu>

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 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 Context menus

The contextmenu attribute gives the element's context menu. The value must be the ID of a menu element in the DOM.

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.