hidden
attributeStatus: Last call for comments. ISSUE-95 (hidden) blocks progress to Last Call
All HTML elements may have the hidden
content attribute set. The hidden
attribute is a boolean
attribute. When specified on an element, it indicates that
the element is not yet, or is no longer, relevant. User agents should not render elements that have the
hidden
attribute
specified.
In the following skeletal example, the attribute is used to hide the Web game's main screen until the user logs in:
<h1>The Example Game</h1> <section id="login"> <h2>Login</h2> <form> ... <!-- calls login() once the user's credentials have been checked --> </form> <script> function login() { // switch screens document.getElementById('login').hidden = true; document.getElementById('game').hidden = false; } </script> </section> <section id="game" hidden> ... </section>
The hidden
attribute must not be
used to hide content that could legitimately be shown in another
presentation. For example, it is incorrect to use hidden
to hide panels in a tabbed dialog,
because the tabbed interface is merely a kind of overflow
presentation — one could equally well just show all the form
controls in one big page with a scrollbar. It is similarly incorrect
to use this attribute to hide content just from one presentation
— if something is marked hidden
, it is hidden from all
presentations, including, for instance, screen readers.
Elements that are not hidden
should not link to or refer to elements that are hidden
.
For example, it would be incorrect to use the href
attribute to link to a
section marked with the hidden
attribute. If the content is not applicable or relevant, then there
is no reason to link to it.
It would similarly be incorrect to use the ARIA aria-describedby
attribute to
refer to descriptions that are themselves hidden
. Hiding a section means that it
is not applicable or relevant to anyone at the current time, so
clearly it cannot be a valid description of content the user can
interact with.
Elements in a section hidden by the hidden
attribute are still active,
e.g. scripts and form controls in such sections still execute
and submit respectively. Only their presentation to the user
changes.
The hidden
IDL
attribute must reflect the content attribute of the
same name.
Status: Last call for comments
click
()Acts as if the element was clicked.
Each element has a click in progress flag, initially set to false.
The click()
method must
run these steps:
If the element's click in progress flag is set to true, then abort these steps.
Set the click in progress flag on the element to true.
If the element has a defined activation behavior,
run synthetic click activation steps on the
element. Otherwise, fire a click
event at
the element.
Set the click in progress flag on the element to false.
Status: Last call for comments
scrollIntoView
( [ top ] )Scrolls the element into view. If the top argument is true, then the element will be scrolled to the top of the viewport, otherwise it'll be scrolled to the bottom. The default is the top.
The scrollIntoView([top])
method, when called, must cause
the element on which the method was called to have the attention of
the user called to it.
In a speech browser, this could happen by having the current playback position move to the start of the given element.
If the element in question cannot be brought to the user's
attention, e.g. because it is hidden
, or is not being
rendered, then the user agent must do nothing instead.
In visual user agents, if the argument is present and has the value false, the user agent should scroll the element into view such that both the bottom and the top of the element are in the viewport, with the bottom of the element aligned with the bottom of the viewport. If it isn't possible to show the entire element in that way, or if the argument is omitted or is true, then the user agent should instead align the top of the element with the top of the viewport. If the entire scrollable part of the content is visible all at once (e.g. if a page is shorter than the viewport), then the user agent should not scroll anything. Visual user agents should further scroll horizontally as necessary to bring the element to the attention of the user.
Non-visual user agents may ignore the argument, or may treat it in some media-specific manner most useful to the user.
Status: Last call for comments
When an element is focused, key events received by the document must be targeted at that element. There may be no element focused; when no element is focused, key events received by the document must be targeted at the body element.
User agents may track focus for each browsing
context or Document
individually, or may support
only one focused element per top-level browsing context
— user agents should follow platform conventions in this
regard.
Which elements within a top-level browsing context currently have focus must be independent of whether or not the top-level browsing context itself has the system focus.
When an element is focused, the element matches the
CSS :focus
pseudo-class.
Status: Last call for comments
The tabindex
content attribute specifies whether the element is focusable,
whether it can be reached using sequential focus navigation, and the
relative order of the element for the purposes of sequential focus
navigation. The name "tab index" comes from the common use of the
"tab" key to navigate through the focusable elements. The term
"tabbing" refers to moving forward through the focusable elements
that can be reached using sequential focus navigation.
The tabindex
attribute, if
specified, must have a value that is a valid
integer.
If the attribute is specified, it must be parsed using the rules for parsing integers. The attribute's values have the following meanings:
The user agent should follow platform conventions to determine if the element is to be focusable and, if so, whether the element can be reached using sequential focus navigation, and if so, what its relative order should be.
The user agent must allow the element to be focused, but should not allow the element to be reached using sequential focus navigation.
The user agent must allow the element to be focused, should allow the element to be reached using sequential focus navigation, and should follow platform conventions to determine the element's relative order.
The user agent must allow the element to be focused, should allow the element to be reached using sequential focus navigation, and should place the element in the sequential focus navigation order so that it is:
tabindex
attribute has been
omitted or whose value, when parsed, returns an error,tabindex
attribute has a value equal
to or less than zero,tabindex
attribute has a value
greater than zero but less than the value of the tabindex
attribute on the
element,tabindex
attribute has a value equal
to the value of the tabindex
attribute on the element but that is earlier in the document in
tree order than the element,tabindex
attribute has a value equal
to the value of the tabindex
attribute on the element but that is later in the document in
tree order than the element, andtabindex
attribute has a value
greater than the value of the tabindex
attribute on the
element.An element is specially focusable if the tabindex
attribute's definition above
defines the element to be focusable.
An element that is specially focusable but does not otherwise have an activation behavior defined has an activation behavior that does nothing.
This means that an element that is only focusable
because of its tabindex
attribute
will fire a click
event in response
to a non-mouse activation (e.g. hitting the "enter" key while the
element is focused).
The tabIndex
IDL
attribute must reflect the value of the tabindex
content attribute. If the
attribute is not present, or parsing its value returns an error,
then the IDL attribute must return 0 for elements that are focusable
and −1 for elements that are not focusable.
Status: Last call for comments
An element is focusable if the user agent's default
behavior allows it to be focusable or if the element is
specially focusable, but only if the element is either
being rendered or is a
descendant of a canvas
element that
represents embedded content.
User agents should make the following elements focusable, unless platform conventions dictate otherwise:
a
elements that have an href
attributelink
elements that have an href
attributebutton
elements that are not disabledinput
elements whose type
attribute are not in the
Hidden state and that
are not disabledselect
elements that are not disabledtextarea
elements that are not disabledcommand
elements that do not have a disabled
attributedraggable
attribute set, if that would enable the user agent to allow the
user to begin a drag operations for those elements without the use
of a pointing deviceIn addition, each shape that is generated for an
area
element should be focusable, unless
platform conventions dictate otherwise. (A single area
element can correspond to multiple shapes, since image maps can be
reused with multiple images on a page.)
The focusing steps are as follows:
If focusing the element will remove the focus from another element, then run the unfocusing steps for that element.
Make the element the currently focused element in its top-level browsing context.
Some elements, most notably area
, can correspond
to more than one distinct focusable area. If a particular area was
indicated when the element was focused, then that is the area that
must get focus; otherwise, e.g. when using the focus()
method, the first such region in
tree order is the one that must be focused.
Fire a simple event named focus
at the element.
User agents must synchronously run the focusing steps for an element whenever the user moves the focus to a focusable element.
The unfocusing steps are as follows:
If the element is an input
element, and the
change
event applies to the
element, and the element does not have a defined activation
behavior, and the user has changed the element's value or its list of selected files
while the control was focused without committing that change, then
fire a simple event that bubbles named change
at the element, then
broadcast formchange
events at the element's form owner.
Unfocus the element.
Fire a simple event named blur
at the element.
When an element that is focused stops being a focusable element, or stops being focused without another element being explicitly focused in its stead, the user agent should synchronously run the focusing steps for the body element, if there is one; if there is not, then the user agent should synchronously run the unfocusing steps for the affected element only.
For example, this might happen because the
element is removed from its Document
, or has a hidden
attribute added. It would also
happen to an input
element when the element gets disabled.
Status: Last call for comments
activeElement
Returns the currently focused element.
hasFocus
()Returns true if the document has focus; otherwise, returns false.
focus
()Focuses the window. Use of this method is discouraged. Allow the user to control window focus instead.
blur
()Unfocuses the window. Use of this method is discouraged. Allow the user to control window focus instead.
The activeElement
attribute on HTMLDocument
objects must return the
element in the document that is focused. If no element in the
Document
is focused, this must return the body
element.
The hasFocus()
method
on HTMLDocument
objects must return true if the
document's browsing context is focused, and all its
ancestor browsing
contexts are also focused, and the top-level browsing
context has the system focus.
The focus()
method on the Window
object, when invoked, provides a
hint to the user agent that the script believes the user might be
interested in the contents of the browsing context of
the Window
object on which the method was invoked.
User agents are encouraged to have this focus()
method trigger some kind of
notification.
The blur()
method
on the Window
object, when invoked, provides a hint to
the user agent that the script believes the user probably is not
currently interested in the contents of the browsing
context of the Window
object on which the method
was invoked, but that the contents might become interesting again in
the future.
User agents are encouraged to ignore calls to this blur()
method entirely.
Historically the focus()
and blur()
methods actually affected the
system focus, but hostile sites widely abuse this behavior to the
user's detriment.
Status: Last call for comments
focus
()Focuses the element.
blur
()Unfocuses the element. Use of this method is discouraged. Focus another element instead.
Do not use this method to hide the focus ring if you find the focus ring unsightly. Instead, use a CSS rule to override the 'outline' property.
For example, to hide the outline from links, you could use:
:link:focus, :visited:focus { outline: none; }
The focus()
method,
when invoked, must run the following algorithm:
If the element is marked as locked for focus, then abort these steps.
If the element is not focusable, then abort these steps.
Mark the element as locked for focus.
If the element is not already focused, run the focusing steps for the element.
Unmark the element as locked for focus.
The blur()
method, when
invoked, should run the focusing steps for the
body element, if there is one; if there is not, then it
should run the unfocusing steps for the element on
which the method was called instead. User agents may selectively or
uniformly ignore calls to this method for usability reasons.
For example, if the blur()
method is unwisely being used to
remove the focus ring for aesthetics reasons, the page would become
unusable by keyboard users. Ignoring calls to this method would thus
allow keyboard users to interact with the page.
accesskey
attributeStatus: Last call for comments
All HTML elements may have the accesskey
content attribute set. The
accesskey
attribute's value is
used by the user agent as a guide for creating a keyboard shortcut
that activates or focuses the element.
If specified, the value must be an ordered set of unique space-separated tokens, each of which must be exactly one Unicode code point in length.
An element's assigned access key is a key combination
derived from the element's accesskey
content attribute as
follows:
If the element has no accesskey
attribute, then skip to the
fallback step below.
Otherwise, the user agent must split the attribute's value on spaces, and let keys be the resulting tokens.
For each value in keys in turn, in the order the tokens appeared in the attribute's value, run the following substeps:
If the value is not a string exactly one Unicode code point in length, then skip the remainder of these steps for this value.
If the value does not correspond to a key on the system's keyboard, then skip the remainder of these steps for this value.
If the user agent can find a combination of modifier keys that, with the key that corresponds to the value given in the attribute, can be used as a shortcut key, then the user agent may assign that combination of keys as the element's assigned access key and abort these steps.
Fallback: Optionally, the user agent may assign a key combination of its choosing as the element's assigned access key and then abort these steps.
If this step is reached, the element has no assigned access key.
Once a user agent has selected and assigned an access key for an
element, the user agent should not change the element's
assigned access key unless the accesskey
content attribute is changed
or the element is moved to another Document
.
When the user presses the key combination corresponding to the assigned access key for an element, if the element defines a command, and the command's Hidden State facet is false (visible), and the command's Disabled State facet is also false (enabled), then the user agent must trigger the Action of the command.
User agents may expose elements that have an accesskey
attribute in other ways as
well, e.g. in a menu displayed in response to a specific key
combination.
The accessKey
IDL
attribute must reflect the accesskey
content attribute.
The accessKeyLabel
IDL
attribute must return a string that represents the element's
assigned access key, if any. If the element does not
have one, then the IDL attribute must return the empty string.
In the following example, a variety of links are given with access keys so that keyboard users familiar with the site can more quickly navigate to the relevant pages:
<nav> <p> <a title="Consortium Activities" accesskey="A" href="/Consortium/activities">Activities</a> | <a title="Technical Reports and Recommendations" accesskey="T" href="/TR/">Technical Reports</a> | <a title="Alphabetical Site Index" accesskey="S" href="/Consortium/siteindex">Site Index</a> | <a title="About This Site" accesskey="B" href="/Consortium/">About Consortium</a> | <a title="Contact Consortium" accesskey="C" href="/Consortium/contact">Contact</a> </p> </nav>
In the following example, the search field is given two possible access keys, "s" and "0" (in that order). A user agent on a device with a full keyboard might pick Ctrl+Alt+S as the shortcut key, while a user agent on a small device with just a numeric keypad might pick just the plain unadorned key 0:
<form action="/search"> <label>Search: <input type="search" name="q" accesskey="s 0"></label> <input type="submit"> </form>
In the following example, a button has possible access keys described. A script then tries to update the button's label to advertise the key combination the user agent selected.
<input type=submit accesskey="N @ 1" value="Compose"> ... <script> function labelButton(button) { if (button.accessKeyLabel) button.value += ' (' + button.accessKeyLabel + ')'; } var inputs = document.getElementsByTagName('input'); for (var i = 0; i < inputs.length; i += 1) { if (inputs[i].type == "submit") labelButton(inputs[i]); } </script>
On one user agent, the button's label might become "Compose (⌘N)". On another, it might become "Compose (Alt+⇧+1)". If the user agent doesn't assign a key, it will be just "Compose". The exact string depends on what the assigned access key is, and on how the user agent represents that key combination.
Status: Last call for comments
Every browsing context has a selection. The selection can be empty, and the selection can have more than one range (a disjointed selection). The user agent should allow the user to change the selection. User agents are not required to let the user select more than one range, and may collapse multiple ranges in the selection to a single range when the user interacts with the selection. (But, of course, the user agent may let the user create selections with multiple ranges.)
This one selection must be shared by all the content of the browsing context (though not by nested browsing contexts), including any editing hosts in the document. (Editing hosts that are not inside a document cannot have a selection.)
If the selection is empty (collapsed, so that it has only one segment and that segment's start and end points are the same) then the selection's position should equal the caret position. When the selection is not empty, this specification does not define the caret position; user agents should follow platform conventions in deciding whether the caret is at the start of the selection, the end of the selection, or somewhere else.
On some platforms (such as those using Wordstar editing conventions), the caret position is totally independent of the start and end of the selection, even when the selection is empty. On such platforms, user agents may ignore the requirement that the cursor position be linked to the position of the selection altogether.
Mostly for historical reasons, in addition to the browsing
context's selection, each
textarea
and input
element has an
independent selection. These are the text field selections.
User agents may selectively ignore attempts to use the API to adjust the selection made after the user has modified the selection. For example, if the user has just selected part of a word, the user agent could ignore attempts to use the API call to immediately unselect the selection altogether, but could allow attempts to change the selection to select the entire word.
User agents may also allow the user to create selections that are not exposed to the API.
The select
element also has a selection, indicating
which items have been picked by the user. This is not discussed in
this section.
This specification does not specify how selections are presented to the user.
Status: Last call for comments
getSelection
()getSelection
()Returns the Selection
object for the window, which
stringifies to the text of the current selection.
The getSelection()
method on
the Window
interface must return the
Selection
object representing the
selection of that Window
object's
browsing context.
For historical reasons, the getSelection()
method on the HTMLDocument
interface must return the
same Selection
object.
interface Selection { readonly attribute Node anchorNode; readonly attribute long anchorOffset; readonly attribute Node focusNode; readonly attribute long focusOffset; readonly attribute boolean isCollapsed; void collapse(in Node parentNode, in long offset); void collapseToStart(); void collapseToEnd(); void selectAllChildren(in Node parentNode); void deleteFromDocument(); readonly attribute long rangeCount; Range getRangeAt(in long index); void addRange(in Range range); void removeRange(in Range range); void removeAllRanges(); stringifier DOMString (); };
The Selection
interface represents a list of
Range
objects. The first item in the list has index 0,
and the last item has index count-1, where count is the number of ranges in the list. [DOMRANGE]
All of the members of the Selection
interface are
defined in terms of operations on the Range
objects
represented by this object. These operations can raise exceptions,
as defined for the Range
interface; this can therefore
result in the members of the Selection
interface
raising exceptions as well, in addition to any explicitly called out
below.
anchorNode
Returns the element that contains the start of the selection.
Returns null if there's no selection.
anchorOffset
Returns the offset of the start of the selection relative to the element that contains the start of the selection.
Returns 0 if there's no selection.
focusNode
Returns the element that contains the end of the selection.
Returns null if there's no selection.
focusOffset
Returns the offset of the end of the selection relative to the element that contains the end of the selection.
Returns 0 if there's no selection.
isCollapsed
()Returns true if there's no selection or if the selection is empty. Otherwise, returns false.
collapse
(parentNode, offset)Replaces the selection with an empty one at the given position.
Throws a WRONG_DOCUMENT_ERR
exception if the given node is in a different document.
collapseToStart
()Replaces the selection with an empty one at the position of the start of the current selection.
Throws an INVALID_STATE_ERR
exception if there is no selection.
collapseToEnd
()Replaces the selection with an empty one at the position of the end of the current selection.
Throws an INVALID_STATE_ERR
exception if there is no selection.
selectAllChildren
(parentNode)Replaces the selection with one that contains all the contents of the given element.
Throws a WRONG_DOCUMENT_ERR
exception if the given node is in a different document.
deleteFromDocument
()Deletes the selection.
rangeCount
Returns the number of ranges in the selection.
getRangeAt
(index)Returns the given range.
Throws an INDEX_SIZE_ERR
exception if the value is out of range.
addRange
(range)Adds the given range to the selection.
removeRange
(range)Removes the given range from the selection, if the range was one of the ones in the selection.
removeAllRanges
()Removes all the ranges in the selection.
The anchorNode
attribute must return the value returned by the startContainer
attribute of the last
Range
object in the list, or null if the list is
empty.
The anchorOffset
attribute must return the value returned by the startOffset
attribute of the last Range
object in the list, or 0 if the list is empty.
The focusNode
attribute must return the value returned by the endContainer
attribute of the last
Range
object in the list, or null if the list is
empty.
The focusOffset
attribute must return the value returned by the endOffset
attribute of the last Range
object in the list, or 0 if the list is empty.
The isCollapsed
attribute must return true if there are zero ranges, or if there is
exactly one range and its collapsed
attribute
is itself true. Otherwise it must return false.
The collapse(parentNode, offset)
method must raise a WRONG_DOCUMENT_ERR
DOM exception if
parentNode's Document
is not the
HTMLDocument
object with which the
Selection
object is associated. Otherwise it is, and
the method must remove all the ranges in the Selection
list, then create a new Range
object, add it to the
list, and invoke its setStart()
and setEnd()
methods with the parentNode and offset values as
their arguments.
The collapseToStart()
method must raise an INVALID_STATE_ERR
DOM exception if
there are no ranges in the list. Otherwise, it must invoke the collapse()
method with the
startContainer
and startOffset
values of the first Range
object in the list as the arguments.
The collapseToEnd()
method must raise an INVALID_STATE_ERR
DOM exception if
there are no ranges in the list. Otherwise, it must invoke the collapse()
method with the
endContainer
and endOffset
values of the last Range
object in the list as the arguments.
The selectAllChildren(parentNode)
method must invoke the collapse()
method with the
parentNode value as the first argument and 0 as the
second argument, and must then invoke the selectNodeContents()
method on the first (and only)
range in the list with the parentNode value as the
argument.
The deleteFromDocument()
method must invoke the deleteContents()
method
on each range in the list, if any, from first to last.
The rangeCount
attribute must return the number of ranges in the list.
The getRangeAt(index)
method must return the indexth range in the list. If
index is less than zero or greater or equal to the value
returned by the rangeCount
attribute, then
the method must raise an INDEX_SIZE_ERR
DOM
exception.
The addRange(range)
method must add the given range Range object to the list
of selections, at the end (so the newly added range is the new last
range). Duplicates are not prevented; a range may be added more than
once in which case it appears in the list more than once, which (for
example) will cause stringification to return the
range's text twice.
The removeRange(range)
method must remove the first occurrence of range in the
list of ranges, if it appears at all.
The removeAllRanges()
method must remove all the ranges from the list of ranges, such that
the rangeCount
attribute returns 0 after the removeAllRanges()
method is invoked (and until a new range is added to the list,
either through this interface or via user interaction).
Objects implementing this interface must stringify to a concatenation
of the results of invoking the toString()
method of the Range
object on each of the ranges of the
selection, in the order they appear in the list (first to last).
In the following document fragment, the emphasized parts indicate the selection.
<p>The cute girl likes the <cite>Oxford English Dictionary</cite>.</p>
If a script invoked window.getSelection().toString()
, the return value
would be "the Oxford English
".
Status: Last call for comments
The input
and textarea
elements define
the following members in their DOM interfaces for handling their
text selection:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; void setSelectionRange(in unsigned long start, in unsigned long end);
These methods and attributes expose and control the selection of
input
and textarea
text fields.
select
()Selects everything in the text field.
selectionStart
[ = value ]Returns the offset to the start of the selection.
Can be set, to change the start of the selection.
selectionEnd
[ = value ]Returns the offset to the end of the selection.
Can be set, to change the end of the selection.
setSelectionRange
(start, end)Changes the selection to cover the given substring.
When these methods and attributes are used with
input
elements while they don't apply, they must raise
an INVALID_STATE_ERR
exception. Otherwise, they must
act as described below.
The select()
method
must cause the contents of the text field to be fully selected.
The selectionStart
attribute must, on getting, return the offset (in logical order) to
the character that immediately follows the start of the
selection. If there is no selection, then it must return the offset
(in logical order) to the character that immediately follows the
text entry cursor.
On setting, it must act as if the setSelectionRange()
method had been called, with the new value as the first argument,
and the current value of the selectionEnd
attribute as the second argument, unless the current value of the
selectionEnd
is
less than the new value, in which case the second argument must also
be the new value.
The selectionEnd
attribute must, on getting, return the offset (in logical order) to
the character that immediately follows the end of the selection. If
there is no selection, then it must return the offset (in logical
order) to the character that immediately follows the text entry
cursor.
On setting, it must act as if the setSelectionRange()
method had been called, with the current value of the selectionStart
attribute as the first argument, and new value as the second
argument.
The setSelectionRange(start, end)
method
must set the selection of the text field to the sequence of
characters starting with the character at the startth position (in logical order) and ending with
the character at the (end-1)th position. Arguments greater than the
length of the value in the text field must be treated as pointing at
the end of the text field. If end is less than
or equal to start then the start of the
selection and the end of the selection must both be placed
immediately before the character with offset end. In UAs where there is no concept of an empty
selection, this must set the cursor to be just before the character
with offset end.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.
contenteditable
attributeStatus: Last call for comments
The contenteditable
attribute is an enumerated attribute whose keywords are
the empty string, true
, and false
. The empty string and the true
keyword map to the true state. The false
keyword maps to the false state. In
addition, there is a third state, the inherit state, which is
the missing value default (and the invalid value
default).
The true state indicates that the element is editable. The inherit state indicates that the element is editable if its parent is. The false state indicates that the element is not editable.
Specifically, if an HTML
element has a contenteditable
attribute set to
the true state, or it has its contenteditable
attribute set to
the inherit state and if its nearest ancestor HTML element with the contenteditable
attribute set to
a state other than the inherit state has its attribute set to the
true state, or if it and its ancestors all have their contenteditable
attribute set to
the inherit state but the Document
has designMode
enabled, then the
UA must treat the element as editable (as described
below).
Otherwise, either the HTML
element has a contenteditable
attribute set to
the false state, or its contenteditable
attribute is set
to the inherit state and its nearest ancestor HTML element with the contenteditable
attribute set to
a state other than the inherit state has its attribute set to the
false state, or all its ancestors have their contenteditable
attribute set to
the inherit state and the Document
itself has designMode
disabled; either
way, the element is not editable.
contentEditable
[ = value ]Returns "true
", "false
", or "inherit
", based
on the state of the contenteditable
attribute.
Can be set, to change that state.
Throws a SYNTAX_ERR
exception if the new value
isn't one of those strings.
isContentEditable
Returns true if the element is editable; otherwise, returns false.
The contentEditable
IDL
attribute, on getting, must return the string "true
" if the content attribute is set to the true
state, false
" if the content attribute is set
to the false state, and "inherit
"
otherwise. On setting, if the new value is an ASCII
case-insensitive match for the string "inherit
" then the content attribute must be removed,
if the new value is an ASCII case-insensitive match for
the string "true
" then the content attribute
must be set to the string "true
", if the new
value is an ASCII case-insensitive match for the string
"false
" then the content attribute must be set
to the string "false
", and otherwise the
attribute setter must raise a SYNTAX_ERR
exception.
The isContentEditable
IDL attribute, on getting, must return true if the element is
editable, and false otherwise.
If an element is editable and its parent element is not, or if an element is editable and it has no parent element, then the element is an editing host. Editable elements can be nested. User agents must make editing hosts focusable (which typically means they enter the tab order). An editing host can contain non-editable sections, these are handled as described below. An editing host can contain non-editable sections that contain further editing hosts.
When an editing host has focus, it must have a caret position that specifies where the current editing position is. It may also have a selection.
How the caret and selection are represented depends entirely on the UA.
Status: Last call for comments
There are several actions that the user agent should allow the user to perform while the user is interacting with an editing host. How exactly each action is triggered is not defined for every action, but when it is not defined, suggested key bindings are provided to guide implementors.
User agents must allow users to move the caret to any
position within an editing host, even into nested editable
elements. This could be triggered as the default action of keydown
events with various key
identifiers and as the default action of mousedown
events.
User agents must allow users to change the
selection within an editing host, even into nested editable
elements. User agents may prevent selections from being made in
ways that cross from editable elements into non-editable elements
(e.g. by making each non-editable descendant atomically selectable,
but not allowing text selection within them). This could be
triggered as the default action of keydown
events with various key
identifiers and as the default action of mousedown
events.
This action must be triggered as the default action of a
textInput
event, and may be
triggered by other commands as well. It must cause the user agent
to insert the specified text (given by the event object's data
attribute in the case of the textInput
event) at the caret.
If the caret is positioned somewhere where phrasing
content is not allowed (e.g. inside an empty ol
element), then the user agent must not insert the text directly at
the caret position. In such cases the behavior is UA-dependent,
but user agents must not, in response to a request to insert text,
generate a DOM that is less conformant than the DOM prior to the
request.
User agents should allow users to insert new paragraphs into elements that contains only content other than paragraphs.
UAs should offer a way for the user to request that the
current paragraph be broken at the caret, e.g. as the default
action of a keydown
event whose
identifier is the "Enter" key and that has no modifiers set.
The exact behavior is UA-dependent, but user agents must not, in response to a request to break a paragraph, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer a way for the user to request an explicit
line break at the caret position without breaking the paragraph,
e.g. as the default action of a keydown
event whose identifier is the
"Enter" key and that has a shift modifier set. Line separators are
typically found within a poem verse or an address. To insert a line
break, the user agent must insert a br
element.
If the caret is positioned somewhere where phrasing
content is not allowed (e.g. in an empty ol
element), then the user agent must not insert the br
element directly at the caret position. In such cases the behavior
is UA-dependent, but user agents must not, in response to a request
to insert a line separator, generate a DOM that is less conformant
than the DOM prior to the request.
UAs should offer a way for the user to delete text and
elements, including non-editable descendants, e.g. as the default
action of keydown
events whose
identifiers are "U+0008" or "U+007F".
Five edge cases in particular need to be considered carefully when implementing this feature: backspacing at the start of an element, backspacing when the caret is immediately after an element, forward-deleting at the end of an element, forward-deleting when the caret is immediately before an element, and deleting a selection whose start and end points do not share a common parent node.
In any case, the exact behavior is UA-dependent, but user agents must not, in response to a request to delete text or an element, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer the user the ability to mark text and paragraphs with semantics that HTML can express.
UAs should similarly offer a way for the user to insert empty semantic elements to subsequently fill by entering text manually.
UAs should also offer a way to remove those semantics from marked up text, and to remove empty semantic element that have been inserted.
In response to a request from a user to mark text up in italics,
user agents should use the i
element to represent the
semantic. The em
element should be used only if the
user agent is sure that the user means to indicate stress
emphasis.
In response to a request from a user to mark text up in bold,
user agents should use the b
element to represent the
semantic. The strong
element should be used only if
the user agent is sure that the user means to indicate
importance.
The exact behavior is UA-dependent, but user agents must not, in response to a request to wrap semantics around some text or to insert or remove a semantic element, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer a way for the user to move images and other non-editable parts around the content within an editing host. This may be done using the drag and drop mechanism. User agents must not, in response to a request to move non-editable elements nested inside editing hosts, generate a DOM that is less conformant than the DOM prior to the request.
When an editable form control is edited, the
changes must be reflected in both its current value and
its default value. For input
elements this means
updating the defaultValue
IDL attribute as
well as the value
IDL
attribute; for select
elements it means updating the
option
elements' defaultSelected
IDL
attribute as well as the selected
IDL attribute; for
textarea
elements this means updating the defaultValue
IDL attribute
as well as the value
IDL
attribute. (Updating the default*
IDL
attributes causes content attributes to be updated as well.)
User agents may perform several commands per user request; for example if the user selects a block of text and hits Enter, the UA might interpret that as a request to delete the content of the selection followed by a request to break the paragraph at that position.
User agents may add DOM changes entries to the
undo transaction history of the editing
host's Document
object each time an action is
triggered.
All of the actions defined above, whether triggered by the user
or programmatically (e.g. by execCommand()
commands),
must fire mutation events as appropriate.
Status: Last call for comments
Documents have a designMode
, which
can be either enabled or disabled.
designMode
[ = value ]Returns "on
" if the document is editable,
and "off
" if it isn't.
Can be set, to change the document's current state.
The designMode
IDL
attribute on the Document
object takes two values,
"on
" and "off
". When it
is set, the new value must be compared in an ASCII
case-insensitive manner to these two values. If it matches
the "on
" value, then designMode
must be enabled,
and if it matches the "off
" value, then designMode
must be
disabled. Other values must be ignored.
When designMode
is
enabled, the IDL attribute must return the value "on
", and when it is disabled, it must return the
value "off
".
The last state set must persist until the document is destroyed
or the state is changed. Initially, documents must have their designMode
disabled.
Status: Last call for comments
User agents can support the checking of spelling and grammar of
editable text, either in form controls (such as the value of
textarea
elements), or in elements in an editing
host (using contenteditable
).
For each element, user agents must establish a default behavior, either through defaults or through preferences expressed by the user. There are three possible default behaviors for each element:
The spellcheck
attribute is an enumerated attribute whose keywords are
the empty string, true
and false
. The empty string and the true
keyword map to the true state. The false
keyword maps to the false state. In
addition, there is a third state, the default state, which is
the missing value default (and the invalid value
default).
The true state indicates that the element is to have its
spelling and grammar checked. The default state indicates
that the element is to act according to a default behavior, possibly
based on the parent element's own spellcheck
state. The false
state indicates that the element is not to be checked.
spellcheck
[ = value ]Returns "true
", "false
", or "default
", based
on the state of the spellcheck
attribute.
Can be set, to change that state.
Throws a SYNTAX_ERR
exception if the new value
isn't one of those strings.
The spellcheck
IDL
attribute, on getting, must return the string "true
" if the content attribute is set to the true
state, false
" if the content attribute is set
to the false state, and "default
"
otherwise. On setting, if the new value is an ASCII
case-insensitive match for the string "default
" then the content attribute must be removed,
if the new value is an ASCII case-insensitive match for
the string "true
" then the content attribute
must be set to the string "true
", if the new
value is an ASCII case-insensitive match for the string
"false
" then the content attribute must be set
to the string "false
", and otherwise the
attribute setter must raise a SYNTAX_ERR
exception.
The spellcheck
IDL attribute is not affected by user preferences that override the
spellcheck
content attribute,
and therefore might not reflect the actual spellchecking state.
On setting, if the new value is true, then the element's spellcheck
content attribute must be
set to the literal string "true
", otherwise it
must be set to the literal string "false
".
User agents must only consider the following pieces of text as checkable for the purposes of this feature:
input
elements to which the readonly
attribute applies,
whose type
attributes are not
in the Password
state, and 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.For text that is part of a text node, the element
with which the text is associated is the element that is the
immediate parent of the first character of the word, sentence, or
other piece of text. For text in attributes, it is the attribute's
element. For the values of input
and
textarea
elements, it is the element itself.
To determine if a word, sentence, or other piece of text in an applicable element (as defined above) is to have spelling- and/or grammar-checking enabled, the UA must use the following algorithm:
spellcheck
content
attribute, then: if that attribute is in the true state,
then checking is enabled; otherwise, if that attribute is in the
false state, then checking is disabled.spellcheck
content attribute that is
not in the default state, then: if the nearest such
ancestor's spellcheck
content
attribute is in the true state, then checking is enabled;
otherwise, checking is disabled.If the checking is enabled for a word/sentence/text, the user
agent should indicate spelling and/or grammar errors in that
text. User agents should take into account the other semantics given
in the document when suggesting spelling and grammar
corrections. User agents may use the language of the element to
determine what spelling and grammar rules to use, or may use the
user's preferred language settings. UAs should use
input
element attributes such as pattern
to ensure that the
resulting value is valid, where possible.
If checking is disabled, the user agent should not indicate spelling or grammar errors for that text.
The element with ID "a" in the following example would be the one used to determine if the word "Hello" is checked for spelling errors. In this example, it would not be.
<div contenteditable="true"> <span spellcheck="false" id="a">Hell</span><em>o!</em> </div>
The element with ID "b" in the following example would have
checking enabled (the leading space character in the attribute's
value on the input
element causes the attribute to be
ignored, so the ancestor's value is used instead, regardless of the
default).
<p spellcheck="true"> <label>Name: <input spellcheck=" false" id="b"></label> </p>
This specification does not define the user interface for spelling and grammar checkers. A user agent could offer on-demand checking, could perform continuous checking while the checking is enabled, or could use other interfaces.