details elementsummary element followed by flow content.open — Whether the details are visibleinterface 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 first summary element
child of the element, if any, represents the summary or
legend of the details. If there is no child
summary element, the user agent should provide its own
legend (e.g. "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.
When the element is created, if the attribute is absent, the additional information should be hidden; if the attribute is present, that information should be shown. Subsequently, if the attribute is removed, then the information should be hidden; if the attribute is added, the information should be shown.
The user agent should allow the user to request that the
additional information be shown or hidden. To honor a request for
the details to be shown, the user agent must set the open attribute on the element to
the value open. To honor a request for the
information to be hidden, the user agent must remove the open attribute from the
element.
The open IDL
attribute must reflect the open content attribute.
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>
summary elementdetails element.HTMLElement.The summary element represents a
summary, caption, or legend for the rest of the contents of the
summary element's parent details
element, if any.
menu elementtype attribute is in the toolbar state: Palpable content.type attribute is in the popup menu state: as the child of a menu element whose type attribute is in the popup menu state.type attribute is in the toolbar state: either zero or more li elements, or flow content.type attribute is in the popup menu state: in any order, zero or more menuitem elements, zero or more hr elements, and zero or more menu elements whose type attributes are in the popup menu state.type — Type of menulabel — User-visible labelinterface HTMLMenuElement : HTMLElement {
attribute DOMString type;
attribute DOMString label;
// also has obsolete members
};
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 two states. The
popup keyword maps to the popup menu state, in which the element is declaring a context menu or the menu for a
menu button. 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 popup menu
state if the parent element is a menu element whose type attribute is in the popup
menu state; otherwise, it is the toolbar state.
If a menu element's type attribute is in the
popup menu state, then the element represents
the commands of a popup menu, and the user can only examine and interact with the commands if that
popup menu is activated through some other element, either via the contextmenu attribute or the button element's menu attribute.
If a menu element's type attribute is in the
toolbar state, then the element represents a
toolbar consisting of its contents, in the form of either an unordered list of items (represented
by li elements), 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: a context menu containing
another menu would use the nested menu's label attribute for
the submenu's menu label. The label attribute must only be
specified on menu elements whose parent element is a menu element whose
type attribute is in the popup
menu state.
A menu is a currently relevant menu element if it is the
child of a currently relevant menu element, or if it is the
designated pop-up menu of a button element that is not
inert, does not have a hidden attribute, and is not
the descendant of an element with a hidden attribute.
A pop-up menu consists of a list of zero or more menu items, which can be any of:
menuitem)hr)menu)To construct and show a menu for a particular menu element and with a
particular element as a subject, the user agent must run the following steps:
Let the menu be an empty list of the type described above.
Run the menu builder steps for the menu element using the menu
prepared in the previous list as the output.
The menu builder steps for a menu element using a specific menu as
output are as follows: For each child node of the menu in tree order,
run the appropriate steps from the following list:
menuitem element that defines
a commandmenuitem element has a default attribute, mark the command as being a default
command.hr elementmenu element with no label attributemenu element for the same menu, then append another separator to the
menu.menu element with a label attributemenu element using the
new submenu as the output. Then, append the submenu to the menu, using the value of the child
menu element's label attribute as the label
of the submenu.Remove any submenu with no label, or whose label is the empty string, in the menu or any submenus.
Remove any menu item with no label, or whose label is the empty string, in the menu or any submenus.
Collapse all sequences of two or more adjacent separators in the menu or any submenus to a single separator.
Remove all separators at the start or end of the menu and any submenus.
Display the menu to the user, and let the algorithm that invoked this one continue.
If the user selects a menu item that corresponds to an element that still represents a command when the user selects it, then the UA must invoke that
command's Action. If the command's Action is defined as firing
a click event, either directly or via the run
synthetic click activation steps algorithm, then the relatedTarget attribute of that click event must be initialized to the subject passed to this
construct and show a menu algorithm.
Pop-up menus must not, while being shown, reflect changes in the DOM. The menu is constructed from the DOM before being shown, and is then immutable.
The type and label IDL attributes must reflect the
respective content attributes of the same name.
In this example, the menu element is used to describe a toolbar with three menu
buttons on it, each of which has a dropdown menu with a series of options:
<menu> <li> <button type=menu value="File" menu="filemenu"> <menu id="filemenu" type="popup"> <menuitem onclick="fnew()" label="New..."> <menuitem onclick="fopen()" label="Open..."> <menuitem onclick="fsave()" label="Save"> <menuitem onclick="fsaveas()" label="Save as..."> </menu> </li> <li> <button type=menu value="Edit" menu="editmenu"> <menu id="editmenu" type="popup"> <menuitem onclick="ecopy()" label="Copy"> <menuitem onclick="ecut()" label="Cut"> <menuitem onclick="epaste()" label="Paste"> </menu> </li> <li> <button type=menu value="Help" menu="helpmenu"> <menu id="helpmenu" type="popup"> <menuitem onclick="location='help.html'" label="Help"> <menuitem onclick="location='about.html'" label="About"> </menu> </li> </menu>
In a supporting user agent, this might look like this (assuming the user has just activated the second button):
menuitem elementmenu element whose type attribute is in the popup menu state.type — Type of commandlabel — User-visible labelicon — Icon for the commanddisabled — Whether the form control is disabledchecked — Whether the command or control is checkedradiogroup — Name of group of commands to treat as a radio button groupdefaultcommand — Command definitiontitle attribute has special semantics on this element. — Hint describing the commandinterface HTMLMenuItemElement : HTMLElement {
attribute DOMString type;
attribute DOMString label;
attribute DOMString icon;
attribute boolean disabled;
attribute boolean checked;
attribute DOMString radiogroup;
attribute boolean default;
readonly attribute HTMLElement? command;
};
The menuitem element represents a command that the user can invoke from a popup
menu (either a context menu or the menu of a menu button).
A menuitem element that uses one or more of the
type,
label,
icon,
disabled,
checked, and
radiogroup
attributes defines a new command.
A menuitem 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.
If the command attribute is specified, the element
is in the indirect command mode. If it is not specified, it is in the explicit
command mode. When the element is in the indirect command mode, the element
must not have any of the following attributes specified:
type,
label,
icon,
disabled,
checked,
radiogroup.
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 element represents a normal command with an associated action.
The element represents a state or option that can be toggled.
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 if the element is in the explicit command mode. If the attribute is
specified, it must have a value that is not the empty string.
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. To obtain
the absolute URL of the icon when the attribute's value is not the empty string, the
attribute's value must be resolved relative to the element.
When the attribute is absent, or its value is the empty string, or resolving its value fails, there is no icon.
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 menuitem 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 menuitem 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.
The title attribute gives a hint describing
the command, which might be shown to the user to help him.
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 the menu. The default attribute is a boolean attribute.
In this trivial example, a submit button is given a context menu that has two options, one to reset the form, and one to submit the form. The submit command is marked as being the default.
<form action="dosearch.pl"> <p><label>Enter search terms: <input type="text" name="terms"></label></p> <p><input type=submit contextmenu=formmenu id="submitbutton"></p> <p hidden><input type=reset id="resetbutton"></p> <menu type=popup id=formmenu> <menuitem command="submitbutton" default> <menuitem command="resetbutton"> </menu> </form>
The type IDL attribute must
reflect the content attribute of the same name, limited to only known
values.
The label, icon, disabled, checked, and radiogroup, and default IDL attributes must reflect
the respective content attributes of the same name.
The command IDL attribute must return the
master command, if any, or null otherwise.
If the element's Disabled State is false
(enabled) then the element's activation behavior depends on the element's type and command
attributes, as follows:
command attributeThe user agent must run synthetic click activation steps on the element's master command.
type attribute is in the Checkbox stateIf 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.
type attribute is in the Radio stateIf 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 menuitem 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.
Then, the element's checked attribute must be set
to the literal value checked.
The element's activation behavior is to do nothing.
Firing a synthetic click event at the element
does not cause any of the actions described above to happen.
If the element's Disabled State is true (disabled) then the element has no activation behavior.
The menuitem element is not rendered except as part of a popup menu.
Here is an example of a pop-up menu button with three options that let the user toggle between left, center, and right alignment. One could imagine such a toolbar as part of a text editor. The menu also has a separator followed by another menu item labeled "Publish", though that menu item is disabled.
<button type=menu menu=editmenu>Commands...</button>
<menu type="popup" id="editmenu">
<menuitem type="radio" radiogroup="alignment" checked="checked"
label="Left" icon="icons/alL.png" onclick="setAlign('left')">
<menuitem type="radio" radiogroup="alignment"
label="Center" icon="icons/alC.png" onclick="setAlign('center')">
<menuitem type="radio" radiogroup="alignment"
label="Right" icon="icons/alR.png" onclick="setAlign('right')">
<hr>
<menuitem type="command" disabled
label="Publish" icon="icons/pub.png" onclick="publish()">
</menu>
The contextmenu attribute gives the element's
context menu. The value must be the ID of a menu
element in the same home subtree whose type
attribute is in the popup menu state.
When a user right-clicks on an element with a contextmenu attribute, the user agent will first fire a contextmenu event at the element, and then, if that event is not
canceled, a show event at the menu element.
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=popup id=namemenu> <menuitem label="Pick random name" onclick="document.forms.npc.elements.char.value = getRandomName()"> <menuitem 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.
Each element has an assigned context menu, which can be null. If an element A has a contextmenu attribute, and there is
an element with the ID given by A's contextmenu attribute's value in A's
home subtree, and the first such element in tree order is a
menu element whose type attribute is in the popup menu state, then A's assigned
context menu is that element. Otherwise, if A has a parent element,
then A's assigned context menu is the assigned context
menu of its parent element. Otherwise, A's assigned context
menu is null.
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:
The user agent must fire a trusted 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
was interpreted as a request for the context menu.
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 or not the element for which the menu was requested has a non-null assigned context
menu when the event dispatch has completed, as follows.
If the assigned context menu of the element for which the menu was requested is null, the default action must be for the user agent to show its default context menu, if it has one.
Otherwise, let subject be the element for which the menu was requested, and
let menu be the assigned context menu of target immediately after the contextmenu
event's dispatch has completed. The user agent must fire a
trusted event with the name show at menu, using the RelatedEvent
interface, with the relatedTarget attribute
initialized to subject. The event must be cancelable.
If this event (the show event) is not canceled, then
the user agent must construct and show the menu for
menu with subject as the subject.
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.
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.
[Constructor(DOMString type, optional RelatedEventInit eventInitDict)]
interface RelatedEvent : Event {
readonly attribute EventTarget? relatedTarget;
};
dictionary RelatedEventInit : EventInit {
EventTarget? relatedTarget;
};
relatedTargetReturns the other event target involved in this event. For example, when a show event fires on a menu element, the other event
target involved in the event would be the element for which the menu is being shown.
The relatedTarget attribute must
return the value it was initialized to. When the object is created, this attribute must be
initialized to null. It represents the other event target that is related to the event.