4.11 Interactive elements — HTML 5
HTML5
A vocabulary and associated APIs for HTML and XHTML
← 4.10 Forms
Table of contents
5 Loading Web pages →
4.11
Interactive elements
Status:
Last call for comments
4.11.1
The
details
element
Status:
Last call for comments.
ISSUE-93
(details) blocks progress to Last Call
Categories
Flow content
Sectioning root
Interactive content
Contexts in which this element may 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
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
open
content attribute is a
boolean attribute
. If present,
it indicates that the details are to be shown to the user. If the
attribute is absent, the details are not to be shown.
If the attribute is removed, then the details should be
hidden. If the attribute is added, the details should be shown.
The user agent should allow the user to request that the details
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
details to be hidden, the user agent must remove the
open
attribute from the
element.
The
open
attribute must
reflect
the
open
content attribute.
The following example shows the
details
element
being used to hide technical details in a progress report.Copying "Really Achieving Your Childhood Dreams"
Copying... 25%
The following shows how a
details
element can be
used to hide some controls by default:Name & Extension:
One could use this in conjuction 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.
4.11.2
The
summary
element
Categories
None.
Contexts in which this element may 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
summary, caption, or legend for the rest of the contents of the
summary
element's parent
details
element
, if any
4.11.3
The
command
element
Status:
Last call for comments
Categories
Metadata content
Flow content
Phrasing content
Contexts in which this element may 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
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
};
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 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 URL
To obtain the
absolute URL
of the icon, the attribute's value must be
resolved
relative to the
element.
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.
The
type
label
icon
disabled
checked
, and
radiogroup
IDL attributes must
reflect
the respective content
attributes of the same name.
The element's
activation behavior
depends on the
value of the
type
attribute
of the element, as follows:
If the
type
attribute is
in the
Checkbox
state
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 is
in the
Radio
state
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.
Then, the element's
checked
attribute attribute
must be set to the literal value
checked
and
the user agent must
fire a
click
event
at the element.
Otherwise
The element has no
activation behavior
Firing a synthetic
click
event at the element does not cause
any of the actions described above to happen.
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.
4.11.4
The
element
Status:
Last call for comments
Categories
Flow content
If the element's
type
attribute is in the
toolbar
state:
Interactive content
Contexts in which this element may 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
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
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
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
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.
4.11.4.1
Introduction
Status:
Last call for comments
This section is non-normative.
The
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:
In a supporting user agent, this might look like this:
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.
The behavior in supporting user agents is similar to the example
above, but here the legacy behaviour consists of a single
select
element with a submit button. The submit button
doesn't appear in the toolbar, because it is not a direct child of
the
element or of its
li
children.
4.11.4.2
Building menus and toolbars
Status:
Last call for comments
A menu (or toolbar) consists of a list of zero or more of the
following components:
Commands
, which can be marked as default commands
Separators
Other menus (which allows the list to be nested)
The list corresponding to a particular
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
label
element
Iterate over the children of the element.
element with no
label
attribute
select
element
Append a separator to the menu, then iterate over the children
of the
or
select
element, then
append another separator.
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:
Except for separators, any menu item with no label, or whose
label is the empty string, must be removed.
Any sequence of two or more separators in a row must be
collapsed to a single separator.
Any separator at the start or end of the menu must be
removed.
4.11.4.3
Context menus
Status:
Last call for comments
The
contextmenu
attribute gives the element's
context
. The value must be the ID of a
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
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 simple 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
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
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
attribute must
reflect
the
contextmenu
content attribute.
Here is an example of a context menu for an input control:
This adds to 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
Status:
Last call for comments
When a
element has a
type
attribute in the
toolbar
state, then the user agent
must
build
the
menu for that
element, and use the result in the
rendering.
The user agent must reflect changes made to the
's DOM, by immediately
rebuilding
the menu.
4.11.5
Commands
Status:
Last call for comments
command
is the abstraction
behind menu items, buttons, and links.
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
An
absolute URL
identifying a graphical image that
represents the action. A command might not have an Icon.
Access Key
A key combination selected by the user agent that triggers the
command. A command might not have an Access Key.
Hidden State
Whether the command is hidden or not (basically, whether it
should be shown in menus).
Disabled State
Whether the command is relevant and can be triggered or not.
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
URL
to which to
navigate
, or a form submission.
These facets are exposed on elements using the
command
API
element
commandType
Exposes the
Type
facet of the command.
element
id
Exposes the
ID
facet of the command.
element
label
Exposes the
Label
facet of the command.
element
title
Exposes the
Hint
facet of the command.
element
icon
Exposes the
Icon
facet of the command.
element
accessKeyLabel
Exposes the
Access Key
facet of the command.
element
hidden
Exposes the
Hidden State
facet of the command.
element
disabled
Exposes the
Disabled State
facet of the command.
element
checked
Exposes the
Checked State
facet of the command.
element
click
()
Triggers the
Action
of the command.
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
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
IDL attribute on
option
and
command
elements.
The
icon
attribute must return the
absolute URL
of 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
IDL 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
IDL 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
IDL attribute on
input
and
command
elements.
The
ID
facet
is exposed by the
id
IDL attribute,
the
Hint
facet is exposed by
the
title
IDL attribute, the
AccessKey
facet is exposed by
the
accessKeyLabel
IDL
attribute, and the
Hidden
State
facet is exposed by the
hidden
IDL attribute.
document
commands
Returns an
HTMLCollection
of the elements in the
Document
that define commands and have IDs.
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
User agents may expose the
commands
whose
Hidden State
facet is false
(visible), e.g. in the user agent's menu bar. User agents are
encouraged to do this especially for commands that have
Access Keys
, as a way to
advertise those keys to the user.
4.11.5.1
Using the
element to define a command
Status:
Last call for comments
An
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
IDL
attribute.
The
Hint
of the command
is the value of the
title
attribute
of the element. If the attribute is not present, the
Hint
is the empty string.
The
Icon
of the command
is the
absolute URL
obtained from
resolving
the value of the
src
attribute of the first
img
element descendant of the element, relative to that
element, if there is such an element and resolving its attribute is
successful. Otherwise, there is no
Icon
for the command.
The
AccessKey
of the
command is the element's
assigned access key
, if
any.
The
Hidden State
of the command is true (hidden) if the element has a
hidden
attribute, and false
otherwise.
The
Disabled
State
facet of the command is 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.
4.11.5.2
Using the
button
element to define a command
Status:
Last call for comments
button
element always
defines a command
The
Type
ID
Label
Hint
Icon
Access Key
Hidden State
Checked State
, and
Action
facets of the command are
determined
as for
elements
(see the previous section).
The
Disabled
State
of the command mirrors the
disabled
state of the button.
4.11.5.3
Using the
input
element to define a command
Status:
Last call for comments
An
input
element whose
type
attribute is in one of the
Submit Button
Reset Button
Image Button
Button
Radio Button
, or
Checkbox
states
defines a command
The
Type
of the command
is "radio" if the
type
attribute is in the
Radio
Button
state, "checkbox" if the
type
attribute is in the
Checkbox
state, 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, locale-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 is a
labeled
control
, the
textContent
of the first
label
element in
tree order
whose
labeled control
is the element in question is the
Label
(in DOM terms, this is 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.
If the element's
type
attribute is in the
Image
Button
state, and the element has a
src
attribute, and that attribute's
value can be successfully
resolved
relative to the element, then the
Icon
of the command is the
absolute URL
obtained from resolving that attribute
that way. Otherwise, there is no
Icon
for the command.
The
AccessKey
of the
command is the element's
assigned access key
, if
any.
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 mirrors the
disabled
state of the
control.
The
Checked State
of the command is true if the command is of
Type
"radio" or "checkbox" and the
element is
checked
attribute, and false otherwise.
The
Action
of the
command, if the element has a defined
activation
behavior
, is to
run synthetic click activation
steps
on the element. Otherwise, it is just to
fire a
click
event
at the
element.
4.11.5.4
Using the
option
element to define a command
Status:
Last call for comments
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
IDL attribute if there isn'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
AccessKey
of the
command is the element's
assigned access key
, if
any.
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 is
disabled
or if its
nearest ancestor
select
element is
disabled
, and false
otherwise.
The
Checked State
of the command is true (checked) if the element's
selectedness
is true, and
false otherwise.
The
Action
of the
command depends on its
Type
. If the command is of
Type
"radio" then it must
pick
the
option
element. Otherwise, it must
toggle
the
option
element.
4.11.5.5
Using the
command
element to define
a command
Status:
Last call for comments
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 URL
obtained from
resolving
the value of the element's
icon
attribute, relative to the
element, if it has such an attribute and resolving it is
successful. Otherwise, there is no
Icon
for the command.
The
AccessKey
of the
command is the element's
assigned access key
, if
any.
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 a
disabled
attribute, 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, if the element has a defined
activation
behavior
, is to
run synthetic click activation
steps
on the element. Otherwise, it is just to
fire a
click
event
at the
element.
4.11.5.6
Using the
accesskey
attribute on a
label
element to define a command
Status:
Last call for comments
label
element that has an
assigned access
key
and a
labeled control
and whose
labeled control
defines a
command
, itself
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
IDL
attribute.
The
Hint
of the command
is the value of the
title
attribute
of the element.
There is no
Icon
for the
command.
The
AccessKey
of the
command is the element's
assigned access key
The
Hidden State
Disabled State
, and
Action
facets of the
command are the same as the respective facets of the element's
labeled control
The
Checked State
of the command is always false. (The command is never checked.)
4.11.5.7
Using the
accesskey
attribute on a
legend
element to define a command
Status:
Last call for comments
legend
element that has an
assigned access
key
and is a child of a
fieldset
element that
has a descendant that is not a descendant of the
legend
element and is neither a
label
element nor a
legend
element but that
defines a command
, itself
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
IDL
attribute.
The
Hint
of the command
is the value of the
title
attribute
of the element.
There is no
Icon
for the
command.
The
AccessKey
of the
command is the element's
assigned access key
The
Hidden State
Disabled State
, and
Action
facets of the
command are the same as the respective facets of the first element
in
tree order
that is a descendant of the parent of the
legend
element that
defines a command
but is not a
descendant of the
legend
element and is neither a
label
nor a
legend
element.
The
Checked State
of the command is always false. (The command is never checked.)
4.11.5.8
Using the
accesskey
attribute to define a command on other elements
Status:
Last call for comments
An element that has an
assigned access key
defines a command
If one of the other sections that define elements that
define commands
define that this
element
defines a command
, then
that section applies to this element, and this section does
not. Otherwise, this section applies to that element.
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
depends on the element. If the element is a
labeled
control
, the
textContent
of the first
label
element in
tree order
whose
labeled control
is the element in question is the
Label
(in DOM terms, this is the
string given by
element
.labels[0].textContent
). Otherwise, the
Label
is the
textContent
of the element itself.
The
Hint
of the command
is the value of the
title
attribute
of the element. If the attribute is not present, the
Hint
is the empty string.
There is no
Icon
for the
command.
The
AccessKey
of the
command is the element's
assigned access key
The
Hidden State
of the command is true (hidden) if the element has a
hidden
attribute, and false
otherwise.
The
Disabled
State
facet of the command is 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 run the following steps:
If the element is
focusable
, run the
focusing steps
for the element.
If the element has a defined
activation behavior
run synthetic click activation steps
on the
element.
Otherwise, if the element does not have a defined
activation behavior
fire a
click
event
at the element.
4.12
Links
Status:
Last call for comments
4.12.1
Hyperlink elements
Status:
Last call for comments
The
area
, and
link
elements can, in certain situations described in the definitions of
those elements, represent
hyperlinks
The
href
attribute on a hyperlink element must have a value that is a
valid URL
. This URL is the
destination
resource
of the hyperlink.
The
href
attribute on
and
area
elements is not required; when
those elements do not have
href
attributes they do not
represent hyperlinks.
The
href
attribute on the
link
element
is
required, but whether a
link
element represents a hyperlink or not depends on
the value of the
rel
attribute
of that element.
The
target
attribute, if present, must be a
valid browsing context name
or keyword
. It gives the name of the
browsing
context
that will be used.
User agents use
this name when
following hyperlinks
The
ping
attribute, if
present, gives the URLs of the resources that are interested in
being notified if the user follows the hyperlink. The value must be
set of space-separated tokens
, each of which must be a
valid URL
The
value is used by the user agent for
hyperlink
auditing
For
and
area
elements that represent
hyperlinks, the relationship between the document containing the
hyperlink and the destination resource indicated by the hyperlink is
given by the value of the element's
rel
attribute, which
must be a
set of space-separated tokens
. The
allowed values and their meanings
are defined
below. The
rel
attribute has
no default value. If the attribute is omitted or if none of the
values in the attribute are recognized by the user agent, then the
document has no particular relationship with the destination
resource other than there being a hyperlink between the two.
The
media
attribute describes for which media the target document was
designed. It is purely advisory. The value must be a
valid
media query
. The default, if the
media
attribute is omitted, is
all
".
The
hreflang
attribute on hyperlink elements, if present, gives the language of
the linked resource. It is purely advisory. The value must be a
valid BCP 47 language code.
[BCP47]
User agents must not consider this attribute
authoritative — upon fetching the resource, user agents must
use only language information associated with the resource to
determine its language, not metadata included in the link to the
resource.
The
type
attribute, if present, gives the
MIME type
of the
linked resource. It is purely advisory. The value must be a
valid MIME type
User agents must
not consider the
type
attribute authoritative — upon fetching the resource, user
agents must not use metadata included in the link to the resource to
determine its type.
4.12.2
Following hyperlinks
Status:
Last call for comments
When a user
follows a hyperlink
, the user agent must
resolve
the
URL
given by the
href
attribute
of that hyperlink, relative to the hyperlink element, and if that is
successful, must
navigate
browsing
context
to the resulting
absolute URL
. In the
case of server-side image maps, the URL of the hyperlink must
further have its
hyperlink suffix
appended to it.
If
resolving
the
URL
fails, the user agent may report the error to the
user in a user-agent-specific manner, may navigate to an error page
to report the error, or may ignore the error and do nothing.
If the user indicated a specific
browsing context
when following the hyperlink, or if the user agent is configured to
follow hyperlinks by navigating a particular browsing context, then
that must be the
browsing context
that is
navigated.
Otherwise, if the hyperlink element is an
or
area
element that has a
target
attribute, then the
browsing context
that is navigated must be chosen by
applying
the rules for choosing a browsing context given a
browsing context name
, using the value of the
target
attribute as the
browsing context name. If these rules result in the creation of a
new
browsing context
, it must be navigated with
replacement enabled
Otherwise, if the hyperlink element is a
sidebar hyperlink
and the user
agent implements a feature that can be considered a secondary
browsing context, such a secondary browsing context may be selected
as the browsing context to be navigated.
Otherwise, if the hyperlink element is an
or
area
element with no
target
attribute, but one of
the child nodes of
the
head
element
is a
base
element with a
target
attribute, then the browsing
context that is navigated must be chosen by applying
the rules
for choosing a browsing context given a browsing context name
using the value of the
target
attribute of the first such
base
element as the
browsing context name. If these rules result in the creation of a
new
browsing context
, it must be navigated with
replacement enabled
Otherwise, the browsing context that must be navigated is the
same browsing context as the one which the hyperlink element itself
is in.
The navigation must be done with the
browsing
context
that contains the
Document
object with
which the hyperlink's element in question is associated as the
source browsing context
4.12.2.1
Hyperlink auditing
Status:
Last call for comments.
ISSUE-1
(PINGPOST) and
ISSUE-2
(PINGUI) block progress to Last Call
If an
or
area
hyperlink element has a
ping
attribute, and the
user follows the hyperlink, and the hyperlink's
URL
can
be
resolved
, relative to the
hyperlink element, without failure, then the user agent must take
the
ping
attribute's value,
split that string on
spaces
resolve
each
resulting token relative to the hyperlink element, and then should
send a request (as described below) to each of the resulting
absolute URLs
. (Tokens that fail to
resolve are ignored.) This may be done in parallel with the primary
request, and is independent of the result of that request.
User agents should allow the user to adjust this behavior, for
example in conjunction with a setting that disables the sending of
HTTP
Referer
(sic) headers. Based
on the user's preferences, UAs may either
ignore
the
ping
attribute altogether,
or selectively ignore URLs in the list (e.g. ignoring any
third-party URLs).
For URLs that are HTTP URLs, the requests must be performed by
fetching
the specified URLs using the
POST method, with an entity body with the
MIME type
text/ping
consisting of the four-character string
PING
", from the
origin
of the
Document
containing the
hyperlink
All relevant cookie and HTTP
authentication headers must be included in the request. Which other
headers are required depends on the URLs involved.
If both the
address
of the
Document
object containing the hyperlink being
audited and the ping URL have the
same origin
The request must include a
Ping-From
HTTP header with, as its
value, the
address
of
the document containing the hyperlink, and a
Ping-To
HTTP header with, as its value,
the address of the
absolute URL
of the target of the
hyperlink. The request must not include a
Referer
(sic) HTTP header.
Otherwise, if the origins are different, but the document
containing the hyperlink being audited was not retrieved over an
encrypted connection
The request must include a
Referer
(sic) HTTP header with, as its
value, the
current
address
of the document containing the hyperlink, a
Ping-From
HTTP header with the same
value, and a
Ping-To
HTTP header
with, as its value, the address of the target of the
hyperlink.
Otherwise, the origins are different and the document
containing the hyperlink being audited was retrieved over an
encrypted connection
The request must include a
Ping-To
HTTP header with, as its value,
the address of the target of the hyperlink. The request must
neither include a
Referer
(sic)
HTTP header nor include a
Ping-From
HTTP header.
To save bandwidth, implementors might also wish to
consider omitting optional headers such as
Accept
from
these requests.
User agents must, unless otherwise specified by the user, honor
the HTTP headers (including, in particular, redirects and HTTP
cookie headers), but must ignore any entity bodies returned in the
responses. User agents may close the connection prematurely once
they start receiving an entity body.
[COOKIES]
For URLs that are not HTTP URLs, the requests must be performed
by
fetching
the specified URL normally,
and discarding the results.
When the
ping
attribute is
present, user agents should clearly indicate to the user that
following the hyperlink will also cause secondary requests to be
sent in the background, possibly including listing the actual target
URLs.
For example, a visual user agent could include
the hostnames of the target ping URLs along with the hyperlink's
actual URL in a status bar or tooltip.
The
ping
attribute is redundant
with pre-existing technologies like HTTP redirects and JavaScript
in allowing Web pages to track which off-site links are most
popular or allowing advertisers to track click-through rates.
However, the
ping
attribute
provides these advantages to the user over those alternatives:
It allows the user to see the final target URL
unobscured.
It allows the UA to inform the user about the out-of-band
notifications.
It allows the user to disable the notifications without losing
the underlying link functionality.
It allows the UA to optimize the use of available network
bandwidth so that the target page loads faster.
Thus, while it is possible to track users without this feature,
authors are encouraged to use the
ping
attribute so that the user
agent can make the user experience more transparent.
4.12.3
Link types
Status:
Last call for comments
The following table summarizes the link types that are defined by
this specification. This table is non-normative; the actual
definitions for the link types are given in the next few
sections.
In this section, the term
referenced document
refers to
the resource identified by the element representing the link, and
the term
current document
refers to the resource within
which the element representing the link finds itself.
To determine which link types apply to a
link
, or
area
element, the element's
rel
attribute must be
split on spaces
. The resulting tokens are the link
types that apply to that element.
Except where otherwise specified, a keyword must not be specified
more than once per
rel
attribute.
The link types that contain no U+003A COLON characters (:),
including all those defined in this specification, are
ASCII
case-insensitive
values
, and must be
compared as such
Thus,
rel="next"
is the
same as
rel="NEXT"
Link type
Effect on...
Brief description
link
and
area
alternate
Hyperlink
Hyperlink
Gives alternate representations of the current document.
archives
Hyperlink
Hyperlink
Provides a link to a collection of records, documents, or other materials of historical interest.
author
Hyperlink
Hyperlink
Gives a link to the current document's author.
not allowed
Hyperlink
Gives the permalink for the nearest ancestor section.
external
not allowed
Hyperlink
Indicates that the referenced document is not part of the same site as the current document.
first
Hyperlink
Hyperlink
Indicates that the current document is a part of a series, and that the first document in the series is the referenced document.
help
Hyperlink
Hyperlink
Provides a link to context-sensitive help.
icon
External Resource
not allowed
Imports an icon to represent the current document.
index
Hyperlink
Hyperlink
Gives a link to the document that provides a table of contents or index listing the current document.
last
Hyperlink
Hyperlink
Indicates that the current document is a part of a series, and that the last document in the series is the referenced document.
license
Hyperlink
Hyperlink
Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
next
Hyperlink
Hyperlink
Indicates that the current document is a part of a series, and that the next document in the series is the referenced document.
nofollow
not allowed
Hyperlink
Indicates that the current document's original author or publisher does not endorse the referenced document.
noreferrer
not allowed
Hyperlink
Requires that the user agent not send an HTTP
Referer
(sic) header if the user follows the hyperlink.
pingback
External Resource
not allowed
Gives the address of the pingback server that handles pingbacks to the current document.
prefetch
External Resource
not allowed
Specifies that the target resource should be preemptively cached.
prev
Hyperlink
Hyperlink
Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document.
Hyperlink
Hyperlink
Gives a link to a resource that can be used to search through the current document and its related pages.
stylesheet
External Resource
not allowed
Imports a stylesheet.
sidebar
Hyperlink
Hyperlink
Specifies that the referenced document, if retrieved, is intended to be shown in the browser's sidebar (if it has one).
tag
Hyperlink
Hyperlink
Gives a tag (identified by the given address) that applies to the current document.
up
Hyperlink
Hyperlink
Provides a link to a document giving the context for the current document.
Some of the types described below list synonyms for these
values. These
are to be handled as
specified by user agents, but
must not be used in
documents.
4.12.3.1
Link type "
alternate
Status:
Last call for comments
The
alternate
keyword may be
used with
link
, and
area
elements. For
link
elements, if the
rel
attribute does not also contain the
keyword
stylesheet
, it creates a
hyperlink
; but if it
does
also contain the keyword
stylesheet
, the
alternate
keyword instead modifies the
meaning of the
stylesheet
keyword in the way described for that keyword, and the rest of this
subsection doesn't apply.
The
alternate
keyword
indicates that the referenced document is an alternate
representation of the current document.
The nature of the referenced document is given by the
media
hreflang
, and
type
attributes.
If the
alternate
keyword is
used with the
media
attribute, it indicates that the referenced document is intended for
use with the media specified.
If the
alternate
keyword is
used with the
hreflang
attribute, and that attribute's value differs from the
root
element
's
language
, it indicates that the
referenced document is a translation.
If the
alternate
keyword is
used with the
type
attribute, it indicates that the referenced document is a
reformulation of the current document in the specified format.
The
media
hreflang
, and
type
attributes can be combined
when specified with the
alternate
keyword.
For example, the following link is a French translation that
uses the PDF format:
If the
alternate
keyword is
used with the
type
attribute set to the value
application/rss+xml
or the value
application/atom+xml
, then it
indicates that the referenced document is a syndication feed (though
not necessarily syndicating exactly the same content as the current
page).
The first
link
, or
area
element in the document (in tree order) with the
alternate
keyword used with the
type
attribute set to the value
application/rss+xml
or the value
application/atom+xml
must be treated as the default
syndication feed for the purposes of feed autodiscovery.
The following
link
element gives the syndication
feed for the current page:
The following extract offers various different syndication
feeds:
You can access the planets database using Atom feeds:
The
alternate
link
relationship is transitive — that is, if a document links to
two other documents with the link type "
alternate
", then, in addition to
implying that those documents are alternative representations of the
first document, it is also implying that those two documents are
alternative representations of each other.
4.12.3.2
Link type "
archives
Status:
Last call for comments
The
archives
keyword may be
used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
archives
keyword indicates
that the referenced document describes a collection of records,
documents, or other materials of historical interest.
A blog's index page could link to an index of the
blog's past posts with
rel="archives"
Synonyms
: For historical reasons, user agents
must also treat the keyword "
archive
" like the
archives
keyword.
4.12.3.3
Link type "
author
Status:
Last call for comments
The
author
keyword may be
used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
For
and
area
elements, the
author
keyword indicates that the
referenced document provides further information about the author of
the nearest
article
element ancestor of the element
defining the hyperlink, if there is one, or of the page as a whole,
otherwise.
For
link
elements, the
author
keyword indicates that the
referenced document provides further information about the author
for the page as a whole.
The "referenced document" can be, and often is, a
mailto:
URL giving the e-mail address of the
author.
[MAILTO]
Synonyms
: For historical reasons, user agents
must also treat
link
, and
area
elements that have a
rev
attribute with the value "
made
" as having the
author
keyword specified as a link
relationship.
4.12.3.4
Link type "
Status:
Last call for comments
The
keyword may be
used with
and
area
elements.
The
keyword gives a
permalink for the nearest ancestor
article
element of
the linking element in question, or of
the section the linking element is most
closely associated with
, if there are no ancestor
article
elements.
The following snippet has three permalinks. A user agent could
determine which permalink applies to which part of the spec by
looking at where the permalinks are given.
...
Example of permalinks
First example
This permalink applies to
only the content from the first H2 to the second H2. The DIV isn't
exactly that section, but it roughly corresponds to it.
Second example
This permalink applies to
the outer ARTICLE element (which could be, e.g., a blog post).
This permalink applies to
the inner ARTICLE element (which could be, e.g., a blog comment).
...
4.12.3.5
Link type "
external
Status:
Last call for comments
The
external
keyword may be
used with
and
area
elements.
The
external
keyword indicates
that the link is leading to a document that is not part of the site
that the current document forms a part of.
4.12.3.6
Link type "
help
Status:
Last call for comments
The
help
keyword may be used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
For
and
area
elements, the
help
keyword indicates that the referenced
document provides further help information for the parent of the
element defining the hyperlink, and its children.
In the following example, the form control has associated
context-sensitive help. The user agent could use this information,
for example, displaying the referenced document if the user presses
the "Help" or "F1" key.
For
link
elements, the
help
keyword indicates that the referenced
document provides help for the page as a whole.
4.12.3.7
Link type "
icon
Status:
Last call for comments
The
icon
keyword may be used with
link
elements, for which it creates an
external resource link
The specified resource is an icon representing the page or site,
and should be used by the user agent when representing the page in
the user interface.
Icons could be auditory icons, visual icons, or other kinds of
icons.
If multiple icons are provided, the user
agent must select the most appropriate icon according to the
type
media
, and
sizes
attributes. If there are
multiple equally appropriate icons, user agents must use the last
one declared in
tree order
. If the user agent tries to
use an icon but that icon is determined, upon closer examination, to
in fact be inappropriate (e.g. because it uses an unsupported
format), then the user agent must try the next-most-appropriate icon
as determined by the attributes.
There is no default type for resources given by the
icon
keyword. However, for the purposes of
determining the type of the
resource
, user agents must expect the resource to be an image.
The
sizes
attribute gives the sizes of icons for visual media.
If specified, the attribute must have a value that is an
unordered set of unique space-separated tokens
. The
values must all be either
any
or a value that consists of
two
valid non-negative
integers
that do not have a leading U+0030 DIGIT ZERO (0)
character and that are separated by a single U+0078 LATIN SMALL
LETTER X character (x).
The keywords represent icon sizes.
To parse and process the attribute's value, the user agent must
first
split the attribute's
value on spaces
, and must then parse each resulting keyword
to determine what it represents.
The
any
keyword
represents that the resource contains a scalable icon, e.g. as
provided by an SVG image.
Other keywords must be further parsed as follows to determine
what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN
SMALL LETTER X character (x), then this keyword doesn't represent
anything. Abort these steps for that keyword.
Let
width string
be the string before
the "
".
Let
height string
be the string after the
".
If either
width string
or
height string
start with a U+0030 DIGIT ZERO (0)
character or contain any characters other than characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), then this
keyword doesn't represent anything. Abort these steps for that
keyword.
Apply the
rules for parsing non-negative
integers
to
width string
to obtain
width
Apply the
rules for parsing non-negative
integers
to
height string
to obtain
height
The keyword represents that the resource contains a bitmap
icon with a width of
width
device pixels and a
height of
height
device pixels.
The keywords specified on the
sizes
attribute must not represent
icon sizes that are not actually available in the linked
resource.
If the attribute is not specified, then the user agent must
assume that the given icon is appropriate, but less appropriate than
an icon of a known and appropriate size.
The following snippet shows the top part of an application with
several icons.
...
4.12.3.8
Link type "
license
Status:
Last call for comments
The
license
keyword may be used
with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
license
keyword indicates
that the referenced document provides the copyright license terms
under which the main content of the current document is
provided.
This specification does not specify how to distinguish between
the main content of a document and content that is not deemed to be
part of that main content. The distinction should be made clear to
the user.
Consider a photo sharing site. A page on that site might
describe and show a photograph, and the page might be marked up as
follows:
Kissat
One of them has six toes!
In this case the
license
applies to just the photo (the main content of the document), not
the whole document. In particular not the design of the page
itself, which is covered by the copyright given at the bottom of
the document. This could be made clearer in the styling
(e.g. making the license link prominently positioned near the
photograph, while having the page copyright in light small text at
the foot of the page.
Synonyms
: For historical reasons, user agents
must also treat the keyword "
" like
the
license
keyword.
4.12.3.9
Link type "
nofollow
Status:
Last call for comments
The
nofollow
keyword may be
used with
and
area
elements.
The
nofollow
keyword indicates
that the link is not endorsed by the original author or publisher of
the page, or that the link to the referenced document was included
primarily because of a commercial relationship between people
affiliated with the two pages.
4.12.3.10
Link type "
noreferrer
Status:
Last call for comments
The
noreferrer
keyword may be
used with
and
area
elements.
It indicates that no referrer information is to be leaked when
following the link.
If a user agent follows a link defined by an
or
area
element that has the
noreferrer
keyword, the user agent
must not include a
Referer
(sic)
HTTP header (
or
equivalent
for other protocols) in the request.
This keyword also
causes the
opener
attribute to remain null
if the
hyperlink creates a new
browsing context
4.12.3.11
Link type "
pingback
Status:
Last call for comments
The
pingback
keyword may be
used with
link
elements, for which it creates an
external resource link
For the semantics of the
pingback
keyword, see the Pingback 1.0
specification.
[PINGBACK]
4.12.3.12
Link type "
prefetch
Status:
Last call for comments
The
prefetch
keyword may be
used with
link
elements, for which it creates an
external resource link
The
prefetch
keyword indicates
that preemptively fetching and caching the specified resource is
likely to be beneficial, as it is highly likely that the user will
require this resource.
There is no default type for resources given by the
prefetch
keyword.
4.12.3.13
Link type "
Status:
Last call for comments
The
keyword may be used
with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
keyword indicates that
the referenced document provides an interface specifically for
searching the document and its related resources.
OpenSearch description documents can be used with
link
elements and the
link type to enable user agents to
autodiscover search interfaces.
[OPENSEARCH]
4.12.3.14
Link type "
stylesheet
Status:
Last call for comments
The
stylesheet
keyword may be
used with
link
elements, for which it creates an
external resource link
that
contributes to the
styling processing model
The specified resource is a resource that describes how to
present the document. Exactly how the resource is to be processed
depends on the actual type of the resource.
If the
alternate
keyword is
also specified on the
link
element, then
the link
is an alternative stylesheet
; in this case, the
title
attribute must be specified on the
link
element, with a non-empty value.
The default type for resources given by the
stylesheet
keyword is
text/css
Quirk
: If the document has been set to
quirks mode
and the
Content-Type metadata
of the external
resource is not a supported style sheet type, the user agent must
instead assume it to be
text/css
4.12.3.15
Link type "
sidebar
Status:
Last call for comments
The
sidebar
keyword may be used
with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
sidebar
keyword indicates
that the referenced document, if retrieved, is intended to be shown
in a
secondary browsing context
(if possible), instead
of in the current
browsing context
hyperlink element
with the
sidebar
keyword specified is a
sidebar hyperlink
4.12.3.16
Link type "
tag
Status:
Last call for comments
The
tag
keyword may be used
with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
tag
keyword indicates that the
tag
that the referenced document represents applies to the
current document.
Since it indicates that the tag
applies to the
current document
, it would be inappropriate to use this keyword
in the markup of a
tag cloud
, which lists
the popular tag across a set of pages.
4.12.3.17
Hierarchical link types
Status:
Last call for comments
Some documents form part of a hierarchical structure of
documents.
A hierarchical structure of documents is one where each document
can have various subdocuments. The document of which a document is a
subdocument is said to be the document's
parent
. A document
with no parent forms the top of the hierarchy.
A document may be part of multiple hierarchies.
4.12.3.17.1
Link type "
index
Status:
Last call for comments
The
index
keyword may be used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
index
keyword indicates that
the document is part of a hierarchical structure, and that the link
is leading to the document that is the top of the hierarchy. It
conveys more information when used with the
up
keyword (q.v.).
Synonyms
: For historical reasons, user agents
must also treat the keywords "
top
", "
contents
", and "
toc
" like the
index
keyword.
4.12.3.17.2
Link type "
up
Status:
Last call for comments
The
up
keyword may be used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
up
keyword indicates that the
document is part of a hierarchical structure, and that the link is
leading to a document that is an ancestor of the current
document.
The
up
keyword may be repeated within
rel
attribute to indicate
the hierarchical distance from the current document to the
referenced document. If it occurs only once, then the link is
leading to the current document's parent; each additional occurrence
of the keyword represents one further level. If the
index
keyword is also present, then the
number of
up
keywords is the depth of
the current page relative to the top of the hierarchy. Only one link
is created for the set of one or more
up
keywords and, if present, the
index
keyword.
If the page is part of multiple hierarchies, then they should be
described in different
paragraphs
User agents
must scope any interpretation of the
up
and
index
keywords together
indicating the depth of the hierarchy to the
paragraph
in which the link finds itself, if any, or to the document
otherwise.
When two links have both the
up
and
index
keywords specified together in
the same scope and contradict each other by having a different
number of
up
keywords, the link with the
greater number of
up
keywords must be
taken as giving the depth of the document.
This can be used to mark up a navigation style sometimes known
as bread crumbs. In the following example, the current page can be
reached via two paths.
The
relList
IDL
attribute (e.g. on the
element) does not currently
represent multiple
up
keywords (the
interface hides duplicates).
4.12.3.18
Sequential link types
Status:
Last call for comments
Some documents form part of a sequence of documents.
A sequence of documents is one where each document can have a
previous sibling
and a
next sibling
. A document
with no previous sibling is the start of its sequence, a document
with no next sibling is the end of its sequence.
A document may be part of multiple sequences.
4.12.3.18.1
Link type "
first
Status:
Last call for comments
The
first
keyword may be used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
first
keyword indicates that
the document is part of a sequence, and that the link is leading to
the document that is the first logical document in the sequence.
Synonyms
: For historical reasons, user agents
must also treat the keywords "
begin
" and
start
" like the
first
keyword.
4.12.3.18.2
Link type "
last
Status:
Last call for comments
The
last
keyword may be used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
last
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the last logical document in the sequence.
Synonyms
: For historical reasons, user agents
must also treat the keyword "
end
" like the
last
keyword.
4.12.3.18.3
Link type "
next
Status:
Last call for comments
The
next
keyword may be used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
next
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the next logical document in the sequence.
4.12.3.18.4
Link type "
prev
Status:
Last call for comments
The
prev
keyword may be used with
link
, and
area
elements. For
link
elements, it creates a
hyperlink
The
prev
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the previous logical document in the sequence.
Synonyms
: For historical reasons, user agents
must also treat the keyword "
previous
" like
the
prev
keyword.
4.12.3.19
Other link types
Status:
Last call for comments
Extensions to the predefined
set of link types
may be registered in the
WHATWG Wiki
RelExtensions page
[WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki RelExtensions page at any
time to add a type. Extension types must be specified with the
following information:
Keyword
The actual value being defined. The value should not be
confusingly similar to any other defined value (e.g. differing
only in case).
If the value contains a U+003A COLON character (:), it must
also be an
absolute URL
Effect on...
link
One of the following:
not allowed
The keyword is not allowed to be specified on
link
elements.
Hyperlink
The keyword may be specified on a
link
element;
it creates a
hyperlink
link
External Resource
The keyword may be specified on a
link
element;
it creates a
external
resource link
Effect on...
and
area
One of the following:
not allowed
The keyword is not allowed to be specified on
and
area
elements.
Hyperlink
The keyword may be specified on
and
area
elements.
Brief description
A short non-normative description of what the keyword's
meaning is.
Specification
A link to a more detailed description of the keyword's
semantics and requirements. It could be another page on the Wiki,
or a link to an external page.
Synonyms
A list of other keyword values that have exactly the same
processing requirements. Authors should not use the values defined
to be synonyms, they are only intended to allow user agents to
support legacy content. Anyone may remove synonyms that are not
used in practice; only names that need to be processed as synonyms
for compatibility with legacy content are to be registered in this
way.
Status
One of the following:
Proposed
The keyword has not received wide peer review and
approval. Someone has proposed it and is, or soon will be, using
it.
Ratified
The keyword has received wide peer review and approval. It
has a specification that unambiguously defines how to handle
pages that use the keyword, including when they use it in
incorrect ways.
Discontinued
The keyword has received wide peer review and it has been
found wanting. Existing pages are using this keyword, but new
pages should avoid it. The "brief description" and
"specification" entries will give details of what authors should
use instead, if anything.
If a keyword is found to be redundant with existing values, it
should be removed and listed as a synonym for the existing
value.
If a keyword is registered in the "proposed" state for a
period of a month or more without being used or specified, then it
may be removed from the registry.
If a keyword is added with the "proposed" status and found to
be redundant with existing values, it should be removed and listed
as a synonym for the existing value. If a keyword is added with
the "proposed" status and found to be harmful, then it should be
changed to "discontinued" status.
Anyone can change the status at any time, but should only do so
in accordance with the definitions above.
Conformance checkers must use the information given on the WHATWG
Wiki RelExtensions page to establish if a value is allowed or not:
values defined in this specification or marked as "proposed" or
"ratified" must be accepted when used on the elements for which they
apply as described in the "Effect on..." field, whereas values
marked as "discontinued" or not listed in either this specification
or on the aforementioned page must be rejected as invalid.
Conformance checkers may cache this information (e.g. for
performance reasons or to avoid the use of unreliable network
connectivity).
When an author uses a new type not defined by either this
specification or the Wiki page, conformance checkers should offer to
add the value to the Wiki, with the details described above, with
the "proposed" status.
Types defined as extensions in the
WHATWG Wiki
RelExtensions page
with the status "proposed" or "ratified" may
be used with the
rel
attribute on
link
, and
area
elements in
accordance to the "Effect on..." field.
[WHATWGWIKI]
4.13
Common idioms without dedicated elements
Status:
Last call for comments.
ISSUE-89
(idioms) blocks progress to Last Call
4.13.1
Tag clouds
Status:
Last call for comments
This specification does not define any markup
specifically for marking up lists of keywords that apply to a group
of pages (also known as
tag clouds
). In general, authors are
encouraged to either mark up such lists using
ul
elements with explicit inline counts that are then hidden and turned
into a presentational effect using a style sheet, or to use SVG.
Here, three tags are included in a short tag cloud:
...
The actual frequency of each tag is given using the
title
attribute. A CSS style sheet is
provided to convert the markup into a cloud of differently-sized
words, but for user agents that do not support CSS or are not
visual, the markup contains annotations like "(popular)" or
"(rare)" to categorize the various tags by frequency, thus enabling
all users to benefit from the information.
The
ul
element is used (rather than
ol
) because the order is not particularly important:
while the list is in fact ordered alphabetically, it would convey
the same information if ordered by, say, the length of the tag.
The
tag
rel
-keyword is
not
used
on these
elements because they do not represent tags
that apply to the page itself; they are just part of an index
listing the tags themselves.
4.13.2
Conversations
Status:
Last call for comments
This specification does not define a specific element for marking
up conversations, meeting minutes, chat transcripts, dialogues in
screenplays, instant message logs, and other situations where
different players take turns in discourse.
Instead, authors are encouraged to mark up conversations using
elements and punctuation. Authors who need to mark
the speaker for styling purposes are encouraged to use
span
or
. Paragraphs with their text
wrapped in the
element can be used for marking up
stage directions.
This example demonstrates this using an extract from Abbot and
Costello's famous sketch,
Who's on first
Costello: Look, you gotta first baseman?
Abbott: Certainly.
Costello: Who's playing first?
Abbott: That's right.
Costello becomes exasperated.
Costello: When you pay off the first baseman every month, who gets the money?
Abbott: Every dollar of it.
The following extract shows how an IM conversation log could be
marked up.
egof I'm not that nerdy, I've only seen 30% of the star trek episodes
kaj if you know what percentage of the star trek episodes you have seen, you are inarguably nerdy
egof it's unarguably
* kaj blinks
kaj you are not helping your case
4.13.3
Footnotes
Status:
Last call for comments
HTML does not have a dedicated mechanism for marking up
footnotes. Here are the recommended alternatives.
For short inline annotations, the
title
attribute should be used.
In this example, two parts of a dialogue are annotated with
footnote-like content using the
title
attribute.
Customer: Hello! I wish to register a complaint. Hello. Miss?
Shopkeeper:
>Watcha mean, miss?
Customer: Uh, I'm sorry, I have a cold. I wish to make a complaint.
Shopkeeper: Sorry, Announcer: Number 16: The hand. Interviewer: Good evening. I have with me in the studio tonight Norman: I don't. [1] Interviewer: You told me you did! [1] This is, naturally, a lie, Customer: I will not buy this record, it is scratched. Shopkeeper: I'm sorry? Customer: I will not buy this record, it is scratched. Shopkeeper: No no no, this's'a tobacconist's. 1. Assumed. 2. Footwork impeccable. 3. Quality described as "well". 4. A lot.
>we're
closing for lunch.
For longer annotations, the
element should be
used, pointing to an element later in the document. The convention
is that the contents of the link be a number in square brackets.
In this example, a footnote in the dialogue links to a paragraph
below the dialogue. The paragraph then reciprocally links back to the
dialogue, allowing the user to return to the location of the
footnote.
Mr Norman St John Polevaulter, who for the past few years has been
contradicting people. Mr Polevaulter, why do you
contradict people?
...
but paradoxically if it were true he could not say so without
contradicting the interviewer and thus making it false.
For side notes, longer annotations that apply to entire sections
of the text rather than just specific words or sentences, the
aside
element should be used.
In this example, a sidebar is given after a dialogue, giving it
some context.
For figures or tables, footnotes can be included in the relevant
figcaption
or
caption
element, or in
surrounding prose.
In this example, a
table has cells with footnotes
that are given in prose. A
figure
element is used to
give a single legend to the combination of the table and its
footnotes. Activity Location Cost Dance Wherever possible £01 Routines, chorus scenes2 Undisclosed Undisclosed Dining3 Camelot Cost of ham, jam, and spam4
4.14
Matching HTML elements using selectors
Status:
Last call for comments
4.14.1
Case-sensitivity
Status:
Last call for comments
Attribute and element
names
of
HTML
elements
in
HTML documents
must be treated as
ASCII case-insensitive
Classes from the
class
attribute
of
HTML elements
in documents that are in
quirks
mode
must be treated as
ASCII
case-insensitive
Attribute selectors on an
HTML
element
in an
HTML
document
must treat the
values
of attributes with
the following names as
ASCII case-insensitive
accept
accept-charset
align
alink
axis
bgcolor
charset
checked
clear
codetype
color
compact
declare
defer
dir
direction
disabled
enctype
face
frame
hreflang
http-equiv
lang
language
link
media
method
multiple
nohref
noresize
noshade
nowrap
readonly
rel
rev
rules
scope
scrolling
selected
shape
target
text
type
valign
valuetype
vlink
All other attribute values on
HTML elements
must be
treated as
case-sensitive
4.14.2
Pseudo-classes
There are a number of dynamic selectors that can be used with
HTML. This section defines when these selectors match HTML
elements.
:link
:visited
All
elements that have an
href
attribute, all
area
elements that have an
href
attribute, and all
link
elements that have an
href
attribute, must match one of
:link
and
:visited
:active
The
:active
pseudo-class
must match the following elements between the time the user begins
to activate the element and the time the user stops activating
the element:
elements that have an
href
attribute
area
elements that have an
href
attribute
link
elements that have an
href
attribute
button
elements that are not
disabled
input
elements whose
type
attribute is in the
Submit Button
Image Button
Reset Button
, or
Button
state
command
elements that do not have a
disabled
attribute
any other element, if it is
specially
focusable
For example, if the user is using a keyboard to
push a
button
element by pressing the space bar, the
element would match this pseudo-class in between the time that the
element received the
keydown
event and the time the element received the
keyup
event.
:enabled
The
:enabled
pseudo-class
must match the following elements:
elements that have an
href
attribute
area
elements that have an
href
attribute
link
elements that have an
href
attribute
button
elements that are not
disabled
input
elements whose
type
attribute are not in the
Hidden
state and that
are not
disabled
select
elements that are not
disabled
textarea
elements that are not
disabled
option
elements that do not have a
disabled
attribute
command
elements that do not have a
disabled
attribute
li
elements that are children of
elements, and that have a child element that
defines a
command
, if the
first such element's
Disabled State
facet
is false (not disabled)
:disabled
The
:disabled
pseudo-class must match the following elements:
button
elements that are
disabled
input
elements whose
type
attribute are not in the
Hidden
state and that
are
disabled
select
elements that are
disabled
textarea
elements that are
disabled
option
elements that have a
disabled
attribute
command
elements that have a
disabled
attribute
li
elements that are children of
elements, and that have a child element that
defines a
command
, if the
first such element's
Disabled State
facet
is true (disabled)
:checked
The
:checked
pseudo-class
must match the following elements:
input
elements whose
type
attribute is in the
Checkbox
state and whose
checkedness
state is
true
input
elements whose
type
attribute is in the
Radio Button
state and whose
checkedness
state is
true
command
elements whose
type
attribute is in the
Checkbox
state
and that have a
checked
attribute
command
elements whose
type
attribute is in the
Radio
state and that
have a
checked
attribute
:indeterminate
The
:indeterminate
pseudo-class must match
input
elements whose
type
attribute is in the
Checkbox
state and whose
indeterminate
IDL
attribute is set to true.
:default
The
:default
pseudo-class
must match the following elements:
button
elements that are their form's
default button
input
elements whose
type
attribute is in the
Submit Button
or
Image Button
state, and that
are their form's
default button
:valid
The
:valid
pseudo-class
must match all elements that are
candidates for constraint validation
and that
satisfy their
constraints
:invalid
The
:invalid
pseudo-class
must match all elements that are
candidates for constraint validation
but that do not
satisfy their
constraints
:in-range
The
:in-range
pseudo-class must match all elements that are
candidates for
constraint validation
and that are neither
suffering
from an underflow
nor
suffering from an
overflow
:out-of-range
The
:out-of-range
pseudo-class must match all elements that are
candidates for
constraint validation
and that are
suffering from an
underflow
or
suffering from an overflow
:required
The
:required
pseudo-class must match the following elements:
input
elements that are
required
textarea
elements that have a
required
attribute
:optional
The
:optional
pseudo-class must match the following elements:
button
elements
input
elements that are not
required
select
elements
textarea
elements that do not have a
required
attribute
:read-only
:read-write
The
:read-write
pseudo-class must match the following elements:
input
elements to which the
readonly
attribute applies,
but that are not
immutable
(i.e. that do not have the
readonly
attribute specified
and that are not
disabled
textarea
elements that do not have a
readonly
attribute, and
that are not
disabled
any element that is
editable
The
:read-only
pseudo-class must match all other
HTML elements
Another section of this specification defines the
target element
used with the
:target
pseudo-class.
This specification does not define when an element
matches the
:hover
:focus
, or
:lang()
dynamic pseudo-classes, as
those are all defined in sufficient detail in a language-agnostic
fashion in the Selectors specification.
[SELECTORS]
4.15
Converting HTML to other formats
Status:
Last call for comments
4.15.1
Atom
Status:
Last call for comments.
ISSUE-86
(atom-id-stability) blocks progress to Last Call
Given a
Document
source
, a user
agent may run the following algorithm to
extract an Atom feed
. This is not the only algorithm
that can be used for this purpose; for instance, a user agent might
instead use the hAtom algorithm.
[HATOM]
If the
Document
source
does
not contain any
article
elements, then return nothing
and abort these steps. This algorithm can only be used with
documents that contain distinct articles.
Let
be an empty
XML
Document
object whose
address
is user-agent
defined.
Append a
feed
element in the
Atom namespace
to
For each
meta
element with a
name
attribute and a
content
attribute and whose
name
attribute's value is
author
, run the following substeps:
Append an
author
element in the
Atom namespace
to the root element of
Append a
name
element in the
Atom namespace
to the element created in the
previous step.
Append a text node whose data is the value of the
meta
element's
content
attribute to the element
created in the previous step.
If there is a
link
element whose
rel
attribute's value includes the
keyword
icon
, and that element also
has an
href
attribute whose
value successfully
resolves
relative to the
link
element, then append an
icon
element in the
Atom namespace
to
the root element of
whose contents is a text
node with its data set to the
absolute URL
resulting
from
resolving
the value of the
href
attribute.
Append an
id
element in the
Atom
namespace
to the root element of
whose contents is a text node with its data set to
the
document's current address
Optionally: Let
be a
link
element in the
Atom
namespace
. Add a
rel
attribute whose
value is the string "
self
" to
. Append a text node with its data set to the
(user-agent-defined)
address
of
to
. Append
to the root element
of
This step would be skipped when the document
has no convenient
address
. The presence of the
rel="self"
link is a "should"-level requirement in
the Atom specification.
Let
be a
link
element in the
Atom namespace
. Add a
rel
attribute whose value is the string "
alternate
" to
. If the
document being converted is an
HTML
document
, add a
type
attribute whose
value is the string "
text/html
" to
. Otherwise, the document being converted is an
XML document
; add a
type
attribute whose value is the string
application/xhtml+xml
" to
. Append a text node with its data set to
the document's current address
to
. Append
to the root element
of
Let
subheading text
be the empty
string.
Let
heading
be the first element of
heading content
whose nearest ancestor of
sectioning content
is
the body
element
, if any, or null if there is none.
Take the appropriate action from the following list, as
determined by the type of the
heading
element:
If
heading
is null
Let
heading text
be the
textContent
of
the
title
element
, if there is one, or the empty string
otherwise.
If
heading
is a
hgroup
element
If
heading
contains no child
h1
h6
elements, let
heading text
be the empty string.
Otherwise, let
headings list
be a list of
all the
h1
h6
element children
of
heading
, sorted first by descending
rank
and then in
tree order
(so
h1
s first, then
h2
s, etc, with each
group in the order they appear in the document). Then, let
heading text
be the
textContent
of
the first entry in
headings list
, and if
there are multiple entries, let
subheading
text
be the
textContent
of the second entry
in
headings list
If
heading
is an
h1
h6
element
Let
heading text
be the
textContent
of
heading
Append a
title
element in the
Atom
namespace
to the root element of
whose contents is a text node with its data set to
heading text
If
subheading text
is not the empty string,
append a
subtitle
element in the
Atom
namespace
to the root element of
whose contents is a text node with its data set to
subheading text
Let
global update date
have no
value.
For each
article
element
article
that does not have an ancestor
article
element, run the following steps:
Let
be an
entry
element in the
Atom namespace
and append
to the root element of
Let
heading
be the first element of
heading content
whose nearest ancestor of
sectioning content
is
article
if any, or null if there is none.
Take the appropriate action from the following list, as
determined by the type of the
heading
element:
If
heading
is null
Let
heading text
be the empty
string.
If
heading
is a
hgroup
element
If
heading
contains no child
h1
h6
elements, let
heading text
be the empty string.
Otherwise, let
headings list
be a list
of all the
h1
h6
element
children of
heading
, sorted first by
descending
rank
and then in
tree
order
(so
h1
s first, then
h2
s, etc, with each group in the order they
appear in the document). Then, let
heading
text
be the
textContent
of the first entry
in
headings list
If
heading
is an
h1
h6
element
Let
heading text
be the
textContent
of
heading
Append a
title
element in the
Atom namespace
to
whose
contents is a text node with its data set to
heading text
Clone
article
and its descendants into an
environment that has
scripting
disabled
, has no
plugins
, and
fails any attempt to
fetch
any
resources. Let
cloned article
be the
resulting clone
article
element.
Remove from the subtree rooted at
cloned
article
any
article
elements other than the
cloned article
itself, any
header
footer
, or
nav
elements whose nearest ancestor of
sectioning
content
is the
cloned article
, and
the first element of
heading content
whose nearest
ancestor of
sectioning content
is the
cloned article
, if any.
If
cloned article
contains any
ins
or
del
elements with
datetime
attributes whose
values
parse
as global date and time strings
without errors, then let
update date
be the value of the
datetime
attribute that parses
to the newest
global date and
time
Otherwise, let
update date
have no
value.
This value is used below; it is calculated here
because in certain cases the next step mutates the
cloned article
If the document being converted is an
HTML document
, then: Let
be a
content
element in the
Atom
namespace
. Add a
type
attribute
whose value is the string "
html
" to
. Append a text node with its data set to the
result of running the
HTML fragment serialization
algorithm
on
cloned article
to
. Append
to
Otherwise, the document being converted is an
XML document
: Let
be a
content
element in
the
Atom namespace
. Add a
type
attribute whose value is the string "
xml
" to
. Append a
div
element to
. Move all the
child nodes of the
cloned article
node to
that
div
element, preserving their relative
order. Append
to
Establish the value of
id
and
has-alternate
from the first of the following to
apply:
If the
article
node has a descendant
or
area
element with an
href
attribute that
successfully
resolves
relative to that descendant and a
rel
attribute whose value includes
the
keyword
Let
id
be the
absolute URL
resulting from
resolving
the
value of the
href
attribute of the first such
or
area
element, relative to the element. Let
has-alternate
be true.
If the
article
node has an
id
attribute
Let
id
be
the document's current
address
, with the fragment identifier (if any) removed,
and with a new fragment identifier specified, consisting of the
value of the
article
element's
id
attribute. Let
has-alternate
be false.
Otherwise
Let
id
be a user-agent-defined
undereferenceable yet globally unique
valid
absolute URL
. The same
absolute URL
should be generated for each run of
this algorithm when given the same input. Let
has-alternate
be false.
Append an
id
element in the
Atom
namespace
to
whose contents is a
text node with its data set to
id
If
has-alternate
is true: Let
be a
link
element in the
Atom namespace
. Add a
rel
attribute whose value is the string "
alternate
" to
. Append a
text node with its data set to
id
to
. Append
to
If
article
has a
time
element descendant that has a
pubdate
attribute and whose
nearest ancestor
article
element is
article
, and the first such element's
date
is not unknown, then run
the following substeps, with
being the
first such element:
Let
datetime
be a
global date and time
whose date
component is the
date
of
If
's
time
and
time-zone offset
are not
unknown, then let
datetime
's time and
time-zone offset components be the
time
and
time-zone offset
of
. Otherwise, let them be midnight and no offset
respectively ("
00:00Z
").
Let
publication date
be the
best representation of the global date and time
string
datetime
Otherwise, let
publication date
have no
value.
If
update date
has no value but
publication date
does, then let
update date
have the value of
publication date
Otherwise, if
publication date
has no
value but
update date
does, then let
publication date
have the value of
update date
If
update date
has a value, and
global update date
has no value or is less recent
than
update date
, then let
global update date
have the value of
update date
If
publication date
and
update date
both still have no value, then let
them both value a value that is a
valid global date and
time string
representing the
global date and time
of the
moment that this algorithm was invoked.
Append an
published
element in the
Atom namespace
to
whose
contents is a text node with its data set to
publication date
Append an
updated
element in the
Atom namespace
to
whose
contents is a text node with its data set to
update date
If
global update date
has no value, then
let it have a value that is a
valid global date and time
string
representing the
global date and time
of the date
and time of the
Document
's source file's last
modification, if it is known, or else of the moment that this
algorithm was invoked.
Insert an
updated
element in the
Atom namespace
into the root element of
before the first
entry
in
the
Atom namespace
whose contents is a text node with
its data set to
global update date
Return the Atom document
The above algorithm does not guarantee that the
output will be a conforming Atom feed. In particular, if
insufficient information is provided in the document (e.g. if the
document does not have any
content="...">
elements), then the output will not be
conforming.
The
Atom namespace
is: