A call to document.getElementById('example').getElementsByClassName('aaa') would
return a NodeList with the two paragraphs p1 and p2 in it.
A call to getElementsByClassName('ccc bbb') would only return one node, however,
namely p3. A call to
document.getElementById('example').getElementsByClassName('bbb ccc ') would
return the same thing.
A call to getElementsByClassName('aaa,bbb') would return no nodes; none of the
elements above are in the "aaa,bbb" class.
The dir attribute on the HTMLDocument interface is defined along with the dir
content attribute.
2.5. Dynamic markup insertion
The document.write() family of methods and the innerHTML family of DOM
attributes enable script authors to dynamically insert markup into the document.
bz argues that innerHTML should be called something else on XML documents and
XML elements. Is the sanity worth the migration pain?
Because these APIs interact with the parser, their behaviour varies depending on
whether they are used with HTML documents (and the HTML parser) or XHTML in XML
documents (and the XML parser). The following table cross-references the various
versions of these APIs. document.write() innerHTML
For documents that are HTML documents document.write() in HTML innerHTML
in HTML
For documents that are XML documents document.write() in XML innerHTML in
XML
Regardless of the parsing mode, the document.writeln(...) method must call the
document.write() method with the same argument(s), and then call the
document.write() method with, as its argument, a string consisting of a single
line feed character (U+000A).
2.5.1. Controlling the input stream
The open() method comes in several variants with different numbers of arguments.
When called with two or fewer arguments, the method must act as follows:
Let type be the value of the first argument, if there is one, or "text/html"
otherwise.
Let replace be true if there is a second argument and it has the value
"replace", and false otherwise.
If the document has an active parser that isn't a script-created parser, and
the insertion point associated with that parser's input stream is not
undefined (that is, it does point to somewhere in the input stream), then the
method does nothing. Abort these steps and return the Document object on which
the method was invoked.
This basically causes document.open() to be ignored when it's called in an
inline script found during the parsing of data sent over the network, while
still letting it have an effect when called asynchronously or on a document
that is itself being spoon-fed using these APIs.
onbeforeunload, onunload
If the document has an active parser, then stop that parser, and throw away
any pending content in the input stream. what about if it doesn't, because
it's either like a text/plain, or Atom, or PDF, or XHTML, or image document,
or something?
Remove all child nodes of the document.
Create a new HTML parser and associate it with the document. This is a
script-created parser (meaning that it can be closed by the document.open()
and document.close() methods, and that the tokeniser will wait for an explicit
call to document.close() before emitting an end-of-file token).
Mark the document as being an HTML document (it might already be so-marked).
If type does not have the value "text/html", then act as if the tokeniser had
emitted a pre element start tag, then set the HTML parser's tokenisation
stage's content model flag to PLAINTEXT.
If replace is false, then:
Remove all the entries in the browsing context's session history after the
current entry in its Document's History object
Remove any earlier entries that share the same Document
Add a new entry just before the last entry that is associated with the text
that was parsed by the previous parser associated with the Document object,
as well as the state of the document at the start of these steps. (This
allows the user to step backwards in the session history to see the page
before it was blown away by the document.open() call.)
Finally, set the insertion point to point at just before the end of the input
stream (which at this point will be empty).
Return the Document on which the method was invoked.
We shouldn't hard-code text/plain there. We should do it some other way, e.g.
hand off to the section on content-sniffing and handling of incoming data
streams, the part that defines how this all works when stuff comes over the
network.
When called with three or more arguments, the open() method on the HTMLDocument
object must call the open() method on the Window interface of the object
returned by the defaultView attribute of the DocumentView interface of the
HTMLDocument object, with the same arguments as the original call to the open()
method, and return whatever that method returned. If the defaultView attribute
of the DocumentView interface of the HTMLDocument object is null, then the
method must raise an INVALID_ACCESS_ERR exception.
The close() method must do nothing if there is no script-created parser
associated with the document. If there is such a parser, then, when the method
is called, the user agent must insert an explicit "EOF" character at the
insertion point of the parser's input stream.
2.5.2. Dynamic markup insertion in HTML
In HTML, the document.write(...) method must act as follows:
If the insertion point is undefined, the open() method must be called (with no
arguments) on the document object. The insertion point will point at just
before the end of the (empty) input stream.
The string consisting of the concatenation of all the arguments to the method
must be inserted into the input stream just before the insertion point.
If there is a script that will execute as soon as the parser resumes, then the
method must now return without further processing of the input stream.
Otherwise, the tokeniser must process the characters that were inserted, one
at a time, processing resulting tokens as they are emitted, and stopping when
the tokeniser reaches the insertion point or when the processing of the
tokeniser is aborted by the tree construction stage (this can happen if a
script start tag token is emitted by the tokeniser).
If the document.write() method was called from script executing inline (i.e.
executing because the parser parsed a set of script tags), then this is a
reentrant invocation of the parser.
Finally, the method must return.
In HTML, the innerHTML DOM attribute of all HTMLElement and HTMLDocument nodes
returns a serialisation of the node's children using the HTML syntax. On
setting, it replaces the node's children with new nodes that result from parsing
the given value. The formal definitions follow.
On getting, the innerHTML DOM attribute must return the result of running the
HTML fragment serialisation algorithm on the node.
On setting, if the node is a document, the innerHTML DOM attribute must run the
following algorithm:
If the document has an active parser, then stop that parser, and throw away
any pending content in the input stream. what about if it doesn't, because
it's either like a text/plain, or Atom, or PDF, or XHTML, or image document,
or something?
Remove the children nodes of the Document whose innerHTML attribute is being
set.
Create a new HTML parser, in its initial state, and associate it with the
Document node.
Place into the input stream for the HTML parser just created the string being
assigned into the innerHTML attribute.
Start the parser and let it run until it has consumed all the characters just
inserted into the input stream. (The Document node will have been populated
with elements and a load event will have fired on its body element.)
Otherwise, if the node is an element, then setting the innerHTML DOM attribute
must cause the following algorithm to run instead:
Invoke the HTML fragment parsing algorithm, with the element whose innerHTML
attribute is being set as the context and the string being assigned into the
innerHTML attribute as the input. Let new children be the result of this
algorithm.
Remove the children of the element whose innerHTML attribute is being set.
Let target document be the ownerDocument of the Element node whose innerHTML
attribute is being set.
Set the ownerDocument of all the nodes in new children to the target document.
Append all the new children nodes to the node whose innerHTML attribute is
being set, preserving their order.
script elements inserted using innerHTML do not execute when they are inserted.
2.5.3. Dynamic markup insertion in XML
In an XML context, the document.write() method must raise an INVALID_ACCESS_ERR
exception.
On the other hand, however, the innerHTML attribute is indeed usable in an XML
context.
In an XML context, the innerHTML DOM attribute on HTMLElements and
HTMLDocuments, on getting, must return a string in the form of an internal
general parsed entity that is XML namespace-well-formed, the string being an
isomorphic serialisation of all of that node's child nodes, in document order.
User agents may adjust prefixes and namespace declarations in the serialisation
(and indeed might be forced to do so in some cases to obtain
namespace-well-formed XML). [XML] [XMLNS]
If any of the following cases are found in the DOM being serialised, the user
agent must raise an INVALID_STATE_ERR exception:
A DocumentType node that has an external subset public identifier or an
external subset system identifier that contains both a U+0022 QUOTATION MARK
('"') and a U+0027 APOSTROPHE ("'").
A node with a prefix or local name containing a U+003A COLON (":").
A Text node whose data contains characters that are not matched by the XML
Char production. [XML]
A CDATASection node whose data contains the string "]]>".
A Comment node whose data contains two adjacent U+002D HYPHEN-MINUS (-)
characters or ends with such a character.
A ProcessingInstruction node whose target name is the string "xml" (case
insensitively).
A ProcessingInstruction node whose target name contains a U+003A COLON (":").
A ProcessingInstruction node whose data contains the string "?>".
These are the only ways to make a DOM unserialisable. The DOM enforces all the
other XML constraints; for example, trying to set an attribute with a name that
contains an equals sign (=) will raised an INVALID_CHARACTER_ERR exception.
On setting, in an XML context, the innerHTML DOM attribute on HTMLElements and
HTMLDocuments must run the following algorithm:
The user agent must create a new XML parser.
If the innerHTML attribute is being set on an element, the user agent must
feed the parser just created the string corresponding to the start tag of that
element, declaring all the namespace prefixes that are in scope on that
element in the DOM, as well as declaring the default namespace (if any) that
is in scope on that element in the DOM.
The user agent must feed the parser just created the string being assigned
into the innerHTML attribute.
If the innerHTML attribute is being set on an element, the user agent must
feed the parser the string corresponding to the end tag of that element.
If the parser found a well-formedness error, the attribute's setter must raise
a SYNTAX_ERR exception and abort these steps.
The user agent must remove the children nodes of the node whose innerHTML
attribute is being set.
If the attribute is being set on a Document node, let new children be the
children of the document, preserving their order. Otherwise, the attribute is
being set on an Element node; let new children be the children of the the
document's root element, preserving their order.
If the attribute is being set on a Document node, let target document be that
Document node. Otherwise, the attribute is being set on an Element node; let
target document be the ownerDocument of that Element.
Set the ownerDocument of all the nodes in new children to the target document.
Append all the new children nodes to the node whose innerHTML attribute is
being set, preserving their order.
script elements inserted using innerHTML do not execute when they are inserted.
2.6. APIs in HTML documents
For HTML documents, and for HTML elements in HTML documents, certain APIs
defined in DOM3 Core become case-insensitive or case-changing, as sometimes
defined in DOM3 Core, and as summarised or required below. [DOM3CORE].
This does not apply to XML documents or to elements that are not in the HTML
namespace despite being in HTML documents.
Element.tagName, Node.nodeName, and Node.localName
These attributes return tag names in all uppercase and attribute names in all
lowercase, regardless of the case with which they were created.
Document.createElement()
The canonical form of HTML markup is all-lowercase; thus, this method will
lowercase the argument before creating the requisite element. Also, the
element created must be in the HTML namespace.
This doesn't apply to Document.createElementNS(). Thus, it is possible, by
passing this last method a tag name in the wrong case, to create an element
that claims to have the tag name of an element defined in this specification,
but doesn't support its interfaces, because it really has another tag name not
accessible from the DOM APIs.
Element.setAttributeNode()
When an Attr node is set on an HTML element, it must have its name lowercased
before the element is affected.
This doesn't apply to Document.setAttributeNodeNS().
Element.setAttribute()
When an attribute is set on an HTML element, the name argument must be
lowercased before the element is affected.
This doesn't apply to Document.setAttributeNS().
Document.getElementsByTagName() and Element.getElementsByTagName()
These methods (but not their namespaced counterparts) must compare the given
argument case-insensitively when looking at HTML elements, and
case-sensitively otherwise.
Thus, in an HTML document with nodes in multiple namespaces, these methods
will be both case-sensitive and case-insensitive at the same time.
Document.renameNode()
If the new namespace is the HTML namespace, then the new qualified name must
be lowercased before the rename takes place.
3. Semantics and structure of HTML elements
3.1. Introduction
This section is non-normative.
An introduction to marking up a document.
3.2. Common microsyntaxes
There are various places in HTML that accept particular data types, such as
dates or numbers. This section describes what the conformance criteria for
content in those formats is, and how to parse them.
Need to go through the whole spec and make sure all the attribute values are
clearly defined either in terms of microsyntaxes or in terms of other specs, or
as "Text" or some such.
3.2.1. Common parser idioms
The space characters, for the purposes of this specification, are U+0020 SPACE,
U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), U+000B LINE
TABULATION, U+000C FORM FEED (FF), and U+000D CARRIAGE RETURN (CR).
Some of the micro-parsers described below follow the pattern of having an input
variable that holds the string being parsed, and having a position variable
pointing at the next character to parse in input.
For parsers based on this pattern, a step that requires the user agent to
collect a sequence of characters means that the following algorithm must be run,
with characters being the set of characters that can be collected:
Let input and position be the same variables as those of the same name in the
algorithm that invoked these steps.
Let result be the empty string.
While position doesn't point past the end of input and the character at
position is one of the characters, append that character to the end of result
and advance position to the next character in input.
Return result.
The step skip whitespace means that the user agent must collect a sequence of
characters that are space characters. The step skip Zs characters means that the
user agent must collect a sequence of characters that are in the Unicode
character class Zs. In both cases, the collected characters are not used.
[UNICODE]
3.2.2. Boolean attributes
A number of attributes in HTML5 are boolean attributes. The presence of a
boolean attribute on an element represents the true value, and the absence of
the attribute represents the false value.
If the attribute is present, its value must either be the empty string or the
attribute's canonical name, exactly, with no leading or trailing whitespace, and
in lowercase.
3.2.3. Numbers
3.2.3.1. Unsigned integers
A string is a valid non-negative integer if it consists of one of more
characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
The rules for parsing non-negative integers are as given in the following
algorithm. When invoked, the steps must be followed in the order given, aborting
at the first step that returns a value. This algorithm will either return zero,
a positive integer, or an error. Leading spaces are ignored. Trailing spaces and
indeed any trailing garbage characters are ignored.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the
string.
Let value have the value 0.
Skip whitespace.
If position is past the end of input, return an error.
If the next character is not one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE
(9), then return an error.
If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE
(9):
Multiply value by ten.
Add the value of the current character (0..9) to value.
Advance position to the next character.
If position is not past the end of input, return to the top of step 7 in the
overall algorithm (that's the step within which these substeps find
themselves).
Return value.
3.2.3.2. Signed integers
A string is a valid integer if it consists of one of more characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), optionally prefixed with a
U+002D HYPHEN-MINUS ("-") character.
The rules for parsing integers are similar to the rules for non-negative
integers, and are as given in the following algorithm. When invoked, the steps
must be followed in the order given, aborting at the first step that returns a
value. This algorithm will either return an integer or an error. Leading spaces
are ignored. Trailing spaces and trailing garbage characters are ignored.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the
string.
Let value have the value 0.
Let sign have the value "positive".
Skip whitespace.
If position is past the end of input, return an error.
If the character indicated by position (the first character) is a U+002D
HYPHEN-MINUS ("-") character:
Let sign be "negative".
Advance position to the next character.
If position is past the end of input, return an error.
If the next character is not one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE
(9), then return an error.
If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE
(9):
Multiply value by ten.
Add the value of the current character (0..9) to value.
Advance position to the next character.
If position is not past the end of input, return to the top of step 9 in the
overall algorithm (that's the step within which these substeps find
themselves).
If sign is "positive", return value, otherwise return 0-value.
3.2.3.3. Real numbers
A string is a valid floating point number if it consists of one of more
characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9),
optionally with a single U+002E FULL STOP (".") character somewhere (either
before these numbers, in between two numbers, or after the numbers), all
optionally prefixed with a U+002D HYPHEN-MINUS ("-") character.
The rules for parsing floating point number values are as given in the following
algorithm. As with the previous algorithms, when this one is invoked, the steps
must be followed in the order given, aborting at the first step that returns a
value. This algorithm will either return a number or an error. Leading spaces
are ignored. Trailing spaces and garbage characters are ignored.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the
string.
Let value have the value 0.
Let sign have the value "positive".
Skip whitespace.
If position is past the end of input, return an error.
If the character indicated by position (the first character) is a U+002D
HYPHEN-MINUS ("-") character:
Let sign be "negative".
Advance position to the next character.
If position is past the end of input, return an error.
If the next character is not one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE
(9) or U+002E FULL STOP ("."), then return an error.
If the next character is U+002E FULL STOP ("."), but either that is the last
character or the character after that one is not one of U+0030 DIGIT ZERO (0)
.. U+0039 DIGIT NINE (9), then return an error.
If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE
(9):
Multiply value by ten.
Add the value of the current character (0..9) to value.
Advance position to the next character.
If position is past the end of input, then if sign is "positive", return
value, otherwise return 0-value.
Otherwise return to the top of step 10 in the overall algorithm (that's the
step within which these substeps find themselves).
Otherwise, if the next character is not a U+002E FULL STOP ("."), then if sign
is "positive", return value, otherwise return 0-value.
The next character is a U+002E FULL STOP ("."). Advance position to the
character after that.
Let divisor be 1.
If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE
(9):
Multiply divisor by ten.
Add the value of the current character (0..9) divided by divisor, to value.
Advance position to the next character.
If position is past the end of input, then if sign is "positive", return
value, otherwise return 0-value.
Otherwise return to the top of step 14 in the overall algorithm (that's the
step within which these substeps find themselves).
Otherwise, if sign is "positive", return value, otherwise return 0-value.
3.2.3.4. Ratios
The algorithms described in this section are used by the progress and meter
elements.
A valid denominator punctuation character is one of the characters from the
table below. There is a value associated with each denominator punctuation
character, as shown in the table below. Denominator Punctuation Character
Value
U+0025 PERCENT SIGN % 100
U+066A ARABIC PERCENT SIGN ٪ 100
U+FE6A SMALL PERCENT SIGN ﹪ 100
U+FF05 FULLWIDTH PERCENT SIGN % 100
U+2030 PER MILLE SIGN ‰ 1000
U+2031 PER TEN THOUSAND SIGN ‱ 10000
The steps for finding one or two numbers of a ratio in a string are as follows:
If the string is empty, then return nothing and abort these steps.
Find a number in the string according to the algorithm below, starting at the
start of the string.
If the sub-algorithm in step 2 returned nothing or returned an error
condition, return nothing and abort these steps.
Set number1 to the number returned by the sub-algorithm in step 2.
Starting with the character immediately after the last one examined by the
sub-algorithm in step 2, skip any characters in the string that are in the
Unicode character class Zs (this might match zero characters). [UNICODE]
If there are still further characters in the string, and the next character in
the string is a valid denominator punctuation character, set denominator to
that character.
If the string contains any other characters in the range U+0030 DIGIT ZERO to
U+0039 DIGIT NINE, but denominator was given a value in the step 6, return
nothing and abort these steps.
Otherwise, if denominator was given a value in step 6, return number1 and
denominator and abort these steps.
Find a number in the string again, starting immediately after the last
character that was examined by the sub-algorithm in step 2.
If the sub-algorithm in step 9 returned nothing or an error condition, return
nothing and abort these steps.
Set number2 to the number returned by the sub-algorithm in step 9.
If there are still further characters in the string, and the next character in
the string is a valid denominator punctuation character, return nothing and
abort these steps.
If the string contains any other characters in the range U+0030 DIGIT ZERO to
U+0039 DIGIT NINE, return nothing and abort these steps.
Otherwise, return number1 and number2.
The algorithm to find a number is as follows. It is given a string and a
starting position, and returns either nothing, a number, or an error condition.
Starting at the given starting position, ignore all characters in the given
string until the first character that is either a U+002E FULL STOP or one of
the ten characters in the range U+0030 DIGIT ZERO to U+0039 DIGIT NINE.
If there are no such characters, return nothing and abort these steps.
Starting with the character matched in step 1, collect all the consecutive
characters that are either a U+002E FULL STOP or one of the ten characters in
the range U+0030 DIGIT ZERO to U+0039 DIGIT NINE, and assign this string of
one or more characters to string.
If string contains more than one U+002E FULL STOP character then return an
error condition and abort these steps.
Parse string according to the rules for parsing floating point number values,
to obtain number. This step cannot fail (string is guarenteed to be a valid
floating point number).
Return number.
3.2.3.5. Percentages and dimensions
valid positive non-zero integers rules for parsing dimension values (only used
by height/width on img, embed, object — lengths in css pixels or percentages)
3.2.3.6. Lists of integers
A valid list of integers is a number of valid integers separated by U+002C COMMA
characters, with no other characters (e.g. no space characters). In addition,
there might be restrictions on the number of integers that can be given, or on
the range of values allowed.
The rules for parsing a list of integers are as follows:
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the
string.
Let numbers be an initially empty list of integers. This list will be the
result of this algorithm.
If there is a character in the string input at position position, and it is
either U+002C COMMA character or a U+0020 SPACE character, then advance
position to the next character in input, or to beyond the end of the string if
there are no more characters.
If position points to beyond the end of input, return numbers and abort.
If the character in the string input at position position is a U+002C COMMA
character or a U+0020 SPACE character, return to step 4.
Let negated be false.
Let value be 0.
Let multiple be 1.
Let started be false.
Let finished be false.
Let bogus be false.
Parser: If the character in the string input at position position is:
A U+002D HYPHEN-MINUS character
Follow these substeps:
If finished is true, skip to the next step in the overall set of steps.
If started is true or if bogus is true, let negated be false.
Otherwise, if started is false and if bogus is false, let negated be true.
Let started be true.
A character in the range U+0030 DIGIT ZERO .. U+0039 DIGIT NINE
Follow these substeps:
If finished is true, skip to the next step in the overall set of steps.
Let n be the value of the digit, interpreted in base ten, multiplied by
multiple.
Add n to value.
If value is greater than zero, multiply multiple by ten.
Let started be true.
A U+002C COMMA character
A U+0020 SPACE character
Follow these substeps:
If started is false, return the numbers list and abort.
If negated is true, then negate value.
Append value to the numbers list.
Jump to step 4 in the overall set of steps.
A U+002E FULL STOP character
Follow these substeps:
Let finished be true.
Any other character
Follow these substeps:
If finished is true, skip to the next step in the overall set of steps.
Let negated be false.
Let bogus be true.
If started is true, then return the numbers list, and abort. (The value in
value is not appended to the list first; it is dropped.)
Advance position to the next character in input, or to beyond the end of the
string if there are no more characters.
If position points to a character (and not to beyond the end of input), jump
to the big Parser step above.
If negated is true, then negate value.
If started is true, then append value to the numbers list, return that list,
and abort.
Return the numbers list and abort.
3.2.4. Dates and times
In the algorithms below, the number of days in month month of year year is: 31
if month is 1, 3, 5, 7, 8, 10, or 12; 30 if month is 4, 6, 9, or 11; 29 if month
is 2 and year is a number divisible by 400, or if year is a number divisible by
4 but not by 100; and 28 otherwise. This takes into account leap years in the
Gregorian calendar. [GREGORIAN]
3.2.4.1. Specific moments in time
A string is a valid datetime if it has four digits (representing the year), a
literal hyphen, two digits (representing the month), a literal hyphen, two
digits (representing the day), optionally some spaces, either a literal T or a
space, optionally some more spaces, two digits (for the hour), a colon, two
digits (the minutes), optionally the seconds (which, if included, must consist
of another colon, two digits (the integer part of the seconds), and optionally a
decimal point followed by one or more digits (for the fractional part of the
seconds)), optionally some spaces, and finally either a literal Z (indicating
the time zone is UTC), or, a plus sign or a minus sign followed by two digits, a
colon, and two digits (for the sign, the hours and minutes of the timezone
offset respectively); with the month-day combination being a valid date in the
given year according to the Gregorian calendar, the hour values (h) being in the
range 0 ≤ h ≤ 23, the minute values (m) in the range 0 ≤ m ≤ 59, and the second
value (s) being in the range 0 ≤ h < 60. [GREGORIAN]
The digits must be characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT
NINE (9), the hyphens must be a U+002D HYPHEN-MINUS characters, the T must be a
U+0054 LATIN CAPITAL LETTER T, the colons must be U+003A COLON characters, the
decimal point must be a U+002E FULL STOP, the Z must be a U+005A LATIN CAPITAL
LETTER Z, the plus sign must be a U+002B PLUS SIGN, and the minus U+002D (same
as the hyphen).
The following are some examples of dates written as valid datetimes.
"0037-12-13 00:00 Z"
Midnight UTC on the birthday of Nero (the Roman Emperor).
"1979-10-14T12:00:00.001-04:00"
One millisecond after noon on October 14th 1979, in the time zone in use on
the east coast of North America during daylight saving time.
"8592-01-01 T 02:09 +02:09"
Midnight UTC on the 1st of January, 8592. The time zone associated with that
time is two hours and nine minutes ahead of UTC.
Several things are notable about these dates:
Years with fewer than four digits have to be zero-padded. The date "37-12-13"
would not be a valid date.
To unambiguously identify a moment in time prior to the introduction of the
Gregorian calendar, the date has to be first converted to the Gregorian
calendar from the calendar in use at the time (e.g. from the Julian calendar).
The date of Nero's birth is the 15th of December 37, in the Julian Calendar,
which is the 13th of December 37 in the Gregorian Calendar.
The time and timezone components are not optional.
Dates before the year 0 or after the year 9999 can't be represented as a
datetime in this version of HTML.
Time zones differ based on daylight savings time.
Conformance checkers can use the algorithm below to determine if a datetime is a
valid datetime or not.
To parse a string as a datetime value, a user agent must apply the following
algorithm to the string. This will either return a time in UTC, with associated
timezone information for round tripping or display purposes, or nothing,
indicating the value is not a valid datetime. If at any point the algorithm says
that it "fails", this means that it returns nothing.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the
string.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9). If the collected sequence is not exactly four characters long,
then fail. Otherwise, interpret the resulting sequence as a base ten integer.
Let that number be the year.
If position is beyond the end of input or if the character at position is not
a U+002D HYPHEN-MINUS character, then fail. Otherwise, move position forwards
one character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9). If the collected sequence is not exactly two characters long,
then fail. Otherwise, interpret the resulting sequence as a base ten integer.
Let that number be the month.
If month is not a number in the range 1 ≤ month ≤ 12, then fail.
Let maxday be the number of days in month month of year year.
If position is beyond the end of input or if the character at position is not
a U+002D HYPHEN-MINUS character, then fail. Otherwise, move position forwards
one character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9). If the collected sequence is not exactly two characters long,
then fail. Otherwise, interpret the resulting sequence as a base ten integer.
Let that number be the day.
If day is not a number in the range 1 ≤ month ≤ maxday, then fail.
Collect a sequence of characters that are either U+0054 LATIN CAPITAL LETTER T
characters or space characters. If the collected sequence is zero characters
long, or if it contains more than one U+0054 LATIN CAPITAL LETTER T character,
then fail.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9). If the collected sequence is not exactly two characters long,
then fail. Otherwise, interpret the resulting sequence as a base ten integer.
Let that number be the hour.
If hour is not a number in the range 0 ≤ hour ≤ 23, then fail.
If position is beyond the end of input or if the character at position is not
a U+003A COLON character, then fail. Otherwise, move position forwards one
character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9). If the collected sequence is not exactly two characters long,
then fail. Otherwise, interpret the resulting sequence as a base ten integer.
Let that number be the minute.
If minute is not a number in the range 0 ≤ minute ≤ 59, then fail.
Let second be a string with the value "0".
If position is beyond the end of input, then fail.
If the character at position is a U+003A COLON, then:
Advance position to the next character in input.
If position is beyond the end of input, or at the last character in input,
or if the next two characters in input starting at position are not two
characters both in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9),
then fail.
Collect a sequence of characters that are either characters in the range
U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) or U+002E FULL STOP
characters. If the collected sequence has more than one U+002E FULL STOP
characters, or if the last character in the sequence is a U+002E FULL STOP
character, then fail. Otherwise, let the collected string be second instead
of its previous value.
Interpret second as a base ten number (possibly with a fractional part). Let
that number be second instead of the string version.
If second is not a number in the range 0 ≤ hour < 60, then fail. (The values
60 and 61 are not allowed: leap seconds cannot be represented by datetime
values.)
If position is beyond the end of input, then fail.
Skip whitespace.
If the character at position is a U+005A LATIN CAPITAL LETTER Z, then:
Let timezonehours be 0.
Let timezoneminutes be 0.
Advance position to the next character in input.
Otherwise, if the character at position is either a U+002B PLUS SIGN ("+") or
a U+002D HYPHEN-MINUS ("-"), then:
If the character at position is a U+002B PLUS SIGN ("+"), let sign be
"positive". Otherwise, it's a U+002D HYPHEN-MINUS ("-"); let sign be
"negative".
Advance position to the next character in input.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9). If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a
base ten integer. Let that number be the timezonehours.
If timezonehours is not a number in the range 0 ≤ timezonehours ≤ 23, then
fail.
If sign is "negative", then negate timezonehours.
If position is beyond the end of input or if the character at position is
not a U+003A COLON character, then fail. Otherwise, move position forwards
one character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9). If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a
base ten integer. Let that number be the timezoneminutes.
If timezoneminutes is not a number in the range 0 ≤ timezoneminutes ≤ 59,
then fail.
If sign is "negative", then negate timezoneminutes.
If position is not beyond the end of input, then fail.
Let time be the moment in time at year year, month month, day day, hours hour,
minute minute, second second, subtracting timezonehours hours and
timezoneminutes minutes. That moment in time is a moment in the UTC timezone.
Let timezone be timezonehours hours and timezoneminutes minutes from UTC.
Return time and timezone.
3.2.4.2. Vaguer moments in time
This section defines date or time strings. There are two kinds, date or time
strings in content, and date or time strings in attributes. The only difference
is in the handling of whitespace characters.
To parse a date or time string, user agents must use the following algorithm. A
date or time string is a valid date or time string if the following algorithm,
when run on the string, doesn't say the string is invalid.
The algorithm may return nothing (in which case the string will be invalid), or
it may return a date, a time, a date and a time, or a date and a time and and a
timezone. Even if the algorithm returns one or more values, the string can still
be invalid.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the
string.
Let results be the collection of results that are to be returned (one or more
of a date, a time, and a timezone), initially empty. If the algorithm aborts
at any point, then whatever is currently in results must be returned as the
result of the algorithm.
For the "in content" variant: skip Zs characters; for the "in attributes"
variant: skip whitespace.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9). If the collected sequence is empty, then the string is
invalid; abort these steps.
Let the sequence of characters collected in the last step be s.
If position is past the end of input, the string is invalid; abort these
steps.
If the character at position is not a U+003A COLON character, then:
If the character at position is not a U+002D HYPHEN-MINUS ("-") character
either, then the string is invalid, abort these steps.
If the sequence s is not exactly four digits long, then the string is
invalid. (This does not stop the algorithm, however.)
Interpret the sequence of characters collected in step 5 as a base ten
integer, and let that number be year.
Advance position past the U+002D HYPHEN-MINUS ("-") character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9). If the collected sequence is empty, then the string
is invalid; abort these steps.
If the sequence collected in the last step is not exactly two digits long,
then the string is invalid.
Interpret the sequence of characters collected two steps ago as a base ten
integer, and let that number be month.
If month is not a number in the range 1 ≤ month ≤ 12, then the string is
invalid, abort these steps.
Let maxday be the number of days in month month of year year.
If position is past the end of input, or if the character at position is not
a U+002D HYPHEN-MINUS ("-") character, then the string is invalid, abort
these steps. Otherwise, advance position to the next character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9). If the collected sequence is empty, then the string
is invalid; abort these steps.
If the sequence collected in the last step is not exactly two digits long,
then the string is invalid.
Interpret the sequence of characters collected two steps ago as a base ten
integer, and let that number be day.
If day is not a number in the range 1 ≤ day ≤ maxday, then the string is
invalid, abort these steps.
Add the date represented by year, month, and day to the results.
For the "in content" variant: skip Zs characters; for the "in attributes"
variant: skip whitespace.
If the character at position is a U+0054 LATIN CAPITAL LETTER T, then move
position forwards one character.
For the "in content" variant: skip Zs characters; for the "in attributes"
variant: skip whitespace.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9). If the collected sequence is empty, then the string
is invalid; abort these steps.
Let s be the sequence of characters collected in the last step.
If s is not exactly two digits long, then the string is invalid.
Interpret the sequence of characters collected two steps ago as a base ten
integer, and let that number be hour.
If hour is not a number in the range 0 ≤ hour ≤ 23, then the string is
invalid, abort these steps.
If position is past the end of input, or if the character at position is not a
U+003A COLON character, then the string is invalid, abort these steps.
Otherwise, advance position to the next character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9). If the collected sequence is empty, then the string is
invalid; abort these steps.
If the sequence collected in the last step is not exactly two digits long,
then the string is invalid.
Interpret the sequence of characters collected two steps ago as a base ten
integer, and let that number be minute.
If minute is not a number in the range 0 ≤ minute ≤ 59, then the string is
invalid, abort these steps.
Let second be 0. It may be changed to another value in the next step.
If position is not past the end of input and the character at position is a
U+003A COLON character, then:
Collect a sequence of characters that are either characters in the range
U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) or are U+002E FULL STOP. If
the collected sequence is empty, or contains more than one U+002E FULL STOP
character, then the string is invalid; abort these steps.
If the first character in the sequence collected in the last step is not in
the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), then the string is
invalid.
Interpret the sequence of characters collected two steps ago as a base ten
number (possibly with a fractional part), and let that number be second.
If second is not a number in the range 0 ≤ minute < 60, then the string is
invalid, abort these steps.
Add the time represented by hour, minute, and second to the results.
If results has both a date and a time, then:
For the "in content" variant: skip Zs characters; for the "in attributes"
variant: skip whitespace.
If position is past the end of input, then skip to the next step in the
overall set of steps.
Otherwise, if the character at position is a U+005A LATIN CAPITAL LETTER Z,
then:
Add the timezone corresponding to UTC (zero offset) to the results.
Advance position to the next character in input.
Skip to the next step in the overall set of steps.
Otherwise, if the character at position is either a U+002B PLUS SIGN ("+")
or a U+002D HYPHEN-MINUS ("-"), then:
If the character at position is a U+002B PLUS SIGN ("+"), let sign be
"positive". Otherwise, it's a U+002D HYPHEN-MINUS ("-"); let sign be
"negative".
Advance position to the next character in input.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9). If the collected sequence is not exactly two
characters long, then the string is invalid.
Interpret the sequence collected in the last step as a base ten number,
and let that number be timezonehours.
If timezonehours is not a number in the range 0 ≤ timezonehours ≤ 23, then
the string is invalid; abort these steps.
If sign is "negative", then negate timezonehours.
If position is beyond the end of input or if the character at position is
not a U+003A COLON character, then the string is invalid; abort these
steps. Otherwise, move position forwards one character.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9). If the collected sequence is not exactly two
characters long, then the string is invalid.
Interpret the sequence collected in the last step as a base ten number,
and let that number be timezoneminutes.
If timezoneminutes is not a number in the range 0 ≤ timezoneminutes ≤ 59,
then the string is invalid; abort these steps.
Add the timezone corresponding to an offset of timezonehours hours and
timezoneminutes minutes to the results.
Skip to the next step in the overall set of steps.
Otherwise, the string is invalid; abort these steps.
For the "in content" variant: skip Zs characters; for the "in attributes"
variant: skip whitespace.
If position is not past the end of input, then the string is invalid.
Abort these steps (the string is parsed).
3.2.5. Time offsets
valid time offset, rules for parsing time offsets, time offset serialisation
rules; in the format "5d4h3m2s1ms" or "3m 9.2s" or "00:00:00.00" or similar.
3.2.6. Tokens
A set of space-separated tokens is a set of zero or more words separated by one
or more space characters, where words consist of any string of one or more
characters, none of which are space characters.
A string containing a set of space-separated tokens may have leading or trailing
space characters.
An unordered set of unique space-separated tokens is a set of space-separated
tokens where none of the words are duplicated.
An ordered set of unique space-separated tokens is a set of space-separated
tokens where none of the words are duplicated but where the order of the tokens
is meaningful.
When a user agent has to split a string on spaces, it must use the following
algorithm:
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the
string.
Let tokens be a list of tokens, initially empty.
Skip whitespace
While position is not past the end of input:
Collect a sequence of characters that are not space characters.
Add the string collected in the previous step to tokens.
Skip whitespace
Return tokens.
When a user agent has to remove a token from a string, it must use the following
algorithm:
Let input be the string being modified.
Let token be the token being removed. It will not contain any space
characters.
Let output be the output string, initially empty.
Let position be a pointer into input, initially pointing at the start of the
string.
If position is beyond the end of input, set the string being modified to
output, and abort these steps.
If the character at position is a space character:
Append the character at position to the end of output.
Increment position so it points at the next character in input.
Return to step 5 in the overall set of steps.
Otherwise, the character at position is the first character of a token.
Collect a sequence of characters that are not space characters, and let that
be s.
If s is exactly equal to token, then:
Skip whitespace (in input).
Remove any space characters currently at the end of output.
If position is not past the end of input, and output is not the empty
string, append a single U+0020 SPACE character at the end of output.
Otherwise, append s to the end of output.
Return to step 6 in the overall set of steps.
This causes any occurrences of the token to be removed from the string, and any
spaces that were surrounding the token to be collapsed to a single space, except
at the start and end of the string, where such spaces are removed.
3.2.7. Keywords and enumerated attributes
Some attributes are defined as taking one of a finite set of keywords. Such
attributes are called enumerated attributes. The keywords are each defined to
map to a particular state (several keywords might map to the same state, in
which case some of the keywords are synonyms of each other; additionally, some
of the keywords can be said to be non-conforming, and are only in the
specification for historical reasons). In addition, two default states can be
given. The first is the invalid value default, the second is the missing value
default.
If an enumerated attribute is specified, the attribute's value must be one of
the given keywords that are not said to be non-conforming, with no leading or
trailing whitespace. The keyword may use any mix of uppercase and lowercase
letters.
When the attribute is specified, if its value case-insensitively matches one of
the given keywords then that keyword's state is the state that the attribute
represents. If the attribute value matches none of the given keywords, but the
attribute has an invalid value default, then the attribute represents that
state. Otherwise, if the attribute value matches none of the keywords but there
is a missing value default state defined, then that is the state represented by
the attribute. Otherwise, there is no default, and invalid values must simply be
ignored.
When the attribute is not specified, if there is a missing value default state
defined, then that is the state represented by the (missing) attribute.
Otherwise, the absence of the attribute means that there is no state
represented.
The empty string can be one of the keywords in some cases. For example the
contenteditable attribute has two states: true, matching the true keyword and
the empty string, false, matching false and all other keywords (it's the invalid
value default). It could further be thought of as having a third state inherit,
which would be the default when the attribute is not specified at all (the
missing value default), but for various reasons that isn't the way this
specification actually defines it.
3.2.8. References
A valid hashed ID reference to an element of type type is a string consisting of
a U+0023 NUMBER SIGN (#) character followed by a string which exactly matches
the value of the id attribute of an element in the document with type type.
The rules for parsing a hashed ID reference to an element of type type are as
follows:
If the string being parsed does not contain a U+0023 NUMBER SIGN character, or
if the first such character in the string is the last character in the string,
then return null and abort these steps.
Let s be the string from the character immediately after the first U+0023
NUMBER SIGN character in the string being parsed up to the end of that string.
Return the first element of type type that has an id or name attribute whose
value case-insensitively matches s.
3.3. Documents and document fragments
3.3.1. Semantics
Elements, attributes, and attribute values in HTML are defined (by this
specification) to have certain meanings (semantics). For example, the ol element
represents an ordered list, and the lang attribute represents the language of
the content.
Authors must only use elements, attributes, and attribute values for their
appropriate semantic purposes.
For example, the following document is non-conforming, despite being
syntactically correct:
Demonstration
This next document fragment, intended to represent the heading of a corporate
site, is similarly non-conforming because the second line is not intended to be
a heading of a subsection, but merely a subheading or subtitle (a subordinate
heading for the same section).
ABC Company
Leading the way in widget design since 1432
...The header element should be used in these kinds of situations:
ABC Company
Leading the way in widget design since 1432
...Through scripting and using other mechanisms, the values of attributes, text,
and indeed the entire structure of the document may change dynamically while a
user agent is processing it. The semantics of a document at an instant in time
are those represented by the state of the document at that instant in time, and
the semantics of a document can therefore change over time. User agents must
update their presentation of the document as this occurs.
HTML has a progress element that describes a progress bar. If its "value"
attribute is dynamically updated by a script, the UA would update the rendering
to show the progress changing.
3.3.2. Structure
All the elements in this specification have a defined content model, which
describes what nodes are allowed inside the elements, and thus what the
structure of an HTML document or fragment must look like. Authors must only put
elements inside an element if that element allows them to be there according to
its content model.
As noted in the conformance and terminology sections, for the purposes of
determining if an element matches its content model or not, CDATASection nodes
in the DOM are treated as equivalent to Text nodes, and entity reference nodes
are treated as if they were expanded in place.
The space characters are always allowed between elements. User agents represent
these characters between elements in the source markup as text nodes in the DOM.
Empty text nodes and text nodes consisting of just sequences of those characters
are considered inter-element whitespace.
Inter-element whitespace, comment nodes, and processing instruction nodes must
be ignored when establishing whether an element matches its content model or
not, and must be ignored when following algorithms that define document and
element semantics.
An element A is said to be preceded or followed by a second element B if A and B
have the same parent node and there are no other element nodes or text nodes
(other than inter-element whitespace) between them.
Authors must only use elements in the HTML namespace in the contexts where they
are allowed, as defined for each element. For XML compound documents, these
contexts could be inside elements from other namespaces, if those elements are
defined as providing the relevant contexts.
The SVG specification defines the SVG foreignObject element as allowing foreign
namespaces to be included, thus allowing compound documents to be created by
inserting subdocument content under that element. This specification defines the
XHTML html element as being allowed where subdocument fragments are allowed in a
compound document. Together, these two definitions mean that placing an XHTML
html element as a child of an SVG foreignObject element is conforming.
3.3.3. Kinds of content
Each element in HTML falls into zero or more categories that group elements with
similar characteristics together. The following categories are used in this
specification:
Metadata content
Prose content
Sectioning content
Heading content
Phrasing content
Embedded content
Form control content
Interactive content
Some elements have unique requirements and do not fit into any particular
category.
3.3.3.1. Metadata content
Metadata content is content that sets up the presentation or behaviour of the
rest of the content, or that sets up the relationship of the document with other
documents, or that conveys other "out of band" information.
Elements from other namespaces whose semantics are primarily metadata-related
(e.g. RDF) are also metadata content.
3.3.3.2. Prose content
Most elements that are used in the body of documents and applications are
categorised as prose content.
As a general rule, elements whose content model allows any prose content should
have either at least one descendant text node that is not inter-element
whitespace, or at least one descendant element node that is embedded content.
For the purposes of this requirement, del elements and their descendants must
not be counted as contributing to the ancestors of the del element.
This requirement is not a hard requirement, however, as there are many cases
where an element can be empty legitimately, for example when it is used as a
placeholder which will later be filled in by a script, or when the element is
part of a template and would on most pages be filled in but on some pages is not
relevant.
3.3.3.3. Sectioning content
Sectioning content is content that defines the scope of headers, footers, and
contact information.
Each sectioning content element potentially has a heading. See the section on
headings and sections for further details.
3.3.3.4. Heading content
Heading content defines the header of a section (whether explicitly marked up
using sectioning content elements, or implied by the heading content itself).
3.3.3.5. Phrasing content
Phrasing content is the text of the document, as well as elements that mark up
that text at the intra-paragraph level. Runs of phrasing content form
paragraphs.
All phrasing content is also prose content. Any content model that expects prose
content also expects phrasing content.
As a general rule, elements whose content model allows any phrasing content
should have either at least one descendant text node that is not inter-element
whitespace, or at least one descendant element node that is embedded content.
For the purposes of this requirement, nodes that are descendants of del elements
must not be counted as contributing to the ancestors of the del element.
Most elements that are categorised as phrasing content can only contain elements
that are themselves categorised as phrasing content, not any prose content.
Text nodes that are not inter-element whitespace are phrasing content.
3.3.3.6. Embedded content
Embedded content is content that imports another resource into the document, or
content from another vocabulary that is inserted into the document.
All embedded content is also phrasing content (and prose content). Any content
model that expects phrasing content (or prose content) also expects embedded
content.
Elements that are from namespaces other than the HTML namespace and that convey
content but not metadata, are embedded content for the purposes of the content
models defined in this specification. (For example, MathML, or SVG.)
Some embedded content elements can have fallback content: content that is to be
used when the external resource cannot be used (e.g. because it is of an
unsupported format). The element definitions state what the fallback is, if any.
3.3.3.7. Interactive content
Parts of this section should eventually be moved to DOM3 Events.
Interactive content is content that is specifically intended for user
interaction.
Certain elements in HTML can be activated, for instance a elements, button
elements, or input elements when their type attribute is set to radio.
Activation of those elements can happen in various (UA-defined) ways, for
instance via the mouse or keyboard.
When activation is performed via some method other than clicking the pointing
device, the default action of the event that triggers the activation must,
instead of being activating the element directly, be to fire a click event on
the same element.
The default action of this click event, or of the real click event if the
element was activated by clicking a pointing device, must be to fire a further
DOMActivate event at the same element, whose own default action is to go through
all the elements the DOMActivate event bubbled through (starting at the target
node and going towards the Document node), looking for an element with an
activation behavior; the first element, in reverse tree order, to have one, must
have its activation behavior executed.
The above doesn't happen for arbitrary synthetic events dispatched by author
script. However, the click() method can be used to make it happen
programmatically.
For certain form controls, this process is complicated further by changes that
must happen around the click event. [WF2]
Most interactive elements have content models that disallow nesting interactive
elements.
3.3.4. Transparent content models
Some elements are described as transparent; they have "transparent" as their
content model. Some elements are described as semi-transparent; this means that
part of their content model is "transparent" but that is not the only part of
the content model that must be satisfied.
When a content model includes a part that is "transparent", those parts must
only contain content that would still be conformant if all transparent and
semi-transparent elements in the tree were replaced, in their parent element, by
the children in the "transparent" part of their content model, retaining order.
When a transparent or semi-transparent element has no parent, then the part of
its content model that is "transparent" must instead be treated as accepting any
prose content.
3.3.5. Paragraphs
A paragraph is typically a block of text with one or more sentences that discuss
a particular topic, as in typography, but can also be used for more general
thematic grouping. For instance, an address is also a paragraph, as is a part of
a form, a byline, or a stanza in a poem.
Paragraphs in prose content are defined relative to what the document looks like
without the ins and del elements complicating matters. Let view be a view of the
DOM that replaces all ins and del elements in the document with their contents.
Then, in view, for each run of phrasing content uninterrupted by other types of
content, in an element that accepts content other than phrasing content, let
first be the first node of the run, and let last be the last node of the run.
For each run, a paragraph exists in the original DOM from immediately before
first to immediately after last. (Paragraphs can thus span across ins and del
elements.)
A paragraph is also formed by p elements.
The p element can be used to wrap individual paragraphs when there would
otherwise not be any content other than phrasing content to separate the
paragraphs from each other.
In the following example, there are two paragraphs in a section. There is also a
header, which contains phrasing content that is not a paragraph. Note how the
comments and intra-element whitespace do not form paragraphs.
Example of paragraphs
This is the first paragraph in this example.
This is the second.
The following example takes that markup and puts ins and del elements around
some of the markup to show that the text was changed (though in this case, the
changes don't really make much sense, admittedly). Notice how this example has
exactly the same paragraphs as the previous one, despite the ins and del
elements.
Example of paragraphs
This is the first paragraph in this example.
This is the second.
3.4. Global attributes
The following attributes are common to and may be specified on all HTML elements
(even those not defined in this specification):
Global attributes:
class
contenteditable
contextmenu
dir
draggable
id
irrelevant
lang
ref
registrationmark
tabindex
template
title
In addition, the following event handler content attributes may be specified on
any HTML element:
Event handler content attributes:
onabort
onbeforeunload
onblur
onchange
onclick
oncontextmenu
ondblclick
ondrag
ondragend
ondragenter
ondragleave
ondragover
ondragstart
ondrop
onerror
onfocus
onkeydown
onkeypress
onkeyup
onload
onmessage
onmousedown
onmousemove
onmouseout
onmouseover
onmouseup
onmousewheel
onresize
onscroll
onselect
onsubmit
onunload
3.4.1. The id attribute
The id attribute represents its element's unique identifier. The value must be
unique in the subtree within which the element finds itself and must contain at
least one character. The value must not contain any space characters.
If the value is not the empty string, user agents must associate the element
with the given value (exactly, including any space characters) for the purposes
of ID matching within the subtree the element finds itself (e.g. for selectors
in CSS or for the getElementById() method in the DOM).
Identifiers are opaque strings. Particular meanings should not be derived from
the value of the id attribute.
This specification doesn't preclude an element having multiple IDs, if other
mechanisms (e.g. DOM Core methods) can set an element's ID in a way that doesn't
conflict with the id attribute.
The id DOM attribute must reflect the id content attribute.
3.4.2. The title attribute
The title attribute represents advisory information for the element, such as
would be appropriate for a tooltip. On a link, this could be the title or a
description of the target resource; on an image, it could be the image credit or
a description of the image; on a paragraph, it could be a footnote or commentary
on the text; on a citation, it could be further information about the source;
and so forth. The value is text.
If this attribute is omitted from an element, then it implies that the title
attribute of the nearest ancestor HTML element with a title attribute set is
also relevant to this element. Setting the attribute overrides this, explicitly
stating that the advisory information of any ancestors is not relevant to this
element. Setting the attribute to the empty string indicates that the element
has no advisory information.
If the title attribute's value contains U+000A LINE FEED (LF) characters, the
content is split into multiple lines. Each U+000A LINE FEED (LF) character
represents a line break.
Some elements, such as link and dfn, define additional semantics for the title
attribute beyond the semantics described above.
The title DOM attribute must reflect the title content attribute.
3.4.3. The lang (HTML only) and xml:lang (XML only) attributes
The lang attribute specifies the primary language for the element's contents and
for any of the element's attributes that contain text. Its value must be a valid
RFC 3066 language code, or the empty string. [RFC3066]
The xml:lang attribute is defined in XML. [XML]
If these attributes are omitted from an element, then it implies that the
language of this element is the same as the language of the parent element.
Setting the attribute to the empty string indicates that the primary language is
unknown.
The lang attribute may only be used on elements of HTML documents. Authors must
not use the lang attribute in XML documents.
The xml:lang attribute may only be used on elements of XML documents. Authors
must not use the xml:lang attribute in HTML documents.
To determine the language of a node, user agents must look at the nearest
ancestor element (including the element itself if the node is an element) that
has an xml:lang attribute set or is an HTML element and has a lang attribute
set. That attribute specifies the language of the node.
If both the xml:lang attribute and the lang attribute are set on an element,
user agents must use the xml:lang attribute, and the lang attribute must be
ignored for the purposes of determining the element's language.
If no explicit language is given for the root element, then language information
from a higher-level protocol (such as HTTP), if any, must be used as the final
fallback language. In the absence of any language information, the default value
is unknown (the empty string).
User agents may use the element's language to determine proper processing or
rendering (e.g. in the selection of appropriate fonts or pronounciations, or for
dictionary selection).
The lang DOM attribute must reflect the lang content attribute.
3.4.4. The dir attribute
The dir attribute specifies the element's text directionality. The attribute is
an enumerated attribute with the keyword ltr mapping to the state ltr, and the
keyword rtl mapping to the state rtl. The attribute has no defaults.
If the attribute has the state ltr, the element's directionality is
left-to-right. If the attribute has the state rtl, the element's directionality
is right-to-left. Otherwise, the element's directionality is the same as its
parent.
The processing of this attribute depends on the presentation layer. For example,
CSS 2.1 defines a mapping from this attribute to the CSS 'direction' and
'unicode-bidi' properties, and defines rendering in terms of those properties.
The dir DOM attribute on an element must reflect the dir content attribute of
that element, limited to only known values.
The dir DOM attribute on HTMLDocument objects must reflect the dir content
attribute of the html element, if any, limited to only known values. If there is
no such element, then the attribute must return the empty string and do nothing
on setting.
3.4.5. The class attribute
Every HTML element may have a class attribute specified.
The attribute, if specified, must have a value that is an unordered set of
unique space-separated tokens representing the various classes that the element
belongs to.
The classes that an HTML element has assigned to it consists of all the classes
returned when the value of the class attribute is split on spaces.
Assigning classes to an element affects class matching in selectors in CSS, the
getElementsByClassName() method in the DOM, and other such features.
Authors may use any value in the class attribute, but are encouraged to use the
values that describe the nature of the content, rather than values that describe
the desired presentation of the content.
The className and classList DOM attributes must both reflect the class content
attribute.
3.4.6. The irrelevant attribute
All elements may have the irrelevant content attribute set. The irrelevant
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 irrelevant attribute specified.
In the following skeletal example, the attribute is used to hide the Web game's
main screen until the user logs in:
The Example Game
Login
...
The irrelevant attribute must not be used to hide content that could
legitimately be shown in another presentation. For example, it is incorrect to
use irrelevant to hide panels in a tabbed dialog, because the tabbed interface
is merely a kind of overflow presentation — showing all the form controls in one
big page with a scrollbar would be equivalent, and no less correct.
Elements in a section hidden by the irrelevant attribute are still active, e.g.
scripts and form controls in such sections still render execute and submit
respectively. Only their presentation to the user changes.
The irrelevant DOM attribute must reflect the content attribute of the same
name.
3.5. Interaction
3.5.1. Activation
The click() method must fire a click event at the element, whose default action
is the firing of a further DOMActivate event at the same element, whose own
default action is to go through all the elements the DOMActivate event bubbled
through (starting at the target node and going towards the Document node),
looking for an element with an activation behavior; the first element, in
reverse tree order, to have one, must have its activation behavior executed.
3.5.2. Focus
When an element is focused, key events received by the document must be targeted
at that element. There is always an element focused; in the absence of other
elements being focused, the document's root element is it.
Which element within a document currently has focus is independent of whether or
not the document itself has the system focus.
Some focusable elements might take part in sequential focus navigation.
3.5.2.1. Focus management
The focus() and blur() methods must focus and unfocus the element respectively,
if the element is focusable.
Some elements, most notably area, can correspond to more than one distinct
focusable area. When such an element is focused using the focus() method, the
first such region in tree order is the one that must be focused.
Well that clearly needs more.
The activeElement attribute must return the element in the document that has
focus. If no element specifically has focus, this must return the body element.
The hasFocus attribute must return true if the document, one of its nested
browsing contexts, or any element in the document or its browsing contexts
currently has the system focus.
3.5.2.2. Sequential focus navigation
This section on the tabindex attribute needs to be checked for
backwards-compatibility.
The tabindex attribute specifies the relative order of elements 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.
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. If parsing the value returns an error, the attribute is ignored for
the purposes of focus management (as if it wasn't specified).
A positive integer or zero specifies the index of the element in the current
scope's tab order. Elements with the same index are sorted in tree order for the
purposes of tabbing.
A negative integer specifies that the element should be removed from the tab
order. If the element does normally take focus, it may still be focused using
other means (e.g. it could be focused by a click).
If the attribute is absent (or invalid), then the user agent must treat the
element as if it had the value 0 or the value -1, based on platform conventions.
For example, a user agent might default textarea elements to 0, and button
elements to -1, making text fields part of the tabbing cycle but buttons not.
When an element that does not normally take focus (i.e. whose default value
would be -1) has the tabindex attribute specified with a positive value, then it
should be added to the tab order and should be made focusable. When focused, the
element matches the CSS :focus pseudo-class and key events are dispatched on
that element in response to keyboard input.
The tabIndex DOM attribute reflects the value of the tabIndex content attribute.
If the attribute is not present (or has an invalid value) then the DOM attribute
must return the UA's default value for that element, which will be either 0 (for
elements in the tab order) or -1 (for elements not in the tab order).
3.5.3. Scrolling elements into view
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.
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 must
instead simply align the top of the element with the top of the viewport.
Non-visual user agents may ignore the argument, or may treat it in some
media-specific manner most useful to the user.
3.6. The root element
3.6.1. The html element
Categories
None.
Contexts in which this element may be used:
As the root element of a document.
Wherever a subdocument fragment is allowed in a compound document.
Content model:
A head element followed by a body element.
Element-specific attributes:
manifest
DOM interface:
No difference from HTMLElement.
The html element represents the root of an HTML document.
The manifest attribute gives the address of the document's application cache
manifest, if there is one. If the attribute is present, the attribute's value
must be a valid URI (or IRI).
The manifest attribute only has an effect during the early stages of document
load. Changing the attribute dynamically thus has no effect (and thus, no DOM
API is provided for this attribute). Furthermore, as it is processed before any
base elements are seen, its value is not subject to being made relative to any
base URI.
Though it has absolutely no effect and no meaning, the html element, in HTML
documents, may have an xmlns attribute specified, if, and only if, it has the
exact value "http://www.w3.org/1999/xhtml". This does not apply to XML
documents.
In HTML, the xmlns attribute has absolutely no effect. It is basically a
talisman. It is allowed merely to make migration to and from XHTML mildly
easier. When parsed by an HTML parser, the attribute ends up in the null
namespace, not the "http://www.w3.org/2000/xmlns/" namespace like namespace
declaration attributes in XML do.
In XML, an xmlns attribute is part of the namespace declaration mechanism, and
an element cannot actually have an xmlns attribute in the null namespace
specified.
3.7. Document metadata
3.7.1. The head element
Categories
None.
Contexts in which this element may be used:
As the first element in an html element.
Content model:
One or more elements of metadata content, of which exactly one is a title
element.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The head element collects the document's metadata.
3.7.2. The title element
Categories
Metadata content.
Contexts in which this element may be used:
In a head element containing no other title elements.
Content model:
Text.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The title element represents the document's title or name. Authors should use
titles that identify their documents even when they are used out of context, for
example in a user's history or bookmarks, or in search results. The document's
title is often different from its first header, since the first header does not
have to stand alone when taken out of context.
There must be no more than one title element per document.
The title element must not contain any elements.
Here are some examples of appropriate titles, contrasted with the top-level
headers that might be used on those same pages.
Introduction to The Mating Rituals of Bees
...
Introduction
This companion guide to the highly successful
Introduction to Medieval Bee-Keeping book is...
The next page might be a part of the same site. Note how the title describes the
subject matter unambiguously, while the first header assumes the reader knowns
what the context is and therefore won't wonder if the dances are Salsa or Waltz:
Dances used during bee mating rituals
...
The Dances
The string to use as the document's title is given by the document.title DOM
attribute. User agents should use the document's title when referring to the
document in their user interface.
3.7.3. The base element
Categories
Metadata content.
Contexts in which this element may be used:
In a head element containing no other base elements.
Content model:
Empty.
Element-specific attributes:
href
target
DOM interface:
interface HTMLBaseElement : HTMLElement {
attribute DOMString href;
attribute DOMString target;
};The base element allows authors to specify the document's base URI for the
purposes of resolving relative URIs, and the name of the default browsing
context for the purposes of following hyperlinks.
There must be no more than one base element per document.
A base element must have either an href attribute, a target attribute, or both.
The href content attribute, if specified, must contain a URI (or IRI).
A base element, if it has an href attribute, must come before any other elements
in the tree that have attributes with URIs (except the html element and its
manifest attribute).
User agents must use the value of the href attribute of the first base element
that is both a child of the head element and has an href attribute, if there is
such an element, as the document entity's base URI for the purposes of section
5.1.1 of RFC 3986 ("Establishing a Base URI": "Base URI Embedded in Content").
This base URI from RFC 3986 is referred to by the algorithm given in XML Base,
which is a normative part of this specification. [RFC3986]
If the base URI given by this attribute is a relative URI, it must be resolved
relative to the higher-level base URIs (i.e. the base URI from the encapsulating
entity or the URI used to retrieve the entity) to obtain an absolute base URI.
All xml:base attributes must be ignored when resolving relative URIs in this
href attribute.
If there are multiple base elements with href attributes, all but the first are
ignored.
The target attribute, if specified, must contain a valid browsing context name.
User agents use this name when following hyperlinks.
A base element, if it has a target attribute, must come before any elements in
the tree that represent hyperlinks.
The href and target DOM attributes must reflect the content attributes of the
same name.
3.7.4. The link element
Categories
Metadata content.
Contexts in which this element may be used:
Where metadata content is expected.
In a noscript element that is a child of a head element.
Content model:
Empty.
Element-specific attributes:
href
rel
media
hreflang
type
Also, the title attribute has special semantics on this element.
DOM interface:
interface HTMLLinkElement : HTMLElement {
attribute boolean disabled;
attribute DOMString href;
attribute DOMString rel;
readonly attribute DOMTokenList relList;
attribute DOMString media;
attribute DOMString hreflang;
attribute DOMString type;
};The LinkStyle interface must also be implemented by this element, the styling
processing model defines how. [CSSOM]
The link element allows authors to link their document to other resources.
The destination of the link is given by the href attribute, which must be
present and must contain a URI (or IRI). If the href attribute is absent, then
the element does not define a link.
The type of link indicated (the relationship) is given by the value of the rel
attribute, which must be present, and must have a value that is a set of
space-separated tokens. The allowed values and their meanings are defined in a
later section. If the rel attribute is absent, or if the value used is not
allowed according to the definitions in this specification, then the element
does not define a link.
Two categories of links can be created using the link element. Links to external
resources are links to resources that are to be used to augment the current
document, and hyperlink links are links to other documents. The link types
section defines whether a particular link type is an external resource or a
hyperlink. One element can create multiple links (of which some might be
external resource links and some might be hyperlinks). User agents should
process the links on a per-link basis, not a per-element basis.
The exact behaviour for links to external resources depends on the exact
relationship, as defined for the relevant link type. Some of the attributes
control whether or not the external resource is to be applied (as defined
below). For external resources that are represented in the DOM (for example,
style sheets), the DOM representation must be made available even if the
resource is not applied. (However, user agents may opt to only fetch such
resources when they are needed, instead of pro-actively downloading all the
external resources that are not applied.)
Interactive user agents should provide users with a means to follow the
hyperlinks created using the link element, somewhere within their user
interface. The exact interface is not defined by this specification, but it
should include the following information (obtained from the element's
attributes, again as defined below), in some form or another (possibly
simplified), for each hyperlink created with each link element in the document:
The relationship between this document and the resource (given by the rel
attribute)
The title of the resource (given by the title attribute).
The URI of the resource (given by the href attribute).
The language of the resource (given by the hreflang attribute).
The optimum media for the resource (given by the media attribute).
User agents may also include other information, such as the type of the resource
(as given by the type attribute).
The media attribute says which media the resource applies to. The value must be
a valid media query. [MQ]
If the link is a hyperlink then the media attribute is purely advisory, and
describes for which media the document in question was designed.
However, if the link is an external resource link, then the media attribute is
prescriptive. The user agent must only apply the external resource to views
while their state match the listed media.
The default, if the media attribute is omitted, is all, meaning that by default
links apply to all media.
The hreflang attribute on the link element has the same semantics as the
hreflang attribute on hyperlink elements.
The type attribute gives the MIME type of the linked resource. It is purely
advisory. The value must be a valid MIME type, optionally with parameters.
[RFC2046]
For external resource links, user agents may use the type given in this
attribute to decide whether or not to consider using the resource at all. If the
UA does not support the given MIME type for the given link relationship, then
the UA may opt not to download and apply the resource.
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.
If the attribute is omitted, then the UA must fetch the resource to determine
its type and thus determine if it supports (and can apply) that external
resource.
If a document contains three style sheet links labelled as follows:
...then a compliant UA that supported only CSS style sheets would fetch the A
and C files, and skip the B file (since text/plain is not the MIME type for CSS
style sheets). For these two files, it would then check the actual types
returned by the UA. For those that are sent as text/css, it would apply the
styles, but for those labelled as text/plain, or any other type, it would not.
The title attribute gives the title of the link. With one exception, it is
purely advisory. The value is text. The exception is for style sheet links,
where the title attribute defines alternative style sheet sets.
The title attribute on link elements differs from the global title attribute of
most other elements in that a link without a title does not inherit the title of
the parent element: it merely has no title.
Some versions of HTTP defined a Link: header, to be processed like a series of
link elements. When processing links, those must be taken into consideration as
well. For the purposes of ordering, links defined by HTTP headers must be
assumed to come before any links in the document, in the order that they were
given in the HTTP entity header. Relative URIs in these headers must be resolved
according to the rules given in HTTP, not relative to base URIs set by the
document (e.g. using a base element or xml:base attributes). [RFC2616] [RFC2068]
The DOM attributes href, rel, media, hreflang, and type each must reflect the
respective content attributes of the same name.
The DOM attribute relList must reflect the rel content attribute.
The DOM attribute disabled only applies to style sheet links. When the link
element defines a style sheet link, then the disabled attribute behaves as
defined for the alternative style sheets DOM. For all other link elements it
always return false and does nothing on setting.
3.7.5. The meta element
Categories
Metadata content.
Contexts in which this element may be used:
If the charset attribute is present: as the first element in a head element.
If the http-equiv attribute is present: in a head element.
If the http-equiv attribute is present: in a noscript element that is a child
of a head element.
If the name attribute is present: where metadata content is expected.
Content model:
Empty.
Element-specific attributes:
name
http-equiv
content
charset (HTML only)
DOM interface:
interface HTMLMetaElement : HTMLElement {
attribute DOMString content;
attribute DOMString name;
attribute DOMString httpEquiv;
};The meta element represents various kinds of metadata that cannot be expressed
using the title, base, link, style, and script elements.
The meta element can represent document-level metadata with the name attribute,
pragma directives with the http-equiv attribute, and the file's character
encoding declaration when an HTML document is serialised to string form (e.g.
for transmission over the network or for disk storage) with the charset
attribute.
Exactly one of the name, http-equiv, and charset attributes must be specified.
If either name or http-equiv is specified, then the content attribute must also
be specified. Otherwise, it must be omitted.
The charset attribute may only be specified in HTML documents, it must not be
used in XML documents. If the charset attribute is specified, the element must
be the first element in the head element of the file.
The content attribute gives the value of the document metadata or pragma
directive when the element is used for those purposes. The allowed values depend
on the exact context, as described in subsequent sections of this specification.
If a meta element has a name attribute, it sets document metadata. Document
metadata is expressed in terms of name/value pairs, the name attribute on the
meta element giving the name, and the content attribute on the same element
giving the value. The name specifies what aspect of metadata is being set; valid
names and the meaning of their values are described in the following sections.
If a meta element has no content attribute, then the value part of the metadata
name/value pair is the empty string.
If a meta element has the http-equiv attribute specified, it must be either in a
head element or in a noscript element that itself is in a head element. If a
meta element does not have the http-equiv attribute specified, it must be in a
head element.
The DOM attributes name and content must reflect the respective content
attributes of the same name. The DOM attribute httpEquiv must reflect the
content attribute http-equiv.
3.7.5.1. Standard metadata names
This specification defines a few names for the name attribute of the meta
element.
generator
The value must be a free-form string that identifies the software used to
generate the document. This value must not be used on hand-authored pages.
WYSIWYG editors have additional constraints on the value used with this
metadata name.
dns
The value must be an ordered set of unique space-separated tokens, each word
of which is a host name. The list allows authors to provide a list of host
names that the user is expected to subsequently need. User agents may,
according to user preferences and prevailing network conditions, pre-emptively
resolve the given DNS names (extracting the names from the value using the
rules for splitting a string on spaces), thus precaching the DNS information
for those hosts and potentially reducing the time between page loads for
subsequent user interactions. Higher priority should be given to host names
given earlier in the list.
3.7.5.2. Other metadata names
Extensions to the predefined set of metadata names may be registered in the
WHATWG Wiki MetaExtensions page.
Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a
type. These new names must be specified with the following information:
Keyword
The actual name being defined. The name should not be confusingly similar to
any other defined name (e.g. differing only in case).
Brief description
A short description of what the metadata name's meaning is, including the
format the value is required to be in.
Link to more details
A link to a more detailed description of the metadata name's semantics and
requirements. It could be another page on the Wiki, or a link to an external
page.
Synonyms
A list of other names that have exactly the same processing requirements.
Authors should not use the names defined to be synonyms, they are only
intended to allow user agents to support legacy content.
Status
One of the following:
Proposal
The name has not received wide peer review and approval. Someone has
proposed it and is using it.
Accepted
The name has received wide peer review and approval. It has a specification
that unambiguously defines how to handle pages that use the name, including
when they use it in incorrect ways.
Unendorsed
The metadata name 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 "link to more details" entries will give
details of what authors should use instead, if anything.
If a metadata name is added with the "proposal" status and found to be
redundant with existing values, it should be removed and listed as a synonym
for the existing value.
Conformance checkers must use the information given on the WHATWG Wiki
MetaExtensions page to establish if a value not explicitly defined in this
specification is allowed or not. 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 "proposal"
status.
This specification does not define how new values will get approved. It is
expected that the Wiki will have a community that addresses this.
Metadata names whose values are to be URIs must not be proposed or accepted.
Links must be represented using the link element, not the meta element.
3.7.5.3. Pragma directives
When the http-equiv attribute is specified on a meta element, the element is a
pragma directive.
The http-equiv attribute is an enumerated attribute. The following table lists
the keywords defined for this attribute. The states given in the first cell of
the the rows with keywords give the states to which those keywords map.
State Keywords
Refresh refresh
Default style default-style
When a meta element is inserted into the document, if its http-equiv attribute
is present and represents one of the above states, then the user agent must run
the algorithm appropriate for that state, as described in the following list:
Refresh state
If another meta element in the Refresh state has already been successfully
processed (i.e. when it was inserted the user agent processed it and reached
the last step of this list of steps), then abort these steps.
If the meta element has no content attribute, or if that attribute's value
is the empty string, then abort these steps.
Let input be the value of the element's content attribute.
Let position point at the first character of input.
Skip whitespace.
Collect a sequence of characters in the range U+0030 DIGIT ZERO to U+0039
DIGIT NINE, and parse the resulting string using the rules for parsing
non-negative integers. If the sequence of characters collected is the empty
string, then no number will have been parsed; abort these steps. Otherwise,
let time be the parsed number.
Collect a sequence of characters in the range U+0030 DIGIT ZERO to U+0039
DIGIT NINE and U+002E FULL STOP ("."). Ignore any collected characters.
Skip whitespace.
Let url be the address of the current page.
If the character in input pointed to by position is a U+003B SEMICOLON
(";"), then advance position to the next character. Otherwise, jump to the
last step.
Skip whitespace.
If the character in input pointed to by position is one of U+0055 LATIN
CAPITAL LETTER U or U+0075 LATIN SMALL LETTER U, then advance position to
the next character. Otherwise, jump to the last step.
If the character in input pointed to by position is one of U+0052 LATIN
CAPITAL LETTER R or U+0072 LATIN SMALL LETTER R, then advance position to
the next character. Otherwise, jump to the last step.
If the character in input pointed to by position is one of U+004C LATIN
CAPITAL LETTER L or U+006C LATIN SMALL LETTER L, then advance position to
the next character. Otherwise, jump to the last step.
Skip whitespace.
If the character in input pointed to by position is a U+003D EQUALS SIGN
("="), then advance position to the next character. Otherwise, jump to the
last step.
Skip whitespace.
Let url be equal to the substring of input from the character at position to
the end of the string.
Strip any trailing space characters from the end of url.
Strip any U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), and U+000D
CARRIAGE RETURN (CR) characters from url.
Resolve the url value to an absolute URI using the base URI of the meta
element.
Set a timer so that in time seconds, if the user has not canceled the
redirect, the user agent navigates to url, with replacement enabled.
For meta elements in the Refresh state, the content attribute must have a
value consisting either of:
just a valid non-negative integer, or
a valid non-negative integer, followed by a U+003B SEMICOLON (;), followed
by one or more space characters, followed by either a U+0055 LATIN CAPITAL
LETTER U or a U+0075 LATIN SMALL LETTER U, a U+0052 LATIN CAPITAL LETTER R
or a U+0072 LATIN SMALL LETTER R, a U+004C LATIN CAPITAL LETTER L or a
U+006C LATIN SMALL LETTER L, a U+003D EQUALS SIGN (=), and then a valid URI
(or IRI).
In the former case, the integer represents a number of seconds before the page
is to be reloaded; in the latter case the integer represents a number of
seconds before the page is to be replaced by the page at the given URI.
Default style state
...
3.7.5.4. Specifying the document's character encoding
The meta element may also be used to provide UAs with character encoding
information for HTML files, by setting the charset attribute to the name of a
character encoding. This is called a character encoding declaration.
The following restrictions apply to character encoding declarations:
The character encoding name given must be the name of the character encoding
used to serialise the file.
The value must be a valid character encoding name, and must be the preferred
name for that encoding. [IANACHARSET]
The attribute value must be serialised without the use of character entity
references of any kind.
If the document does not start with a BOM, and if its encoding is not explicitly
given by Content-Type metadata, then the character encoding used must be a
superset of US-ASCII (specifically, ANSI_X3.4-1968) for bytes in the range 0x09
- 0x0D, 0x20, 0x21, 0x22, 0x26, 0x27, 0x2C - 0x3F, 0x41 - 0x5A, and 0x61 - 0x7A
, and, in addition, if that encoding isn't US-ASCII itself, then the encoding
must be specified using a meta element with a charset attribute.
Authors should not use JIS_X0212-1990, x-JIS0208, and encodings based on EBCDIC.
Authors should not use UTF-32. Authors must not use the CESU-8, UTF-7, BOCU-1
and SCSU encodings. [CESU8] [UTF7] [BOCU1] [SCSU]
Authors are encouraged to use UTF-8. Conformance checkers may advise against
authors using legacy encodings.
In XHTML, the XML declaration should be used for inline character encoding
information, if necessary.
3.7.6. The style element
Categories
Metadata content.
If the scoped attribute is present: prose content.
Contexts in which this element may be used:
If the scoped attribute is absent: where metadata content is expected.
If the scoped attribute is absent: in a noscript element that is a child of a
head element.
If the scoped attribute is present: where prose content is expected, but
before any sibling elements other than style elements and before any text
nodes other than inter-element whitespace.
Content model:
Depends on the value of the type attribute.
Element-specific attributes:
media
type
scoped
Also, the title attribute has special semantics on this element.
DOM interface:
interface HTMLStyleElement : HTMLElement {
attribute boolean disabled;
attribute DOMString media;
attribute DOMString type;
attribute boolean scoped;
};The LinkStyle interface must also be implemented by this element, the styling
processing model defines how. [CSSOM]
The style element allows authors to embed style information in their documents.
The style element is one of several inputs to the styling processing model.
If the type attribute is given, it must contain a valid MIME type, optionally
with parameters, that designates a styling language. [RFC2046] If the attribute
is absent, the type defaults to text/css. [RFC2138]
When examining types to determine if they support the language, user agents must
not ignore unknown MIME parameters — types with unknown parameters must be
assumed to be unsupported.
The media attribute says which media the styles apply to. The value must be a
valid media query. [MQ] User agents must only apply the styles to views while
their state match the listed media. [DOM3VIEWS]
The default, if the media attribute is omitted, is all, meaning that by default
styles apply to all media.
The scoped attribute is a boolean attribute. If the attribute is present, then
the user agent must only apply the specified style information to the style
element's parent element (if any), and that element's child nodes. Otherwise,
the specified styles must, if applied, be applied to the entire document.
If the scoped attribute is not specified, the style element must be the child of
a head element or of a noscript element that is a child of a head element.
If the scoped attribute is specified, then the style element must be the child
of a prose content element, before any text nodes other than inter-element
whitespace, and before any elements other than other style elements.
The title attribute on style elements defines alternative style sheet sets. If
the style element has no title attribute, then it has no title; the title
attribute of ancestors does not apply to the style element.
The title attribute on style elements, like the title attribute on link
elements, differs from the global title attribute in that a style block without
a title does not inherit the title of the parent element: it merely has no
title.
All descendant elements must be processed, according to their semantics, before
the style element itself is evaluated. For styling languages that consist of
pure text, user agents must evaluate style elements by passing the concatenation
of the contents of all the text nodes that are direct children of the style
element (not any other nodes such as comments or elements), in tree order, to
the style system. For XML-based styling languages, user agents must pass all the
children nodes of the style element to the style system.
This specification does not specify a style system, but CSS is expected to be
supported by most Web browsers. [CSS21]
The media, type and scoped DOM attributes must reflect the respective content
attributes of the same name.
The DOM disabled attribute behaves as defined for the alternative style sheets
DOM.
3.7.7. Styling
The link and style elements can provide styling information for the user agent
to use when rendering the document. The DOM Styling specification specifies what
styling information is to be used by the user agent and how it is to be used.
[CSSOM]
The style and link elements implement the LinkStyle interface. [CSSOM]
For style elements, if the user agent does not support the specified styling
language, then the sheet attribute of the element's LinkStyle interface must
return null. Similarly, link elements that do not represent external resource
links that contribute to the styling processing model (i.e. that do not have a
stylesheet keyword in their rel attribute), and link elements whose specified
resource has not yet been downloaded, or is not in a supported styling language,
must have their LinkStyle interface's sheet attribute return null.
Otherwise, the LinkStyle interface's sheet attribute must return a StyleSheet
object with the attributes implemented as follows: [CSSOM]
The content type (type DOM attribute)
The content type must be the same as the style's specified type. For style
elements, this is the same as the type content attribute's value, or text/css
if that is omitted. For link elements, this is the Content-Type metadata of
the specified resource.
The location (href DOM attribute)
For link elements, the location must be the URI given by the element's href
content attribute. For style elements, there is no location.
The intended destination media for style information (media DOM attribute)
The media must be the same as the value of the element's media content
attribute.
The style sheet title (title DOM attribute)
The title must be the same as the value of the element's title content
attribute. If the attribute is absent, then the style sheet does not have a
title. The title is used for defining alternative style sheet sets.
The disabled DOM attribute on link and style elements must return false and do
nothing on setting, if the sheet attribute of their LinkStyle interface is null.
Otherwise, it must return the value of the StyleSheet interface's disabled
attribute on getting, and forward the new value to that same attribute on
setting.
3.8. Sections
Some elements, for example address elements, are scoped to their nearest
ancestor sectioning content. For such elements x, the elements that apply to a
sectioning content element e are all the x elements whose nearest sectioning
content ancestor is e.
3.8.1. The body element
Categories
Sectioning content.
Contexts in which this element may be used:
As the second element in an html element.
Content model:
Prose content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The body element represents the main content of the document.
In conforming documents, there is only one body element. The document.body DOM
attribute provides scripts with easy access to a document's body element.
Some DOM operations (for example, parts of the drag and drop model) are defined
in terms of "the body element". This refers to a particular element in the DOM,
as per the definition of the term, and not any arbitrary body element.
3.8.2. The section element
Categories
Prose content.
Sectioning content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Prose content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The section element represents a generic document or application section. A
section, in this context, is a thematic grouping of content, typically with a
header, possibly with a footer.
Examples of sections would be chapters, the various tabbed pages in a tabbed
dialog box, or the numbered sections of a thesis. A Web site's home page could
be split into sections for an introduction, news items, contact information.
3.8.3. The nav element
Categories
Prose content.
Sectioning content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Prose content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The nav element represents a section of a page that links to other pages or to
parts within the page: a section with navigation links.
3.8.4. The article element
Categories
Prose content.
Sectioning content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Prose content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The article element represents a section of a page that consists of a
composition that forms an independent part of a document, page, or site. This
could be a forum post, a magazine or newspaper article, a Web log entry, a
user-submitted comment, or any other independent item of content.
An article element is "independent" in that its contents could stand alone, for
example in syndication. However, the element is still associated with its
ancestors; for instance, contact information that applies to a parent body
element still covers the article as well.
When article elements are nested, the inner article elements represent articles
that are in principle related to the contents of the outer article. For
instance, a Web log entry on a site that accepts user-submitted comments could
represent the comments as article elements nested within the article element for
the Web log entry.
Author information associated with an article element (q.v. the address element)
does not apply to nested article elements.
3.8.5. The blockquote element
Categories
Prose content.
Sectioning content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Prose content.
Element-specific attributes:
cite
DOM interface:
interface HTMLQuoteElement : HTMLElement {
attribute DOMString cite;
};The HTMLQuoteElement interface is also used by the q element.
The blockquote element represents a section that is quoted from another source.
Content inside a blockquote must be quoted from another source, whose URI, if it
has one, should be cited in the cite attribute.
If the cite attribute is present, it must be a URI (or IRI). User agents should
allow users to follow such citation links.
If a blockquote element is preceded or followed by a paragraph that contains a
single cite element and is itself not preceded or followed by another blockquote
element and does not itself have a q element descendant, then, the citation
given by that cite element gives the source of the quotation contained in the
blockquote element.
The cite DOM attribute reflects the element's cite content attribte.
The best way to represent a conversation is not with the cite and blockquote
elements, but with the dialog element.
3.8.6. The aside element
Categories
Prose content.
Sectioning content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Prose content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The aside element represents a section of a page that consists of content that
is tangentially related to the content around the aside element, and which could
be considered separate from that content. Such sections are often represented as
sidebars in printed typography.
3.8.7. The h1, h2, h3, h4, h5, and h6 elements
Categories
Prose content.
Heading content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
These elements define headers for their sections.
The semantics and meaning of these elements are defined in the section on
headings and sections.
These elements have a rank given by the number in their name. The h1 element is
said to have the highest rank, the h6 element has the lowest rank, and two
elements with the same name have equal rank.
3.8.8. The header element
Categories
Prose content.
Heading content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Prose content, including at least one descendant that is heading content, but
no sectioning content descendants, no header element descendants, and no
footer element descendants.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The header element represents the header of a section. Headers may contain more
than just the section's heading — for example it would be reasonable for the
header to include version history information.
For the purposes of document summaries, outlines, and the like, header elements
are equivalent to the highest ranked h1-h6 element descendant of the header
element (the first such element if there are multiple elements with that rank).
Other heading elements in the header element indicate subheadings or subtitles.
Here are some examples of valid headers. In each case, the emphasised text
represents the text that would be used as the header in an application
extracting header data and ignoring subheadings.
Dave Raggett,
Arnaud Le Hors,
contact persons for the W3C HTML Activity
The address element must not be used to represent arbitrary addresses (e.g.
postal addresses), unless those addresses are contact information for the
section. (The p element is the appropriate element for marking up such
addresses.)
The address element must not contain information other than contact information.
For example, the following is non-conforming use of the address element:
Last Modified: 1999/12/24 23:37:50Typically, the address element would be included with other information in a
footer element.
To determine the contact information for a sectioning element (such as a
document's body element, which would give the contact information for the page),
UAs must collect all the address elements that apply to that sectioning element
and its ancestor sectioning elements. The contact information is the collection
of all the information given by those elements.
Contact information for one sectioning element, e.g. an aside element, does not
apply to its ancestor elements, e.g. the page's body.
3.8.11. Headings and sections
The h1-h6 elements and the header element are headings.
The first element of heading content in an element of sectioning content gives
the header for that section. Subsequent headers of equal or higher rank start
new (implied) sections, headers of lower rank start subsections that are part of
the previous one.
Sectioning elements other than blockquote are always considered subsections of
their nearest ancestor element of sectioning content, regardless of what implied
sections other headings may have created. However, blockquote elements are
associated with implied sections. Effectively, blockquote elements act like
sections on the inside, and act opaquely on the outside.
For the following fragment:
Foo
Bar
Bla
Baz
Quux
Thud
Grunt
...the structure would be:
Foo (heading of explicit body section)
Bar (heading starting implied section)
Bla (heading of explicit blockquote section)
Baz (paragraph)
Quux (heading starting implied section)
Thud (heading of explicit section section)
Grunt (paragraph)
Notice how the blockquote nests inside an implicit section while the section
does not (and in fact, ends the earlier implicit section so that a later
paragraph is back at the top level).
Sections may contain headers of any rank, but authors are strongly encouraged to
either use only h1 elements, or to use elements of the appropriate rank for the
section's nesting level.
Authors are also encouraged to explictly wrap sections in elements of sectioning
content, instead of relying on the implicit sections generated by having
multiple heading in one element of sectioning content.
For example, the following is correct:
Apples
Apples are fruit.
Taste
They taste lovely.
Sweet
Red apples are sweeter than green ones.
Color
Apples come in various colors.
However, the same document would be more clearly expressed as:
Apples
Apples are fruit.
Taste
They taste lovely.
Sweet
Red apples are sweeter than green ones.
Color
Apples come in various colors.
Both of the documents above are semantically identical and would produce the
same outline in compliant user agents.
3.8.11.1. Creating an outline
This section will be rewritten at some point. The algorithm likely won't change,
but its description will be dramatically simplified.
Documents can be viewed as a tree of sections, which defines how each element in
the tree is semantically related to the others, in terms of the overall section
structure. This tree is related to the document tree, but there is not a
one-to-one relationship between elements in the DOM and the document's sections.
The tree of sections should be used when generating document outlines, for
example when generating tables of contents.
To derive the tree of sections from the document tree, a hypothetical tree is
used, consisting of a view of the document tree containing only the elements of
heading content and the elements of sectioning content other than blockquote.
Descendants of h1-h6, header, and blockquote elements must be removed from this
view.
The hypothetical tree must be rooted at the root element or at an element of
sectioning content. In particular, while the sections inside blockquotes do not
contribute to the document's tree of sections, blockquotes can have outlines of
their own.
UAs must take this hypothetical tree (which will become the outline) and mutate
it by walking it depth first in tree order and, for each element of heading
content that is not the first element of its parent sectioning content element,
inserting a new element of sectioning content, as follows:
If the element is a header element, or if it is an h1-h6 node of rank equal to
or higher than the first element in the parent element of sectioning content
(assuming that is also an h1-h6 node), or if the first element of the parent
element of sectioning content is an element of sectioning content:
Insert the new element of sectioning content as the immediately following
sibling of the parent element of sectioning content, and move all the elements
from the current element of heading content up to the end of the parent
element of sectioning content into the new element of sectioning content.
Otherwise:
Move the current heading element, and all subsequent siblings up to but
excluding the next element of sectioning content, header element, or h1-h6 of
equal or higher rank, whichever comes first, into the new element of
sectioning content, then insert the new element of sectioning content where
the current header was.
The outline is then the resulting hypothetical tree. The ranks of the headers
become irrelevant at this point: each element of sectioning content in the
hypothetical tree contains either no or one heading element child. If there is
one, then it gives the section's heading, of there isn't, the section has no
heading.
Sections are nested as in the hypothetical tree. If a sectioning element is a
child of another, that means it is a subsection of that other section.
When creating an interactive table of contents, entries should jump the user to
the relevant section element, if it was a real element in the original document,
or to the heading, if the section element was one of those created during the
above process.
Selecting the first section of the document therefore always takes the user to
the top of the document, regardless of where the first header in the body is to
be found.
The hypothetical tree (before mutations) could be generated by creating a
TreeWalker with the following NodeFilter (described here as an anonymous
ECMAScript function). [DOMTR] [ECMA262]
function (n) {
// This implementation only knows about HTML elements.
// An implementation that supports other languages might be
// different.
// Reject anything that isn't an element.
if (n.nodeType != Node.ELEMENT_NODE)
return NodeFilter.FILTER_REJECT;
// Skip any descendants of headings.
if ((n.parentNode && n.parentNode.namespaceURI == 'http://www.w3.org/1999/xhtml') &&
(n.parentNode.localName == 'h1' || n.parentNode.localName == 'h2' ||
n.parentNode.localName == 'h3' || n.parentNode.localName == 'h4' ||
n.parentNode.localName == 'h5' || n.parentNode.localName == 'h6' ||
n.parentNode.localName == 'header'))
return NodeFilter.FILTER_REJECT;
// Skip any blockquotes.
if ((n.namespaceURI == 'http://www.w3.org/1999/xhtml') &&
(n.localName == 'blockquote'))
return NodeFilter.FILTER_REJECT;
// Accept HTML elements in the list given in the prose above.
if ((n.namespaceURI == 'http://www.w3.org/1999/xhtml') &&
(n.localName == 'body' || /*n.localName == 'blockquote' ||*/
n.localName == 'section' || n.localName == 'nav' ||
n.localName == 'article' || n.localName == 'aside' ||
n.localName == 'h1' || n.localName == 'h2' ||
n.localName == 'h3' || n.localName == 'h4' ||
n.localName == 'h5' || n.localName == 'h6' ||
n.localName == 'header'))
return NodeFilter.FILTER_ACCEPT;
// Skip the rest.
return NodeFilter.FILTER_SKIP;
}3.8.11.2. Determining which heading and section applies to a particular node
This section will be rewritten at some point. The algorithm likely won't change,
but its description will be dramatically simplified.
Given a particular node, user agents must use the following algorithm, in the
given order, to determine which heading and section the node is most closely
associated with. The processing of this algorithm must stop as soon as the
associated section and heading are established (even if they are established to
be nothing).
If the node has an ancestor that is a header element, then the associated
heading is the most distant such ancestor. The associated section is that
header's associated section (i.e. repeat this algorithm for that header).
If the node has an ancestor that is an h1-h6 element, then the associated
heading is the most distant such ancestor. The associated section is that
heading's section (i.e. repeat this algorithm for that heading element).
If the node is an h1-h6 element or a header element, then the associated
heading is the element itself. The UA must then generate the hypothetical
section tree described in the previous section, rooted at the nearest section
ancestor (or the root element if there is no such ancestor). If the parent of
the heading in that hypothetical tree is an element in the real document tree,
then that element is the associated section. Otherwise, there is no associated
section element.
If the node is an element of sectioning content, then the associated section
is itself. The UA must then generate the hypothetical section tree described
in the previous section, rooted at the section itself. If the section element,
in that hypothetical tree, has a child element that is an h1-h6 element or a
header element, then that element is the associated heading. Otherwise, there
is no associated heading element.
If the node is a footer or address element, then the associated section is the
nearest ancestor element of sectioning content, if there is one. The node's
associated heading is the same as that element of sectioning content's
associated heading (i.e. repeat this algorithm for that element of sectioning
content). If there is no ancestor element of sectioning content, the element
has no associated section nor an associated heading.
Otherwise, the node is just a normal node, and the document has to be examined
more closely to determine its section and heading. Create a view rooted at the
nearest ancestor element of sectioning content (or the root element if there
is none) that has just h1-h6 elements, header elements, the node itself, and
elements of sectioning content other than blockquote elements. (Descendants of
any of the nodes in this view can be ignored, as can any node later in the
tree than the node in question, as the algorithm below merely walks backwards
up this view.)
Let n be an iterator for this view, initialised at the node in question.
Let c be the current best candidate heading, initially null, and initially not
used. It is used when top-level heading candidates are to be searched for (see
below).
Repeat these steps (which effectively goes backwards through the node's
previous siblings) until an answer is found:
If n points to a node with no previous sibling, and c is null, then return
the node's parent node as the answer. If the node has no parent node, return
null as the answer.
Otherwise, if n points to a node with no previous sibling, return c as the
answer.
Adjust n so that it points to the previous sibling of the current position.
If n is pointing at an h1 or header element, then return that element as the
answer.
If n is pointing at an h2-h6 element, and heading candidates are not being
searched for, then return that element as the answer.
Otherwise, if n is pointing at an h2-h6 element, and either c is still null,
or c is a heading of lower rank than this one, then set c to be this
element, and continue going backwards through the previous siblings.
If n is pointing at an element of sectioning content, then from this point
on top-level heading candidates are being searched for. (Specifically, we
are looking for the nearest top-level header for the current section.)
Continue going backwards through the previous siblings.
If the answer from the previous step (the loop) is null, which can only happen
if the node has no preceeding headings and is not contained in an element of
sectioning content, then there is no associated heading and no associated
section.
Otherwise, if the answer from the earlier loop step is an element of
sectioning content, then the associated section is that element and the
associated heading is that element of sectioning content's associated heading
(i.e. repeat this algorithm for that section).
Otherwise, if the answer from that same earlier step is an h1-h6 element or a
header element, then the associated heading is that element and the associated
section is that heading element's associated section (i.e. repeat this
algorithm for that heading).
Not all nodes have an associated header or section. For example, if a section is
implied, as when multiple headers are found in one element of sectioning
content, then a node in that section has an anonymous associated section (its
section is not represented by a real element), and the algorithm above does not
associate that node with any particular element of sectioning content.
For the following fragment:
X
X
X
X
Text Node A
X
Text Node B
The associations are as follows (not all associations are shown):
Node Associated heading Associated section
None.
None.
None.
Text Node A
None.
Text Node B
3.8.11.3. Distinguishing site-wide headers from page headers
Given the hypothetical section tree, but ignoring any sections created for nav
and aside elements, and any of their descendants, if the root of the tree is the
body element's section, and it has only a single subsection which is created by
an article element, then the header of the body element should be assumed to be
a site-wide header, and the header of the article element should be assumed to
be the page's header.
If a page starts with a heading that is common to the whole site, the document
must be authored such that, in the document's hypothetical section tree,
ignoring any sections created for nav and aside elements and any of their
descendants, the root of the tree is the body element's section, its heading is
the site-wide heading, the body element has just one subsection, that subsection
is created by an article element, and that article's header is the page heading.
If a page does not contain a site-wide heading, then the page must be authored
such that, in the document's hypothetical section tree, ignoring any sections
created for nav and aside elements and any of their descendants, either the body
element has no subsections, or it has more than one subsection, or it has a
single subsection but that subsection is not created by an article element.
Conceptually, a site is thus a document with many articles — when those articles
are split into many pages, the heading of the original single page becomes the
heading of the site, repeated on every page.
3.9. Prose
3.9.1. The p element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The p element represents a paragraph.
The following examples are conforming HTML fragments:
The little kitten gently seated himself on a piece of
carpet. Later in his life, this would be referred to as the time the
cat sat on the mat.
There was once an example from Femley,
Whose markup was of dubious quality.
The validator complained,
So the author was pained,
To move the error from the markup to the rhyming.
The p element should not be used when a more specific element is more
appropriate.
The following example is technically correct:
Last modified: 2001-04-23
Author: fred@example.com
However, it would be better marked-up as:
Author: fred@example.com
Or:
3.9.2. The hr element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Empty.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The hr element represents a paragraph-level thematic break, e.g. a scene change
in a story, or a transition to another topic within a section of a reference
book.
3.9.3. The br element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Empty.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The br element represents a line break.
br elements must be empty. Any content inside br elements must not be considered
part of the surrounding text.
br elements must only be used for line breaks that are actually part of the
content, as in poems or addresses.
The following example is correct usage of the br element:
P. Sherman
42 Wallaby Way
Sydney
br elements must not be used for separating thematic groups in a paragraph.
The following examples are non-conforming, as they abuse the br element:
If a paragraph consists of nothing but a single br element, it represents a
placeholder blank line (e.g. as in a template). Such blank lines must not be
used for presentation purposes.
3.9.4. The dialog element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Zero or more pairs of dt and dd elements.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The dialog element represents a conversation.
Each part of the conversation must have an explicit talker (or speaker) given by
a dt element, and a discourse (or quote) given by a dd element.
This example demonstrates this using an extract from Abbot and Costello's famous
sketch, Who's on first:
Text in a dt element in a dialog element is implicitly the source of the text
given in the following dd element, and the contents of the dd element are
implicitly a quote from that speaker. There is thus no need to include cite, q,
or blockquote elements in this markup. Indeed, a q element inside a dd element
in a conversation would actually imply the people talking were themselves
quoting someone else. See the cite, q, and blockquote elements for other ways to
cite or quote.
3.10. Preformatted text
3.10.1. The pre element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The pre element represents a block of preformatted text, in which structure is
represented by typographic conventions rather than by elements.
Some examples of cases where the pre element could be used:
Including an e-mail, with paragraphs indicated by blank lines, lists indicated
by lines prefixed with a bullet, and so on.
Including fragments of computer code, with structure indicated according to
the conventions of that language.
Displaying ASCII art.
To represent a block of computer code, the pre element can be used with a code
element; to represent a block of computer output the pre element can be used
with a samp element. Similarly, the kbd element can be used within a pre element
to indicate text that the user is to enter.
In the following snippet, a sample of computer code is presented.
This is the Panel constructor:
function Panel(element, canClose, closeHandler) {
this.element = element;
this.canClose = canClose;
this.closeHandler = function () { if (closeHandler) closeHandler() };
}
In the following snippet, samp and kbd elements are mixed in the contents of a
pre element to show a session of Zork I.
You are in an open field west of a big white house with a boarded
front door.
There is a small mailbox here.
>open mailboxOpening the mailbox reveals:
A leaflet.
>
The following shows a contemporary poem that uses the pre element to preserve
its unusual formatting, which forms an intrinsic part of the poem itself.
maxling
it is with a heart
heavy
that i admit loss of a feline
so loved
a friend lost to the
unknown
(night)
~cdr 11dec07
3.11. Lists
3.11.1. The ol element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Zero or more li elements.
Element-specific attributes:
start
DOM interface:
interface HTMLOListElement : HTMLElement {
attribute long start;
};The ol element represents an ordered list of items (which are represented by li
elements).
The start attribute, if present, must be a valid integer giving the ordinal
value of the first list item.
If the start attribute is present, user agents must parse it as an integer, in
order to determine the attribute's value. The default value, used if the
attribute is missing or if the value cannot be converted to a number according
to the referenced algorithm, is 1.
The items of the list are the li element child nodes of the ol element, in tree
order.
The first item in the list has the ordinal value given by the ol element's start
attribute, unless that li element has a value attribute with a value that can be
successfully parsed, in which case it has the ordinal value given by that value
attribute.
Each subsequent item in the list has the ordinal value given by its value
attribute, if it has one, or, if it doesn't, the ordinal value of the previous
item, plus one.
The start DOM attribute must reflect the value of the start content attribute.
3.11.2. The ul element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Zero or more li elements.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The ul element represents an unordered list of items (which are represented by
li elements).
The items of the list are the li element child nodes of the ul element.
3.11.3. The li element
Categories
None.
Contexts in which this element may be used:
Inside ol elements.
Inside ul elements.
Inside menu elements.
Content model:
When the element is a child of a menu element: phrasing content.
Otherwise: prose content.
Element-specific attributes:
If the element is a child of an ol element: value
If the element is not the child of an ol element: None.
DOM interface:
interface HTMLLIElement : HTMLElement {
attribute long value;
};The li element represents a list item. If its parent element is an ol, ul, or
menu element, then the element is an item of the parent element's list, as
defined for those elements. Otherwise, the list item has no defined list-related
relationship to any other li element.
The value attribute, if present, must be a valid integer giving the ordinal
value of the first list item.
If the value attribute is present, user agents must parse it as an integer, in
order to determine the attribute's value. If the attribute's value cannot be
converted to a number, the attribute must be treated as if it was absent. The
attribute has no default value.
The value attribute is processed relative to the element's parent ol element
(q.v.), if there is one. If there is not, the attribute has no effect.
The value DOM attribute must reflect the value of the value content attribute.
3.11.4. The dl element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Zero or more groups each consisting of one or more dt elements followed by one
or mode dd elements.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The dl element introduces an unordered association list consisting of zero or
more name-value groups (a description list). Each group must consist of one or
more names (dt elements) followed by one or more values (dd elements).
Name-value groups may be terms and definitions, metadata topics and values, or
any other groups of name-value data.
The following are all conforming HTML fragments.
In the following example, one entry ("Authors") is linked to two values ("John"
and "Luke").
Authors
John
Luke
Editor
Frank
In the following example, one definition is linked to two terms.
color
colour
A sensation which (in humans) derives from the ability of
the fine structure of the eye to distinguish three differently
filtered analyses of a view.
The following example illustrates the use of the dl element to mark up metadata
of sorts. At the end of the example, one group has two metadata labels
("Authors" and "Editors") and two values ("Robert Rothman" and "Daniel
Jackson").
Last modified time
2004-12-23T23:33Z
Recommended update interval
60s
Authors
Editors
Robert Rothman
Daniel Jackson
If a dl element is empty, it contains no groups.
If a dl element contains non-whitespace text nodes, or elements other than dt
and dd, then those elements or text nodes do not form part of any groups in that
dl, and the document is non-conforming.
If a dl element contains only dt elements, then it consists of one group with
names but no values, and the document is non-conforming.
If a dl element contains only dd elements, then it consists of one group with
values but no names, and the document is non-conforming.
The dl element is inappropriate for marking up dialogue, since dialogue is
ordered (each speaker/line pair comes after the next). For an example of how to
mark up dialogue, see the dialog element.
3.11.5. The dt element
Categories
None.
Contexts in which this element may be used:
Before dd or dt elements inside dl elements.
Before a dd element inside a dialog element.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The dt element represents the term, or name, part of a term-description group in
a description list (dl element), and the talker, or speaker, part of a
talker-discourse pair in a conversation (dialog element).
The dt element itself, when used in a dl element, does not indicate that its
contents are a term being defined, but this can be indicated using the dfn
element.
3.11.6. The dd element
Categories
None.
Contexts in which this element may be used:
After dt or dd elements inside dl elements.
After a dt element inside a dialog element.
Content model:
Prose content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The dd element represents the description, definition, or value, part of a
term-description group in a description list (dl element), and the discourse, or
quote, part in a conversation (dialog element).
3.12. Phrase elements
3.12.1. The a element
Categories
Phrasing content.
Interactive content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content, but there must be no interactive content descendant.
Element-specific attributes:
href
target
ping
rel
media
hreflang
type
DOM interface:
interface HTMLAnchorElement : HTMLElement {
attribute DOMString href;
attribute DOMString target;
attribute DOMString ping;
attribute DOMString rel;
readonly attribute DOMTokenList relList;
attribute DOMString media;
attribute DOMString hreflang;
attribute DOMString type;
};The Command interface must also be implemented by this element.
If the a element has an href attribute, then it represents a hyperlink.
If the a element has no href attribute, then the element is a placeholder for
where a link might otherwise have been placed, if it had been relevant.
The target, ping, rel, media, hreflang, and type attributes must be omitted if
the href attribute is not present.
If a site uses a consistent navigation toolbar on every page, then the link that
would normally link to the page itself could be marked up using an a element:
Interactive user agents should allow users to follow hyperlinks created using
the a element. The href, target and ping attributes decide how the link is
followed. The rel, media, hreflang, and type attributes may be used to indicate
to the user the likely nature of the target resource before the user follows the
link.
The activation behavior of a elements that represent hyperlinks is to run the
following steps:
If the DOMActivate event in question is not trusted (i.e. a click() method
call was the reason for the event being dispatched), and the a element's
target attribute is ... then raise an INVALID_ACCESS_ERR exception and abort
these steps.
If the target of the DOMActivate event is an img element with an ismap
attribute specified, then server-side image map processing must be performed,
as follows:
If the DOMActivate event was dispatched as the result of a real
pointing-device-triggered click event on the img element, then let x be the
distance in CSS pixels from the left edge of the image to the location of
the click, and let y be the distance in CSS pixels from the top edge of the
image to the location of the click. Otherwise, let x and y be zero.
Let the hyperlink suffix be a U+003F QUESTION MARK character, the value of x
expressed as a base-ten integer using ASCII digits (U+0030 DIGIT ZERO to
U+0039 DIGIT NINE), a U+002C COMMA character, and the value of y expressed
as a base-ten integer using ASCII digits.
Finally, the user agent must follow the hyperlink defined by the a element. If
the steps above defined a hyperlink suffix, then take that into account when
following the hyperlink.
One way that a user agent can enable users to follow hyperlinks is by allowing a
elements to be clicked, or focussed and activated by the keyboard. This will
cause the aforementioned activation behavior to be invoked.
The DOM attributes href, ping, target, rel, media, hreflang, and type, must each
reflect the respective content attributes of the same name.
The DOM attribute relList must reflect the rel content attribute.
3.12.2. The q element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
cite
DOM interface:
The q element uses the HTMLQuoteElement interface.
The q element represents a part of a paragraph quoted from another source.
Content inside a q element must be quoted from another source, whose URI, if it
has one, should be cited in the cite attribute.
If the cite attribute is present, it must be a URI (or IRI). User agents should
allow users to follow such citation links.
If a q element is contained (directly or indirectly) in a paragraph that
contains a single cite element and has no other q element descendants, then, the
citation given by that cite element gives the source of the quotation contained
in the q element.
3.12.3. The cite element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The cite element represents a citation: the source, or reference, for a quote or
statement made in the document.
A citation is not a quote (for which the q element is appropriate).
This is incorrect usage:
This is wrong!, said Ian.
This is the correct way to do it:
This is correct!, said Ian.
This is also wrong, because the title and the name are not references or
citations:
My favourite book is The Reality Dysfunction
by Peter F. Hamilton.
This is correct, because even though the source is not quoted, it is cited:
According to the Wikipedia article on
HTML, HTML is defined in formal specifications that were
developed and published throughout the 1990s.
The cite element can apply to blockquote and q elements in certain cases
described in the definitions of those elements.
3.12.4. The em element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The em element represents stress emphasis of its contents.
The level of emphasis that a particlar piece of content has is given by its
number of ancestor em elements.
The placement of emphasis changes the meaning of the sentence. The element thus
forms an integral part of the content. The precise way in which emphasis is used
in this way depends on the language.
These examples show how changing the emphasis changes the meaning. First, a
general statement of fact, with no emphasis:
Cats are cute animals.
By emphasising the first word, the statement implies that the kind of animal
under discussion is in question (maybe someone is asserting that dogs are cute):
Cats are cute animals.
Moving the emphasis to the verb, one highlights that the truth of the entire
sentence is in question (maybe someone is saying cats are not cute):
Cats are cute animals.
By moving it to the adjective, the exact nature of the cats is reasserted (maybe
someone suggested cats were mean animals):
Cats are cute animals.
Similarly, if someone asserted that cats were vegetables, someone correcting
this might emphasise the last word:
Cats are cute animals.
By emphasising the entire sentence, it becomes clear that the speaker is
fighting hard to get the point across. This kind of emphasis also typically
affects the punctuation, hence the exclamation mark here.
Cats are cute animals!
Anger mixed with emphasising the cuteness could lead to markup such as:
Cats are cute animals!
3.12.5. The strong element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The strong element represents strong importance for its contents.
The relative level of importance of a piece of content is given by its number of
ancestor strong elements; each strong element increases the importance of its
contents.
Changing the importance of a piece of text with the strong element does not
change the meaning of the sentence.
Here is an example of a warning notice in a game, with the various parts marked
up according to how important they are:
Warning. This dungeon is dangerous.
Avoid the ducks. Take any gold you find.
Do not take any of the diamonds,
they are explosive and will destroy anything within
ten meters. You have been warned.
3.12.6. The small element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The small element represents small print (part of a document often describing
legal restrictions, such as copyrights or other disadvantages), or other side
comments.
The small element does not "de-emphasise" or lower the importance of text
emphasised by the em element or marked as important with the strong element.
In this example the footer contains contact information and a copyright.
In this second example, the small element is used for a side comment.
Example Corp today announced record profits for the
second quarter (Full Disclosure: Foo News is a subsidiary of
Example Corp), leading to speculation about a third quarter
merger with Demo Group.
In this last example, the small element is marked as being important small
print.
Continued use of this service will result in a kiss.
3.12.7. The m element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
This section has a large number of outstanding comments and will likely be
rewritten or removed from the spec.
The m element represents a run of text marked or highlighted.
In the following snippet, a paragraph of text refers to a specific part of a
code fragment.
The highlighted part below is where the error lies:
var i: Integer;
begin
i := 1.1;
end.
Another example of the m element is highlighting parts of a document that are
matching some search string. If someone looked at a document, and the server
knew that the user was searching for the word "kitten", then the server might
return the document with one paragraph modified as follows:
I also have some kittens who are visiting me
these days. They're really cute. I think they like my garden!
3.12.8. The dfn element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content, but there must be no descendant dfn elements.
Element-specific attributes:
None, but the title attribute has special semantics on this element.
DOM interface:
No difference from HTMLElement.
The dfn element represents the defining instance of a term. The paragraph,
description list group, or section that contains the dfn element contains the
definition for the term given by the contents of the dfn element.
Defining term: If the dfn element has a title attribute, then the exact value of
that attribute is the term being defined. Otherwise, if it contains exactly one
element child node and no child text nodes, and that child element is an abbr
element with a title attribute, then the exact value of that attribute is the
term being defined. Otherwise, it is the exact textContent of the dfn element
that gives the term being defined.
If the title attribute of the dfn element is present, then it must only contain
the term being defined.
There must only be one dfn element per document for each term defined (i.e.
there must not be any duplicate terms).
The title attribute of ancestor elements does not affect dfn elements.
The dfn element enables automatic cross-references. Specifically, any span,
abbr, code, var, samp, or i element that has a non-empty title attribute whose
value exactly equals the term of a dfn element in the same document, or which
has no title attribute but whose textContent exactly equals the term of a dfn
element in the document, and that has no interactive elements or dfn elements
either as ancestors or descendants, and has no other elements as ancestors that
are themselves matching these conditions, should be presented in such a way that
the user can jump from the element to the first dfn element giving the defining
instance of that term.
In the following fragment, the term "GDO" is first defined in the first
paragraph, then used in the second. A compliant UA could provide a link from the
abbr element in the second paragraph to the dfn element in the first.
The GDO
is a device that allows off-world teams to open the iris.
Teal'c activated his GDO
and so Hammond ordered the iris to be opened.
3.12.9. The abbr element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None, but the title attribute has special semantics on this element.
DOM interface:
No difference from HTMLElement.
The abbr element represents an abbreviation or acronym. The title attribute
should be used to provide an expansion of the abbreviation. If present, the
attribute must only contain an expansion of the abbreviation.
The paragraph below contains an abbreviation marked up with the abbr element.
The WHATWG is a loose unofficial collaboration of
Web browser manufacturers and interested parties who wish to develop
new technologies designed to allow authors to write and deploy
Applications over the World Wide Web.
The title attribute may be omitted if there is a dfn element in the document
whose defining term is the abbreviation (the textContent of the abbr element).
In the example below, the word "Zat" is used as an abbreviation in the second
paragraph. The abbreviation is defined in the first, so the explanatory title
attribute has been omitted. Because of the way dfn elements are defined, the
second abbr element in this example would be connected (in some UA-specific way)
to the first.
The Zat, short for Zat'ni'catel, is a weapon.
Jack used a Zat to make the boxes of evidence disappear.
3.12.10. The time element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
datetime
DOM interface:
interface HTMLTimeElement : HTMLElement {
attribute DOMString dateTime;
readonly attribute DOMTimeStamp date;
readonly attribute DOMTimeStamp time;
readonly attribute DOMTimeStamp timezone;
};The time element represents a date and/or a time.
The datetime attribute, if present, must contain a date or time string that
identifies the date or time being specified.
If the datetime attribute is not present, then the date or time must be
specified in the content of the element, such that parsing the element's
textContent according to the rules for parsing date or time strings in content
successfully extracts a date or time.
The dateTime DOM attribute must reflect the datetime content attribute.
User agents, to obtain the date, time, and timezone represented by a time
element, must follow these steps:
If the datetime attribute is present, then parse it according to the rules for
parsing date or time strings in attributes, and let the result be result.
Otherwise, parse the element's textContent according to the rules for parsing
date or time strings in content, and let the result be result.
If result is empty (because the parsing failed), then the date is unknown, the
time is unknown, and the timezone is unknown.
Otherwise: if result contains a date, then that is the date; if result
contains a time, then that is the time; and if result contains a timezone,
then the timezone is the element's timezone. (A timezone can only be present
if both a date and a time are also present.)
The date DOM attribute must return null if the date is unknown, and otherwise
must return the time corresponding to midnight UTC (i.e. the first second) of
the given date.
The time DOM attribute must return null if the time is unknown, and otherwise
must return the time corresponding to the given time of 1970-01-01, with the
timezone UTC.
The timezone DOM attribute must return null if the timezone is unknown, and
otherwise must return the time corresponding to 1970-01-01 00:00 UTC in the
given timezone, with the timezone set to UTC (i.e. the time corresponding to
1970-01-01 at 00:00 UTC plus the offset corresponding to the timezone).
In the following snippet:
Our first date was .
...the time element's date attribute would have the value 1,158,969,600,000ms,
and the time and timezone attributes would return null.
In the following snippet:
We stopped talking at .
...the time element's date attribute would have the value 1,159,056,000,000ms,
the time attribute would have the value 18,000,000ms, and the timezone attribute
would return -25,200,000ms. To obtain the actual time, the three attributes can
be added together, obtaining 1,159,048,800,000, which is the specified date and
time in UTC.
Finally, in the following snippet:
Many people get up at .
...the time element's date attribute would have the value null, the time
attribute would have the value 28,800,000ms, and the timezone attribute would
return null.
These APIs may be suboptimal. Comments on making them more useful to JS authors
are welcome. The primary use cases for these elements are for marking up
publication dates e.g. in blog entries, and for marking event dates in hCalendar
markup. Thus the DOM APIs are likely to be used as ways to generate interactive
calendar widgets or some such.
3.12.11. The progress element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
value
max
DOM interface:
interface HTMLProgressElement : HTMLElement {
attribute float value;
attribute float max;
readonly attribute float position;
};The progress element represents the completion progress of a task. The progress
is either indeterminate, indicating that progress is being made but that it is
not clear how much more work remains to be done before the task is complete
(e.g. because the task is waiting for a remote host to respond), or the progress
is a number in the range zero to a maximum, giving the fraction of work that has
so far been completed.
There are two attributes that determine the current task completion represented
by the element.
The value attribute specifies how much of the task has been completed, and the
max attribute specifies how much work the task requires in total. The units are
arbitrary and not specified.
Instead of using the attributes, authors are recommended to simply include the
current value and the maximum value inline as text inside the element.
Here is a snippet of a Web application that shows the progress of some automated
task:
Task Progress
(The updateProgress() method in this example would be called by some other code
on the page to update the actual progress bar as the task progressed.)
Author requirements: The max and value attributes, when present, must have
values that are valid floating point numbers. The max attribute, if present,
must have a value greater than zero. The value attribute, if present, must have
a value equal to or greater than zero, and less than or equal to the value of
the max attribute, if present.
User agent requirements: User agents must parse the max and value attributes'
values according to the rules for parsing floating point number values.
If the value attribute is omitted, then user agents must also parse the
textContent of the progress element in question using the steps for finding one
or two numbers of a ratio in a string. These steps will return nothing, one
number, one number with a denominator punctuation character, or two numbers.
Using the results of this processing, user agents must determine whether the
progress bar is an indeterminate progress bar, or whether it is a determinate
progress bar, and in the latter case, what its current and maximum values are,
all as follows:
If the max attribute is omitted, and the value is omitted, and the results of
parsing the textContent was nothing, then the progress bar is an indeterminate
progress bar. Abort these steps.
Otherwise, it is a determinate progress bar.
If the max attribute is included, then, if a value could be parsed out of it,
then the maximum value is that value.
Otherwise, if the max attribute is absent but the value attribute is present,
or, if the max attribute is present but no value could be parsed from it, then
the maximum is 1.
Otherwise, if neither attribute is included, then, if the textContent
contained one number with an associated denominator punctuation character,
then the maximum value is the value associated with that denominator
punctuation character; otherwise, if the textContent contained two numbers,
the maximum value is the higher of the two values; otherwise, the maximum
value is 1.
If the value attribute is present on the element and a value could be parsed
out of it, that value is the current value of the progress bar. Otherwise, if
the attribute is present but no value could be parsed from it, the current
value is zero.
Otherwise if the value attribute is absent and the max attribute is present,
then, if the textContent was parsed and found to contain just one number, with
no associated denominator punctuation character, then the current value is
that number. Otherwise, if the value attribute is absent and the max attribute
is present then the current value is zero.
Otherwise, if neither attribute is present, then the current value is the
lower of the one or two numbers that were found in the textContent of the
element.
If the maximum value is less than or equal to zero, then it is reset to 1.
If the current value is less than zero, then it is reset to zero.
Finally, if the current value is greater than the maximum value, then the
current value is reset to the maximum value.
UA requirements for showing the progress bar: When representing a progress
element to the user, the UA should indicate whether it is a determinate or
indeterminate progress bar, and in the former case, should indicate the relative
position of the current value relative to the maximum value.
The max and value DOM attributes must reflect the elements' content attributes
of the same name. When the relevant content attributes are absent, the DOM
attributes must return zero. The value parsed from the textContent never affects
the DOM values.
Would be cool to have the value DOM attribute update the textContent in-line...
If the progress bar is an indeterminate progress bar, then the position DOM
attribute must return -1. Otherwise, it must return the result of dividing the
current value by the maximum value.
3.12.12. The meter element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
value
min
low
high
max
optimum
DOM interface:
interface HTMLMeterElement : HTMLElement {
attribute long value;
attribute long min;
attribute long max;
attribute long low;
attribute long high;
attribute long optimum;
};The meter element represents a scalar measurement within a known range, or a
fractional value; for example disk usage, the relevance of a query result, or
the fraction of a voting population to have selected a particular candidate.
This is also known as a gauge.
The meter element should not be used to indicate progress (as in a progress
bar). For that role, HTML provides a separate progress element.
The meter element also does not represent a scalar value of arbitrary range —
for example, it would be wrong to use this to report a weight, or height, unless
there is a known maximum value.
There are six attributes that determine the semantics of the gauge represented
by the element.
The min attribute specifies the lower bound of the range, and the max attribute
specifies the upper bound. The value attribute specifies the value to have the
gauge indicate as the "measured" value.
The other three attributes can be used to segment the gauge's range into "low",
"medium", and "high" parts, and to indicate which part of the gauge is the
"optimum" part. The low attribute specifies the range that is considered to be
the "low" part, and the high attribute specifies the range that is considered to
be the "high" part. The optimum attribute gives the position that is "optimum";
if that is higher than the "high" value then this indicates that the higher the
value, the better; if it's lower than the "low" mark then it indicates that
lower values are better, and naturally if it is in between then it indicates
that neither high nor low values are good.
Authoring requirements: The recommended way of giving the value is to include it
as contents of the element, either as two numbers (the higher number represents
the maximum, the other number the current value), or as a percentage or similar
(using one of the characters such as "%"), or as a fraction.
The value, min, low, high, max, and optimum attributes are all optional. When
present, they must have values that are valid floating point numbers.
The following examples all represent a measurement of three quarters (of the
maximum of whatever is being measured):
75%750‰3/46 blocks used (out of 8 total)max: 100; current: 75The following example is incorrect use of the element, because it doesn't give a
range (and since the default maximum is 1, both of the gauges would end up
looking maxed out):
The grapefruit pie had a radius of 12cm
and a height of 2cm.
Instead, one would either not include the meter element, or use the meter
element with a defined range to give the dimensions in context compared to other
pies:
The grapefruit pie had a radius of 12cm and a height of
2cm.
Radius:
12cm
Height:
2cm
There is no explicit way to specify units in the meter element, but the units
may be specified in the title attribute in freeform text.
The example above could be extended to mention the units:
Radius:
12cm
Height:
2cm
User agent requirements: User agents must parse the min, max, value, low, high,
and optimum attributes using the rules for parsing floating point number values.
If the value attribute has been omitted, the user agent must also process the
textContent of the element according to the steps for finding one or two numbers
of a ratio in a string. These steps will return nothing, one number, one number
with a denominator punctuation character, or two numbers.
User agents must then use all these numbers to obtain values for six points on
the gauge, as follows. (The order in which these are evaluated is important, as
some of the values refer to earlier ones.)
The minimum value
If the min attribute is specified and a value could be parsed out of it, then
the minimum value is that value. Otherwise, the minimum value is zero.
The maximum value
If the max attribute is specified and a value could be parsed out of it, the
maximum value is that value.
Otherwise, if the max attribute is specified but no value could be parsed out
of it, or if it was not specified, but either or both of the min or value
attributes were specified, then the maximum value is 1.
Otherwise, none of the max, min, and value attributes were specified. If the
result of processing the textContent of the element was either nothing or just
one number with no denominator punctuation character, then the maximum value
is 1; if the result was one number but it had an associated denominator
punctuation character, then the maximum value is the value associated with
that denominator punctuation character; and finally, if there were two numbers
parsed out of the textContent, then the maximum is the higher of those two
numbers.
If the above machinations result in a maximum value less than the minimum
value, then the maximum value is actually the same as the minimum value.
The actual value
If the value attribute is specified and a value could be parsed out of it,
then that value is the actual value.
If the value attribute is not specified but the max attribute is specified and
the result of processing the textContent of the element was one number with no
associated denominator punctuation character, then that number is the actual
value.
If neither of the value and max attributes are specified, then, if the result
of processing the textContent of the element was one number (with or without
an associated denominator punctuation character), then that is the actual
value, and if the result of processing the textContent of the element was two
numbers, then the actual value is the lower of the two numbers found.
Otherwise, if none of the above apply, the actual value is zero.
If the above procedure results in an actual value less than the minimum value,
then the actual value is actually the same as the minimum value.
If, on the other hand, the result is an actual value greater than the maximum
value, then the actual value is the maximum value.
The low boundary
If the low attribute is specified and a value could be parsed out of it, then
the low boundary is that value. Otherwise, the low boundary is the same as the
minimum value.
If the above results in a low boundary that is less than the minimum value,
the low boundary is the minimum value.
The high boundary
If the high attribute is specified and a value could be parsed out of it, then
the high boundary is that value. Otherwise, the high boundary is the same as
the maximum value.
If the above results in a high boundary that is higher than the maximum value,
the high boundary is the maximum value.
The optimum point
If the optimum attribute is specified and a value could be parsed out of it,
then the optimum point is that value. Otherwise, the optimum point is the
midpoint between the minimum value and the maximum value.
If the optimum point is then less than the minimum value, then the optimum
point is actually the same as the minimum value. Similarly, if the optimum
point is greater than the maximum value, then it is actually the maximum value
instead.
All of which should result in the following inequalities all being true:
minimum value ≤ actual value ≤ maximum value
minimum value ≤ low boundary ≤ high boundary ≤ maximum value
minimum value ≤ optimum point ≤ maximum value
UA requirements for regions of the gauge: If the optimum point is equal to the
low boundary or the high boundary, or anywhere in between them, then the region
between the low and high boundaries of the gauge must be treated as the optimum
region, and the low and high parts, if any, must be treated as suboptimal.
Otherwise, if the optimum point is less than the low boundary, then the region
between the minimum value and the low boundary must be treated as the optimum
region, the region between the low boundary and the high boundary must be
treated as a suboptimal region, and the region between the high boundary and the
maximum value must be treated as an even less good region. Finally, if the
optimum point is higher than the high boundary, then the situation is reversed;
the region between the high boundary and the maximum value must be treated as
the optimum region, the region between the high boundary and the low boundary
must be treated as a suboptimal region, and the remaining region between the low
boundary and the minimum value must be treated as an even less good region.
UA requirements for showing the gauge: When representing a meter element to the
user, the UA should indicate the relative position of the actual value to the
minimum and maximum values, and the relationship between the actual value and
the three regions of the gauge.
The following markup:
Might be rendered as follows:
User agents may combine the value of the title attribute and the other
attributes to provide context-sensitive help or inline text detailing the actual
values.
For example, the following snippet:
...might cause the user agent to display a gauge with a tooltip saying "Value:
23.2 out of 60." on one line and "seconds" on a second line.
The min, max, value, low, high, and optimum DOM attributes must reflect the
elements' content attributes of the same name. When the relevant content
attributes are absent, the DOM attributes must return zero. The value parsed
from the textContent never affects the DOM values.
Would be cool to have the value DOM attribute update the textContent in-line...
3.12.13. The code element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None, but the title attribute has special semantics on this element when used
with the dfn element.
DOM interface:
No difference from HTMLElement.
The code element represents a fragment of computer code. This could be an XML
element name, a filename, a computer program, or any other string that a
computer would recognise.
Although there is no formal way to indicate the language of computer code being
marked up, authors who wish to mark code elements with the language used, e.g.
so that syntax highlighting scripts can use the right rules, may do so by adding
a class prefixed with "language-" to the element.
The following example shows how a block of code could be marked up using the pre
and code elements.
var i: Integer;
begin
i := 1;
end.
A class is used in that example to indicate the language used.
See the pre element for more detais.
3.12.14. The var element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None, but the title attribute has special semantics on this element when used
with the dfn element.
DOM interface:
No difference from HTMLElement.
The var element represents a variable. This could be an actual variable in a
mathematical expression or programming context, or it could just be a term used
as a placeholder in prose.
In the paragraph below, the letter "n" is being used as a variable in prose:
If there are n pipes leading to the ice
cream factory then I expect at leastn
flavours of ice cream to be available for purchase!
3.12.15. The samp element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None, but the title attribute has special semantics on this element when used
with the dfn element.
DOM interface:
No difference from HTMLElement.
The samp element represents (sample) output from a program or computing system.
See the pre and kbd elements for more detais.
This example shows the samp element being used inline:
The computer said Too much cheese in tray
two but I didn't know what that meant.
This second example shows a block of sample output. Nested samp and kbd elements
allow for the styling of specific elements of the sample output using a style
sheet.
jdoe@mowmow:~$ssh demo.example.com
Last login: Tue Apr 12 09:10:17 2005 from mowmow.example.com on pts/1
Linux demo 2.6.10-grsec+gg3+e+fhs6b+nfs+gr0501+++p3+c4a+gr2b-reslog-v6.189 #1 SMP Tue Feb 1 11:22:36 PST 2005 i686 unknown
jdoe@demo:~$_
3.12.16. The kbd element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The kbd element represents user input (typically keyboard input, although it may
also be used to represent other input, such as voice commands).
When the kbd element is nested inside a samp element, it represents the input as
it was echoed by the system.
When the kbd element contains a samp element, it represents input based on
system output, for example invoking a menu item.
When the kbd element is nested inside another kbd element, it represents an
actual key or other single unit of input as appropriate for the input mechanism.
Here the kbd element is used to indicate keys to press:
To make George eat an apple, press Shift+F3
In this second example, the user is told to pick a particular menu item. The
outer kbd element marks up a block of input, with the inner kbd elements
representing each individual step of the input, and the samp elements inside
them indicating that the steps are input based on something being displayed by
the system, in this case menu labels:
To make George eat an apple, select
File|Eat Apple...
3.12.17. The sub and sup elements
Categories
Phrasing content.
Contexts in which these elements may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The sup element represents a superscript and the sub element represents a
subscript.
These elements must only be used to mark up typographical conventions with
specific meanings, not for typographical presentation for presentation's sake.
For example, it would be inappropriate for the sub and sup elements to be used
in the name of the LaTeX document preparation system. In general, authors should
only use these elements if the absence of those elements would change the
meaning of the content.
When the sub element is used inside a var element, it represents the subscript
that identifies the variable in a family of variables.
The coordinate of the ith point is
(xi, yi).
For example, the 10th point has coordinate
(x10, y10).
In certain languages, superscripts are part of the typographical conventions for
some abbreviations.
The most beautiful women are
Mlle Gwendoline and
Mme Denise.
Mathematical expressions often use subscripts and superscripts.
E=mc2f(x, n) = log4xn3.12.18. The span element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None, but the title attribute has special semantics on this element when used
with the dfn element.
DOM interface:
No difference from HTMLElement.
The span element doesn't mean anything on its own, but can be useful when used
together with other attributes, e.g. class, lang, or dir, or when used in
conjunction with the dfn element.
3.12.19. The i element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None, but the title attribute has special semantics on this element when used
with the dfn element.
DOM interface:
No difference from HTMLElement.
The i element represents a span of text in an alternate voice or mood, or
otherwise offset from the normal prose, such as a taxonomic designation, a
technical term, an idiomatic phrase from another language, a thought, a ship
name, or some other prose whose typical typographic presentation is italicized.
Terms in languages different from the main text should be annotated with lang
attributes (xml:lang in XML).
The examples below show uses of the i element:
The felis silvestris catus is cute.
The term prose content is defined above.
There is a certain je ne sais quoi in the air.
In the following example, a dream sequence is marked up using i elements.
Raymond tried to sleep.
The ship sailed away on Thursday, he
dreamt. The ship had many people aboard, including a beautiful
princess called Carey. He watched her, day-in, day-out, hoping she
would notice him, but she never did.
Finally one night he picked up the courage to speak with
her—
Raymond woke with a start as the fire alarm rang out.
The i element should be used as a last resort when no other element is more
appropriate. In particular, citations should use the cite element, defining
instances of terms should use the dfn element, stress emphasis should use the em
element, importance should be denoted with the strong element, quotes should be
marked up with the q element, and small print should use the small element.
Style sheets can be used to format i elements, just like any other element can
be restyled. Thus, it is not the case that content in i elements will
necessarily be italicised.
3.12.20. The b element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The b element represents a span of text to be stylistically offset from the
normal prose without conveying any extra importance, such as key words in a
document abstract, product names in a review, or other spans of text whose
typical typographic presentation is boldened.
The following example shows a use of the b element to highlight key words
without marking them up as important:
The frobonitor and barbinator components are fried.
The following would be incorrect usage:
WARNING! Do not frob the barbinator!
In the previous example, the correct element to use would have been strong, not
b.
In the following example, objects in a text adventure are highlighted as being
special by use of the b element.
You enter a small room. Your sword glows
brighter. A rat scurries past the corner wall.
Another case where the b element is appropriate is in marking up the lede (or
lead) sentence or paragraph. The following example shows how a BBC article about
kittens adopting a rabbit as their own could be marked up using HTML5 elements:
Kittens 'adopted' by pet rabbit
Six abandoned kittens have found an unexpected new
mother figure — a pet rabbit.
Veterinary nurse Melanie Humble took the three-week-old
kittens to her Aberdeen home.
[...]The b element should be used as a last resort when no other element is more
appropriate. In particular, headers should use the h1 to h6 elements, stress
emphasis should use the em element, importance should be denoted with the strong
element, and text marked or highlighted should use the m element.
Style sheets can be used to format b elements, just like any other element can
be restyled. Thus, it is not the case that content in b elements will
necessarily be boldened.
3.12.21. The bdo element
Categories
Phrasing content.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Element-specific attributes:
None, but the dir global attribute has special requirements on this element.
DOM interface:
No difference from HTMLElement.
The bdo element allows authors to override the Unicode bidi algorithm by
explicitly specifying a direction override. [BIDI]
Authors must specify the dir attribute on this element, with the value ltr to
specify a left-to-right override and with the value rtl to specify a
right-to-left override.
If the element has the dir attribute set to the exact value ltr, then for the
purposes of the bidi algorithm, the user agent must act as if there was a U+202D
LEFT-TO-RIGHT OVERRIDE character at the start of the element, and a U+202C POP
DIRECTIONAL FORMATTING at the end of the element.
If the element has the dir attribute set to the exact value rtl, then for the
purposes of the bidi algorithm, the user agent must act as if there was a U+202E
RIGHT-TO-LEFT OVERRIDE character at the start of the element, and a U+202C POP
DIRECTIONAL FORMATTING at the end of the element.
The requirements on handling the bdo element for the bidi algorithm may be
implemented indirectly through the style layer. For example, an HTML+CSS user
agent should implement these requirements by implementing the CSS unicode-bidi
property. [CSS21]
3.13. Edits
The ins and del elements represent edits to the document.
Since the ins and del elements do not affect paragraphing, it is possible, in
some cases where paragraphs are implied (without explicit p elements), for an
ins or del element to span both an entire paragraph or other non-phrasing
content elements and part of another paragraph.
For example:
This is a paragraph that was inserted.
This is another paragraph whose first sentence was inserted
at the same time as the paragraph above.
This is a second sentence, which was there all along.
By only wrapping some paragraphs in p elements, one can even get the end of one
paragraph, a whole second paragraph, and the start of a third paragraph to be
covered by the same ins or del element (though this is very confusing, and not
considered good practice):
This is the first paragraph. This sentence was
inserted.
This second paragraph was inserted.
This sentence was inserted too. This is the
third paragraph in this example.
However, due to the way implied paragraphs are defined, it is not possible to
mark up the end of one paragraph and the start of the very next one using the
same ins or del element. You instead have to use one (or two) p element(s) and
two ins or del elements:
For example:
This is the first paragraph. This sentence was
deleted.
This sentence was deleted too. That
sentence needed a separate <del> element.
Partly because of the confusion described above, authors are strongly
recommended to always mark up all paragraphs with the p element, and to not have
any ins or del elements that cross across any implied paragraphs.
3.13.1. The ins element
Categories
When the element only contains phrasing content: phrasing content.
Otherwise: prose content.
Contexts in which this element may be used:
When the element only contains phrasing content: where phrasing content is
expected.
Otherwise: where prose content is expected.
Content model:
Transparent.
Element-specific attributes:
cite
datetime
DOM interface:
Uses the HTMLModElement interface.
The ins element represents an addition to the document.
The following represents the addition of a single paragraph:
As does this, because everything in the aside element here counts as phrasing
content and therefore there is just one paragraph:
ins elements should not cross implied paragraph boundaries.
The following example represents the addition of two paragraphs, the second of
which was inserted in two parts. The first ins element in this example thus
crosses a paragraph boundary, which is considered poor form.
Here is a better way of marking this up. It uses more elements, but none of the
elements cross implied paragraph boundaries.
3.13.2. The del element
Categories
When the element only contains phrasing content: phrasing content.
Otherwise: prose content.
Contexts in which this element may be used:
When the element only contains phrasing content: where phrasing content is
expected.
Otherwise: where prose content is expected.
Content model:
Transparent.
Element-specific attributes:
cite
datetime
DOM interface:
Uses the HTMLModElement interface.
The del element represents a removal from the document.
del elements should not cross implied paragraph boundaries.
3.13.3. Attributes common to ins and del elements
The cite attribute may be used to specify a URI that explains the change. When
that document is long, for instance the minutes of a meeting, authors are
encouraged to include a fragment identifier pointing to the specific part of
that document that discusses the change.
If the cite attribute is present, it must be a URI (or IRI) that explains the
change. User agents should allow users to follow such citation links.
The datetime attribute may be used to specify the time and date of the change.
If present, the datetime attribute must be a valid datetime value.
User agents must parse the datetime attribute according to the parse a string as
a datetime value algorithm. If that doesn't return a time, then the modification
has no associated timestamp (the value is non-conforming; it is not a valid
datetime). Otherwise, the modification is marked as having been made at the
given datetime. User agents should use the associated timezone information to
determine which timezone to present the given datetime in.
The ins and del elements must implement the HTMLModElement interface:
interface HTMLModElement : HTMLElement {
attribute DOMString cite;
attribute DOMString dateTime;
};The cite DOM attribute must reflect the element's >cite content attribute. The
dateTime DOM attribute must reflect the element's datetime content attribute.
3.14. Embedded content
3.14.1. The figure element
Categories
Prose content.
Contexts in which this element may be used:
Where prose content is expected.
Content model:
Either one legend element followed by prose content.
Or: Prose content followed by one legend element.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.
The figure element represents some prose content with a caption.
The first legend element child of the element, if any, represents the caption of
the figure element's contents. If there is no child legend element, then there
is no caption.
The remainder of the element's contents, if any, represents the captioned
content.
3.14.2. The img element
Categories
Embedded content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Empty.
Element-specific attributes:
alt
src
usemap
ismap
width
height
DOM interface:
interface HTMLImageElement : HTMLElement {
attribute DOMString alt;
attribute DOMString src;
attribute DOMString useMap;
attribute boolean isMap;
attribute long width;
attribute long height;
readonly attribute boolean complete;
};An instance of HTMLImageElement can be obtained using the Image constructor.
An img element represents an image.
The image given by the src attribute is the embedded content, and the value of
the alt attribute is the img element's fallback content.
Authoring requirements: The src attribute must be present, and must contain a
URI (or IRI).
Should we restrict the URI to pointing to an image? What's an image? Is PDF an
image? (Safari supports PDFs in elements.) How about SVG? (Opera supports
those). WMFs? XPMs? HTML?
The requirements for the alt attribute depend on what the image is intended to
represent:
A phrase or paragraph with an alternative graphical representation
Sometimes something can be more clearly stated in graphical form, for example
as a flowchart, a diagram, a graph, or a simple map showing directions. In
such cases, an image can be given using the img element, but the lesser
textual version must still be given, so that users who are unable to view the
image (e.g. because they have a very slow connection, or because they are
using a text-only browser, or because they are listening to the page being
read out by a hands-free automobile voice Web browser, or simply because they
are blind) are still able to understand the message being conveyed.
The text must be given in the alt attribute, and must convey the same message
as the the image specified in the src attribute.
In the following example we have a flowchart in image form, with text in the
alt attribute rephrasing the flowchart in prose form:
In the common case, the data handled by the tokenisation stage
comes from the network, but it can also come from script.
Here's another example, showing a good solution and a bad solution to the
problem of including an image in a description.
First, here's the good solution. This sample shows how the alternative text
should just be what you would have put in the prose if the image had never
existed.
You are standing in an open field west of a house.
There is a small mailbox here.
Second, here's the bad solution. In this incorrect way of doing things, the
alternative text is simply a description of the image, instead of a textual
replacement for the image. It's bad because when the image isn't shown, the
text doesn't flow as well as in the first example.
You are standing in an open field west of a house.
There is a small mailbox here.
It is important to realise that the alternative text is a replacement for the
image, not a description of the image.
Icons: a short phrase or label with an alternative graphical representation
A document can contain information in iconic form. The icon is intended to
help users of visual browsers to recognise features at a glance.
In some cases, the icon is supplemental to a text label conveying the same
meaning. In those cases, the alt attribute must be present but must be empty.
Here the icons are next to text that conveys the same meaning, so they have an
empty alt attribute:
In other cases, the icon has no text next to it describing what it means; the
icon is supposed to be self-explanatory. In those cases, an equivalent textual
label must be given in the alt attribute.
Here, posts on a news site are labelled with an icon indicating their topic.
Ratatouille wins Best Movie of the Year award
Pixar has won yet another Best Movie of the Year award,
making this its 8th win in the last 12 years.
Latest TWiT episode is online
The latest TWiT episode has been posted, in which we hear
several tech news stories as well as learning much more about the
iPhone. This week, the panelists compare how reflective their
iPhones' Apple logos are.
Many pages include logos, insignia, flags, or emblems, which stand for a
particular entity such as a company, organisation, project, band, software
package, country, or some such.
If the logo is being used to represent the entity, the alt attribute must
contain the name of the entity being represented by the logo. The alt
attribute must not contain text like the word "logo", as it is not the fact
that it is a logo that is being conveyed, it's the entity itself.
If the logo is being used next to the name of the entity that it represents,
then the logo is supplemental, and its alt attribute must instead be empty.
If the logo is merely used as decorative material (as branding, or, for
example, as a side image in an article that mentions the entity to which the
logo belongs), then the entry below on purely decorative images applies. If
the logo is actually being discussed, then it is being used as a phrase or
paragraph (the description of the logo) with an alternative graphical
representation (the logo itself), and the first entry above applies.
In the following snippets, all four of the above cases are present. First, we
see a logo used to represent a company:
Next, we see a paragraph which uses a logo right next to the company name, and
so doesn't have any alternative text:
News
We have recently been looking at buying the ΑΒΓ company, a small Greek company
specialising in our type of product.
In this third snippet, we have a logo being used in an aside, as part of the
larger article discussing the acquisition:
The ΑΒΓ company has had a good quarter, and our
pie chart studies of their accounts suggest a much bigger blue slice
than its green and orange slices, which is always a good sign.
Finally, we have an opinion piece talking about a logo, and the logo is
therefore described in detail in the alternative text.
Consider for a moment their logo:
How unoriginal can you get? I mean, oooooh, a question mark, how
revolutionary, how utterly ground-breaking, I'm
sure everyone will rush to adopt those specifications now! They could
at least have tried for some sort of, I don't know, sequence of
rounded squares with varying shades of green and bold white outlines,
at least that would look good on the cover of a blue book.
This example shows how the alternative text should be written such that if the
image isn't available, and the text is used instead, the text flows seamlessly
into the surrounding text, as if the image had never been there in the first
place.
A graphical representation of some of the surrounding text
In many cases, the image is actually just supplementary, and its presence
merely reinforces the surrounding text. In these cases, the alt attribute must
be present but its value must be the empty string.
A flowchart that repeats the previous paragraph in graphical form:
The network passes data to the Tokeniser stage, which
passes data to the Tree Construction stage. From there, data goes
to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to
the Tokeniser.
A graph that repeats the previous paragraph in graphical form:
According to a study covering several billion pages,
about 62% of documents on the Web in 2007 triggered the Quirks
rendering mode of Web browsers, about 30% triggered the Almost
Standards mode, and about 9% triggered the Standards mode.
In general, an image falls into this category if removing the image doesn't
make the page any less useful, but including the image makes it a lot easier
for users of visual browsers to understand the concept.
A purely decorative image that doesn't add any information but is still
specific to the surrounding content
In some cases, the image isn't discussed by the surrounding text, but it has
some relevance. Such images are decorative, but still form part of the
content. In these cases, the alt attribute must be present but its value must
be the empty string.
Examples where the image is purely decorative despite being relevant would
include things like a photo of the Black Rock City landscape in a blog post
about an event at Burning Man, or an image of a painting inspired by a poem,
on a page reciting that poem. The following snippet shows an example of the
latter case (only the first verse is included in this snippet):
The Lady of Shalott
On either side the river lie
Long fields of barley and of rye,
That clothe the wold and meet the sky;
And through the field the road run by
To many-tower'd Camelot;
And up and down the people go,
Gazing where the lilies blow
Round an island there below,
The island of Shalott.
In general, if an image is decorative but isn't especially page-specific, for
example an image that forms part of a site-wide design scheme, the image
should be specified in the site's CSS, not in the markup of the document.
A key part of the content that doesn't have an obvious textual alternative
In certain rare cases, the image is simply a critical part of the content, and
there might even be no alternative text available. This could be the case, for
instance, in a photo gallery, where a user has uploaded 3000 photos from a
vacation trip, without providing any descriptions of the images. The images
are the whole point of the pages containing them.
In such cases, the alt attribute may be omitted, but the alt attribute should
be included, with a useful value, if at all possible. If an image is a key
part of the content, the alt attribute must not be specified with an empty
value.
A photo on a photo-sharing site:
A screenshot in a gallery of screenshots for a new OS:
In both cases, though, it would be better if a detailed description of the
important parts of the image were included.
Sometimes there simply is no text that can do justice to an image. For
example, there is little that can be said to usefully describe a Rorschach
inkblot test.
Note that the following would be a very bad use of alternative text:
Including the caption in the alternative text like this isn't useful because
it effectively duplicates the caption for users who don't have images,
taunting them twice yet not helping them any more than if they had only read
or heard the caption once.
Since some users cannot use images at all (e.g. because they have a very slow
connection, or because they are using a text-only browser, or because they are
listening to the page being read out by a hands-free automobile voice Web
browser, or simply because they are blind), the alt attribute should only be
omitted when no alternative text is available and none can be made available,
e.g. on automated image gallery sites.
An image in an e-mail or document intended for a specific person who is known
to be able to view images
When an image is included in a communication (such as an HTML e-mail) aimed at
someone who is known to be able to view images, the alt attribute may be
omitted. However, even in such cases it is stongly recommended that
alternative text be included (as appropriate according to the kind of image
involved, as described in the above entries), so that the e-mail is still
usable should the user use a mail client that does not support images, or
should the e-mail be forwarded on to other users whose abilities might not
include easily seeing images.
The img must not be used as a layout tool. In particular, img elements should
not be used to display fully transparent images, as they rarely convey meaning
and rarely add anything useful to the document.
There has been some suggestion that the longdesc attribute from HTML4, or some
other mechanism that is more powerful than alt="", should be included. This has
not yet been considered.
User agent requirements: When the alt attribute is present and its value is the
empty string, the image supplements the surrounding content. In such cases, the
image may be omitted without affecting the meaning of the document.
When the alt attribute is present and its value is not the empty string, the
image is a graphical equivalent of the string given in the alt attribute. In
such cases, the image may be replaced in the rendering by the string given in
the attribute without significantly affecting the meaning of the document.
When the alt attribute is missing, the image represents a key part of the
content. Non-visual user agents should apply image analysis heuristics to help
the user make sense of the image.
The alt attribute does not represent advisory information. User agents must not
present the contents of the alt attribute in the same way as content of the
title attribute.
If the src attribute is omitted, the image represents whatever string is given
by the element's alt attribute, if any, or nothing, if that attribute is empty
or absent.
When the src attribute is set, the user agent must immediately begin to download
the specified resource, unless the user agent cannot support images, or its
support for images has been disabled.
The download of the image must delay the load event.
This, unfortunately, can be used to perform a rudimentary port scan of the
user's local network (especially in conjunction with scripting, though scripting
isn't actually necessary to carry out such an attack). User agents may implement
cross-origin access control policies that mitigate this attack.
Once the download has completed, if the image is a valid image, the user agent
must fire a load event on the img element. If the download fails or it completes
but the image is not a valid or supported image, the user agent must fire an
error event on the img element.
The remote server's response metadata (e.g. an HTTP 404 status code, or
associated Content-Type headers) must be ignored when determining whether the
resource obtained is a valid image or not.
This allows servers to return images with error responses.
User agents must not support non-image resources with the img element.
The usemap attribute, if present, can indicate that the image has an associated
image map.
The ismap attribute, when used on an element that is a descendant of an a
element with an href attribute, indicates by its presence that the element
provides access to a server-side image map. This affects how events are handled
on the corresponding a element.
The ismap attribute is a boolean attribute. The attribute must not be specified
on an element that does not have an ancestor a element with an href attribute.
The img element supports dimension attributes.
The DOM attributes alt, src, useMap, and isMap each must reflect the respective
content attributes of the same name.
The DOM attributes height and width must return the rendered height and width of
the image, in CSS pixels, if the image is being rendered, and is being rendered
to a visual medium, or 0 otherwise. [CSS21]
The DOM attribute complete must return true if the user agent has downloaded the
image specified in the src attribute, and it is a valid image, and false
otherwise.
3.14.3. The iframe element
Categories
Embedded content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Text that conforms to the requirements given in the prose.
Element-specific attributes:
src
DOM interface:
interface HTMLIFrameElement : HTMLElement {
attribute DOMString src;
};Objects implementing the HTMLIFrameElement interface must also implement the
EmbeddingElement interface defined in the Window Object specification.
[WINDOW]
The iframe element introduces a new nested browsing context.
The src attribute, if present, must be a URI (or IRI) to a page that the nested
browsing context is to contain. When the browsing context is created, if the
attribute is present, the user agent must navigate this browsing context to the
given URI, with replacement enabled. If the user navigates away from this page,
the iframe's corresponding Window object will reference new Document objects,
but the src attribute will not change.
Whenever the src attribute is set, the nested browsing context must be navigated
to the given URI.
If the src attribute is not set when the element is created, the browsing
context will remain at the initial about:blank page.
When content loads in an iframe, after any load events are fired within the
content itself, the user agent must fire a load event at the iframe element.
When content fails to load (e.g. due to a network error), then the user agent
must fire an error event at the element instead.
When there is an active parser in the iframe, and when anything in the iframe
that is delaying the load event in the iframe's browsing context, the iframe
must delay the load event.
If, during the handling of the load event, the browsing context in the iframe is
again navigated, that will further delay the load event.
An iframe element never has fallback content, as it will always create a nested
browsing context, regardless of whether the specified initial contents are
successfully used.
Descendants of iframe elements represent nothing. (In legacy user agents that do
not support iframe elements, the contents would be parsed as markup that could
act as fallback content.)
The content model of iframe elements is text, except that the text must be such
that ... anyone have any bright ideas?
The HTML parser treats markup inside iframe elements as text.
The DOM attribute src must reflect the content attribute of the same name.
3.14.4. The embed element
Categories
Embedded content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Empty.
Element-specific attributes:
src
type
width
height
Any other attribute that has no namespace (see prose).
DOM interface:
interface HTMLEmbedElement : HTMLElement {
attribute DOMString src;
attribute DOMString type;
attribute long width;
attribute long height;
};Depending on the type of content instantiated by the embed element, the node
may also support other interfaces.
The embed element represents an integration point for an external (typically
non-HTML) application or interactive content.
The src attribute gives the address of the resource being embedded. The
attribute must be present and contain a URI (or IRI).
If the src attribute is missing, then the embed element must be ignored.
When the src attribute is set, user agents are expected to find an appropriate
handler for the specified resource, based on the content's type, and hand that
handler the content of the resource. If the handler supports a scriptable
interface, the HTMLEmbedElement object representing the element should expose
that interfaces.
The download of the resource must delay the load event.
The user agent should pass the names and values of all the attributes of the
embed element that have no namespace to the handler used. Any (namespace-less)
attribute may be specified on the embed element.
This specification does not define a mechanism for interacting with third-party
handlers, as it is expected to be user-agent-specific. Some UAs might opt to
support a plugin mechanism such as the Netscape Plugin API; others may use
remote content convertors or have built-in support for certain types. [NPAPI]
The embed element has no fallback content. If the user agent can't display the
specified resource, e.g. because the given type is not supported, then the user
agent must use a default handler for the content. (This default could be as
simple as saying "Unsupported Format", of course.)
The type attribute, if present, gives the MIME type of the linked resource. The
value must be a valid MIME type, optionally with parameters. [RFC2046]
The type of the content being embedded is defined as follows:
If the element has a type attribute, then the value of the type attribute is
the content's type.
Otherwise, if the specified resource has explicit Content-Type metadata, then
that is the content's type.
Otherwise, the content has no type and there can be no appropriate handler for
it.
Should we instead say that the content-sniffing that we're going to define for
top-level browsing contexts should apply here?
Should we require the type attribute to match the server information?
We should say that 404s, etc, don't affect whether the resource is used or not.
Not sure how to say it here though.
Browsers should take extreme care when interacting with external content
intended for third-party renderers. When third-party software is run with the
same privileges as the user agent itself, vulnerabilities in the third-party
software become as dangerous as those in the user agent.
The embed element supports dimension attributes.
The DOM attributes src and type each must reflect the respective content
attributes of the same name.
3.14.5. The object element
Categories
Embedded content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Zero or more param elements, then, transparent.
Element-specific attributes:
data
type
usemap
width
height
DOM interface:
interface HTMLObjectElement : HTMLElement {
attribute DOMString data;
attribute DOMString type;
attribute DOMString useMap;
attribute long width;
attribute long height;
};Objects implementing the HTMLObjectElement interface must also implement the
EmbeddingElement interface defined in the Window Object specification.
[WINDOW]
Depending on the type of content instantiated by the object element, the node
may also support other interfaces.
The object element can represent an external resource, which, depending on the
type of the resource, will either be treated as an image, as a nested browsing
context, or as an external resource to be processed by a third-party software
package.
The data attribute, if present, specifies the address of the resource. If
present, the attribute must be a URI (or IRI).
The type attribute, if present, specifies the type of the resource. If present,
the attribute must be a valid MIME type, optionally with parameters. [RFC2046]
One or both of the data and type attributes must be present.
Whenever the data attribute changes, or, if the data attribute is not present,
whenever the type attribute changes, the user agent must run the following steps
to determine what the object element represents:
If the data attribute is present, then:
Begin a load for the resource.
The download of the resource must delay the load event.
If the resource is not yet available (e.g. because the resource was not
available in the cache, so that loading the resource required making a
request over the network), then jump to step 3 in the overall set of steps
(fallback). When the resource becomes available, or if the load fails,
restart this algorithm from this step. Resources can load incrementally;
user agents may opt to consider a resource "available" whenever enough data
has been obtained to begin processing the resource.
If the load failed (e.g. DNS error), fire an error event at the element,
then jump to step 3 in the overall set of steps (fallback).
Determine the resource type, as follows:
This says to trust the type. Should we instead use the same mechanism as for
browsing contexts?
If the resource has associated Content-Type metadata
The type is the type specified in the resource's Content-Type metadata.
Otherwise, if the type attribute is present
The type is the type specified in the type attribute.
Otherwise, there is no explicit type information
The type is the sniffed type of the resource.
Handle the content as given by the first of the following cases that
matches:
If the resource requires a special handler (e.g. a plugin)
The user agent should find an appropriate handler for the specified
resource, based on the resource type found in the previous step, and pass
the content of the resource to that handler. If the handler supports a
scriptable interface, the HTMLObjectElement object representing the
element should expose that interface. The handler is not a nested browsing
context. If no appropriate handler can be found, then jump to step 3 in
the overall set of steps (fallback).
The user agent should pass the names and values of all the parameters
given by param elements that are children of the object element to the
handler used.
This specification does not define a mechanism for interacting with
third-party handlers, as it is expected to be user-agent-specific. Some
UAs might opt to support a plugin mechanism such as the Netscape Plugin
API; others may use remote content convertors or have built-in support for
certain types. [NPAPI]
this doesn't completely duplicate the navigation section, since it handles
, etc, but surely some work should be done to work with it
If the type of the resource is an XML MIME type
If the type of the resource is HTML
If the type of the resource does not start with "image/"
The object element must be associated with a nested browsing context, if
it does not already have one. The element's nested browsing context must
then be navigated to the given resource, with replacement enabled. (The
data attribute of the object element doesn't get updated if the browsing
context gets further navigated to other locations.)
navigation might end up treating it as something else, because it can do
sniffing. how should we handle that?
If the resource is a supported image format, and support for images has
not been disabled
The object element represents the specified image. The image is not a
nested browsing context.
shouldn't we use the image-sniffing stuff here?
Otherwise
The object element represents the specified image, but the image cannot be
shown. Jump to step 3 below in the overall set of steps (fallback).
The element's contents are not part of what the object element represents.
Once the resource is completely loaded, fire a load event at the element.
If the data attribute is absent but the type attribute is present, and if the
user agent can find a handler suitable according to the value of the type
attribute, then that handler should be used. If the handler supports a
scriptable interface, the HTMLObjectElement object representing the element
should expose that interface. The handler is not a nested browsing context. If
no suitable handler can be found, jump to the next step (fallback).
(Fallback.) The object element doesn't represent anything except what the
element's contents represent, ignoring any leading param element children.
This is the element's fallback content.
In the absence of other factors (such as style sheets), user agents must show
the user what the object element represents. Thus, the contents of object
elements act as fallback content, to be used only when referenced resources
can't be shown (e.g. because it returned a 404 error). This allows multiple
object elements to be nested inside each other, targeting multiple user agents
with different capabilities, with the user agent picking the best one it
supports.
The usemap attribute, if present while the object element represents an image,
can indicate that the object has an associated image map. The attribute must be
ignored if the object element doesn't represent an image.
The object element supports dimension attributes.
The DOM attributes data, type, and useMap each must reflect the respective
content attributes of the same name.
3.14.6. The param element
Categories
None.
Contexts in which this element may be used:
As a child of an object element, before any prose content.
Content model:
Empty.
Element-specific attributes:
name
value
DOM interface:
interface HTMLParamElement : HTMLElement {
attribute DOMString name;
attribute DOMString value;
};The param element defines parameters for handlers invoked by object elements.
The name attribute gives the name of the parameter.
The value attribute gives the value of the parameter.
Both attributes must be present. They may have any value.
If both attributes are present, and if the parent element of the param is an
object element, then the element defines a parameter with the given name/value
pair.
The DOM attributes name and value must both reflect the respective content
attributes of the same name.
3.14.7. The video element
Categories
Embedded content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
If the element has a src attribute: transparent.
If the element does not have a src attribute: one or more source elements,
then, transparent.
Element-specific attributes:
src
poster
autoplay
start
loopstart
loopend
end
playcount
controls
width
height
DOM interface:
interface HTMLVideoElement : HTMLMediaElement {
attribute long width;
attribute long height;
readonly attribute unsigned long videoWidth;
readonly attribute unsigned long videoHeight;
attribute DOMString poster;
};A video element represents a video or movie.
Content may be provided inside the video element. User agents should not show
this content to the user; it is intended for older Web browsers which do not
support video, so that legacy video plugins can be tried, or to show text to the
users of these older browser informing them of how to access the video contents.
In particular, this content is not fallback content intended to address
accessibility concerns. To make video content accessible to the blind, deaf, and
those with other physical or cognitive disabilities, authors are expected to
provide alternative media streams and/or to embed accessibility aids (such as
caption or subtitle tracks) into their media streams.
The video element is a media element whose media data is ostensibly video data,
possibly with associated audio data.
The src, autoplay, start, loopstart, loopend, end, playcount, and controls
attributes are the attributes common to all media elements.
The video element supports dimension attributes.
The poster attribute gives the address of an image file that the user agent can
show while no video data is available. The attribute, if present, must contain a
URI (or IRI).
The poster DOM attribute must reflect the poster content attribute.
The videoWidth DOM attribute must return the native width of the video in CSS
pixels. The videoHeight DOM attribute must return the native height of the video
in CSS pixels. In the absence of resolution information defining the mapping of
pixels in the video to physical dimensions, user agents may assume that one
pixel in the video corresponds to one CSS pixel. If no video data is available,
then the attributes must return 0.
When no video data is available (the element's networkState attribute is either
EMPTY, LOADING, or LOADED_METADATA), video elements represent either the image
given by the poster attribute, or nothing.
When a video element is actively playing, it represents the frame of video at
the continuously increasing "current" position. When the current playback
position changes such that the last frame rendered is no longer the frame
corresponding to the current playback position in the video, the new frame must
be rendered. Similarly, any audio associated with the video must, if played, be
played synchronised with the current playback position, at the specified volume
with the specified mute state.
When a video element is paused, the element represents the frame of video
corresponding to the current playback position, or, if that is not available yet
(e.g. because the video is seeking or buffering), the last rendered frame of
video.
When a video element is neither actively playing nor paused (e.g. when seeking
or stalled), the element represents the last frame of the video to have been
rendered.
Which frame in a video stream corresponds to a particular playback position is
defined by the video stream's format.
Video content should be rendered inside the element's playback area such that
the video content is shown centered in the playback area at the largest possible
size that fits completely within it, with the video content's aspect ratio being
preserved. Thus, if the aspect ratio of the playback area does not match the
aspect ratio of the video, the video will be shown letterboxed. Areas of the
element's playback area that do not contain the video represent nothing.
In addition to the above, the user agent may provide messages to the user (such
as "buffering", "no video loaded", "error", or more detailed information) by
overlaying text or icons on the video or other areas of the element's playback
area, or in another appropriate manner.
User agents that cannot render the video may instead make the element represent
a link to an external video playback utility or to the video data itself.
User agents should provide controls to enable or disable the display of closed
captions associated with the video stream, though such features should, again,
not interfere with the page's normal rendering.
User agents may allow users to view the video content in manners more suitable
to the user (e.g. full-screen or in an independent resizable window). As for the
other user interface features, controls to enable this should not interfere with
the page's normal rendering unless the user agent is exposing a user interface.
In such an independent context, however, user agents may make full user
interfaces visible, with, e.g., play, pause, seeking, and volume controls, even
if the controls attribute is absent.
User agents may allow video playback to affect system features that could
interfere with the user's experience; for example, user agents could disable
screensavers while video playback is in progress.
User agents should not provide a public API to cause videos to be shown
full-screen. A script, combined with a carefully crafted video file, could trick
the user into thinking a system-modal dialog had been shown, and prompt the user
for a password. There is also the danger of "mere" annoyance, with pages
launching full-screen videos when links are clicked or pages navigated. Instead,
user-agent specific interface features may be provided to easily allow the user
to obtain a full-screen playback mode.
3.14.7.1. Video and audio codecs for video elements
User agents may support any video and audio codecs and container formats.
It would be helpful for interoperability if all browsers could support the same
codecs. However, there are no known codecs that satisfy all the current players:
we need a codec that is known to not require per-unit or per-distributor
licensing, that is compatible with the open source development model, that is of
sufficient quality as to be usable, and that is not an additional submarine
patent risk for large companies. This is an ongoing issue and this section will
be updated once more information is available.
Certain user agents might support no codecs at all, e.g. text browsers running
over SSH connections.
3.14.8. The audio element
Categories
Embedded content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
If the element has a src attribute: transparent.
If the element does not have a src attribute: one or more source elements,
then, transparent.
Element-specific attributes:
src
autoplay
start
loopstart
loopend
end
playcount
controls
DOM interface:
interface HTMLAudioElement : HTMLMediaElement {
// no members
};An audio element represents a sound or audio stream.
Content may be provided inside the audio element. User agents should not show
this content to the user; it is intended for older Web browsers which do not
support audio, so that legacy audio plugins can be tried, or to show text to the
users of these older browser informing them of how to access the audio contents.
In particular, this content is not fallback content intended to address
accessibility concerns. To make audio content accessible to the deaf or to those
with other physical or cognitive disabilities, authors are expected to provide
alternative media streams and/or to embed accessibility aids (such as
transcriptions) into their media streams.
The audio element is a media element whose media data is ostensibly audio data.
The src, autoplay, start, loopstart, loopend, end, playcount, and controls
attributes are the attributes common to all media elements.
When an audio element is actively playing, it must have its audio data played
synchronised with the current playback position, at the specified volume with
the specified mute state.
When an audio element is not actively playing, audio must not play for the
element.
3.14.8.1. Audio codecs for audio elements
User agents may support any audio codecs and container formats.
User agents must support the WAVE container format with audio encoded using the
PCM format.
3.14.9. Media elements
Media elements implement the following interface:
interface HTMLMediaElement : HTMLElement {
// error state
readonly attribute MediaError error;
// network state
attribute DOMString src;
readonly attribute DOMString currentSrc;
const unsigned short EMPTY = 0;
const unsigned short LOADING = 1;
const unsigned short LOADED_METADATA = 2;
const unsigned short LOADED_FIRST_FRAME = 3;
const unsigned short LOADED = 4;
readonly attribute unsigned short networkState;
readonly attribute float bufferingRate;
readonly attribute TimeRanges buffered;
void load();
// ready state
const unsigned short DATA_UNAVAILABLE = 0;
const unsigned short CAN_SHOW_CURRENT_FRAME = 1;
const unsigned short CAN_PLAY = 2;
const unsigned short CAN_PLAY_THROUGH = 3;
readonly attribute unsigned short readyState;
readonly attribute boolean seeking;
// playback state
attribute float currentTime;
readonly attribute float duration;
readonly attribute boolean paused;
attribute float defaultPlaybackRate;
attribute float playbackRate;
readonly attribute TimeRanges played;
readonly attribute TimeRanges seekable;
readonly attribute boolean ended;
attribute boolean autoplay;
void play();
void pause();
// looping
attribute float start;
attribute float end;
attribute float loopStart;
attribute float loopEnd;
attribute unsigned long playCount;
attribute unsigned long currentLoop;
// cue ranges
void addCueRange(in DOMString className, in float start, in float end, in boolean pauseOnExit, in VoidCallback enterCallback, in VoidCallback exitCallback);
void removeCueRanges(in DOMString className);
// controls
attribute boolean controls;
attribute float volume;
attribute boolean muted;
};The media element attributes, src, autoplay, start, loopstart, loopend, end,
playcount, and controls, apply to all media elements. They are defined in this
section.
Media elements are used to present audio data, or video and audio data, to the
user. This is referred to as media data in this section, since this section
applies equally to media elements for audio or for video. The term media
resource is used to refer to the complete set of media data, e.g. the complete
video file, or complete audio file.
3.14.9.1. Error codes
All media elements have an associated error status, which records the last error
the element encountered since the load() method was last invoked. The error
attribute, on getting, must return the MediaError object created for this last
error, or null if there has not been an error.
interface MediaError {
const unsigned short MEDIA_ERR_ABORTED = 1;
const unsigned short MEDIA_ERR_NETWORK = 2;
const unsigned short MEDIA_ERR_DECODE = 3;
readonly attribute unsigned short code;
};The code attribute of a MediaError object must return the code for the error,
which must be one of the following:
MEDIA_ERR_ABORTED (numeric value 1)
The download of the media resource was aborted by the user agent at the user's
request.
MEDIA_ERR_NETWORK (numeric value 2)
A network error of some description caused the user agent to stop downloading
the media resource.
MEDIA_ERR_DECODE (numeric value 3)
An error of some description occurred while decoding the media resource.
3.14.9.2. Location of the media resource
The src content attribute on media elements gives the address of the media
resource (video, audio) to show. The attribute, if present, must contain a URI
(or IRI).
If the src attribute of a media element that is already in a document and whose
networkState is in the EMPTY state is added, changed, or removed, the user agent
must implicitly invoke the load() method on the media element as soon as all
other scripts have finished executing. Any exceptions raised must be ignored.
If a src attribute is specified, the resource it specifies is the media resource
that will be used. Otherwise, the resource specified by the first suitable
source element child of the media element is the one used.
The src DOM attribute on media elements must reflect the content attribute of
the same name.
To pick a media resource for a media element, a user agent must use the
following steps:
If the media element has a src, then the address given in that attribute is
the address of the media resource; jump to the last step.
Otherwise, let candidate be the first source element child in the media
element, or null if there is no such child.
If either:
candidate is null, or
the candidate element has no src attribute, or
the candidate element has a type attribute and that attribute's value, when
parsed as a MIME type, does not represent a type that the user agent can
render (including any codecs described by the codec parameter), or [RFC2046]
[RFC4281]
the candidate element has a media attribute and that attribute's value, when
processed according to the rules for media queries, does not match the
current environment, [MQ]
...then the candidate is not suitable; go to the next step.
Otherwise, the address given in that candidate element's src attribute is the
address of the media resource; jump to the last step.
Let candidate be the next source element child in the media element, or null
if there are no more such children.
If candidate is not null, return to step 3.
There is no media resource. Abort these steps.
Let the address of the chosen media resource be the one that was found before
jumping to this step.
A source element with no src attribute is assumed to be the last source element
— any source elements after it are ignored (and are invalid).
The currentSrc DOM attribute must return the empty string if the media element's
networkState has the value EMPTY, and the absolute URL of the chosen media
resource otherwise.
3.14.9.3. Network states
As media elements interact with the network, they go through several states. The
networkState attribute, on getting, must return the current network state of the
element, which must be one of the following values:
EMPTY (numeric value 0)
The element has not yet been initialised. All attributes are in their initial
states.
LOADING (numeric value 1)
The element has picked a media resource (the chosen media resource is
available from the currentSrc attribute), but none of the metadata has yet
been obtained and therefore all the other attributes are still in their
initial states.
LOADED_METADATA (numeric value 2)
Enough of the resource has been obtained that the metadata attributes are
initialized (e.g. the length is known). The API will no longer raise
exceptions when used.
LOADED_FIRST_FRAME (numeric value 3)
Actual media data has been obtained. In the case of video, this specifically
means that a frame of video is available and can be shown.
LOADED (numeric value 4)
The entire media resource has been obtained and is available to the user agent
locally. Network connectivity could be lost without affecting the media
playback.
The algorithm for the load() method defined below describes exactly when the
networkState attribute changes value.
3.14.9.4. Loading the media resource
All media elements have a begun flag, which must begin in the false state, a
loaded-first-frame flag, which must begin in the false state, and an autoplaying
flag, which must begin in the true state.
When the load() method on a media element is invoked, the user agent must run
the following steps. Note that this algorithm might get aborted, e.g. if the
load() method itself is invoked again.
Any already-running instance of this algorithm for this element must be
aborted. If those method calls have not yet returned, they must finish the
step they are on, and then immediately return.
If the element's begun flag is true, then the begun flag must be set to false,
the error attribute must be set to a new MediaError object whose code
attribute is set to MEDIA_ERR_ABORTED, and the user agent must synchronously
fire a progress event called abort at the media element.
The error attribute must be set to null, the loaded-first-frame flag must be
set to false, and the autoplaying flag must be set to true.
The playbackRate attribute must be set to the value of the defaultPlaybackRate
attribute.
If the media element's networkState is not set to EMPTY, then the following
substeps must be followed:
The networkState attribute must be set to EMPTY.
If readyState is not set to DATA_UNAVAILABLE, it must be set to that state.
If the paused attribute is false, it must be set to true.
If seeking is true, it must be set to false.
The current playback position must be set to 0.
The currentLoop DOM attribute must be set to 0.
The user agent must synchronously fire a simple event called emptied at the
media element.
The user agent must pick a media resource for the media element. If that
fails, the method must raise an INVALID_STATE_ERR exception, and abort these
steps.
The networkState attribute must be set to LOADING.
The currentSrc attribute starts returning the new value.
The user agent must then set the begun flag to true and fire a progress event
called begin at the media element.
The method must return, but these steps must continue.
Playback of any previously playing media resource for this element stops.
If a download is in progress for the media element, the user agent should stop
the download.
The user agent must then begin to download the chosen media resource. The rate
of the download may be throttled, however, in response to user preferences
(including throttling it to zero until the user indicates that the download
can start), or to balance the download with other connections sharing the same
bandwidth.
While the download is progressing, the user agent must fire a progress event
called progress at the element every 350ms (±200ms) or for every byte
received, whichever is least frequent.
If at any point the user agent has received no data for more than about three
seconds, the user agent must fire a progress event called stalled at the
element.
User agents may allow users to selectively block or slow media data downloads.
When a media element's download has been blocked, the user agent must act as
if it was stalled (as opposed to acting as if the connection was closed).
The user agent may use whatever means necessary to download the resource
(within the constraints put forward by this and other specifications); for
example, reconnecting to the server in the face of network errors, using HTTP
partial range requests, or switching to a streaming protocol. The user agent
must only consider a resource erroneous if it has given up trying to download
it.
If the media data cannot be downloaded at all, due to network errors,
causing the user agent to give up trying to download the resource
DNS errors and HTTP 4xx and 5xx errors (and equivalents in other protocols)
must cause the user agent to execute the following steps. User agents may
also follow these steps in response to other network errors of similar
severity.
The user agent should cancel the download.
The error attribute must be set to a new MediaError object whose code
attribute is set to MEDIA_ERR_NETWORK.
The begun flag must be set to false and the user agent must fire a
progress event called error at the media element.
The element's networkState attribute must be switched to the EMPTY value
and the user agent must fire a simple event called emptied at the element.
These steps must be aborted.
If the media data can be downloaded but is in an unsupported format, or can
otherwise not be rendered at all
The server returning a file of the wrong kind (e.g. one that that turns out
to not be pure audio when the media element is an audio element), or the
file using unsupported codecs for all the data, must cause the user agent to
execute the following steps. User agents may also execute these steps in
response to other codec-related fatal errors, such as the file requiring
more resources to process than the user agent can provide in real time.
The user agent should cancel the download.
The error attribute must be set to a new MediaError object whose code
attribute is set to MEDIA_ERR_DECODE.
The begun flag must be set to false and the user agent must fire a
progress event called error at the media element.
The element's networkState attribute must be switched to the EMPTY value
and the user agent must fire a simple event called emptied at the element.
These steps must be aborted.
If the media data download is aborted by the user
The download is aborted by the user, e.g. because the user navigated the
browsing context to another page, the user agent must execute the following
steps. These steps are not followed if the load() method itself is
reinvoked, as the steps above handle that particular kind of abort.
The user agent should cancel the download.
The error attribute must be set to a new MediaError object whose code
attribute is set to MEDIA_ERR_ABORT.
The begun flag must be set to false and the user agent must fire a
progress event called abort at the media element.
If the media element's networkState attribute has the value LOADING, the
element's networkState attribute must be switched to the EMPTY value and
the user agent must fire a simple event called emptied at the element. (If
the networkState attribute has a value greater than LOADING, then this
doesn't happen; the available data, if any, will be playable.)
These steps must be aborted.
If the media data can be downloaded but has non-fatal errors or uses, in
part, codecs that are unsupported, preventing the user agent from rendering
the content completely correctly but not preventing playback altogether
The server returning data that is partially usable but cannot be optimally
rendered must cause the user agent to execute the following steps.
Should we fire a 'warning' event? Set the 'error' flag to
'MEDIA_ERR_SUBOPTIMAL' or something?
Once enough of the media data has been downloaded to determine the duration
of the media resource, its dimensions, and other metadata
The user agent must follow these substeps:
The current playback position must be set to the effective start.
The networkState attribute must be set to LOADED_METADATA.
A number of attributes, including duration, buffered, and played, become
available.
The user agent will fire a simple event called durationchange at the
element at this point.
The user agent must fire a simple event called loadedmetadata at the
element.
Once enough of the media data has been downloaded to enable the user agent
to display the frame at the effective start of the media resource
The user agent must follow these substeps:
The networkState attribute must be set to LOADED_FIRST_FRAME.
The readyState attribute must change to CAN_SHOW_CURRENT_FRAME.
The loaded-first-frame flag must be set to true.
The user agent must fire a simple event called loadedfirstframe at the
element.
The user agent must fire a simple event called canshowcurrentframe at the
element.
When the user agent has completed the download of the entire media resource,
it must move on to the next step.
If the download completes without errors, the begun flag must be set to false,
the networkState attribute must be set to LOADED, and the user agent must fire
a progress event called load at the element.
If a media element whose networkState has the value EMPTY is inserted into a
document, user agents must implicitly invoke the load() method on the media
element as soon as all other scripts have finished executing. Any exceptions
raised must be ignored.
The bufferingRate attribute must return the average number of bits received per
second for the current download over the past few seconds. If there is no
download in progress, the attribute must return 0.
The buffered attribute must return a static normalised TimeRanges object that
represents the ranges of the media resource, if any, that the user agent has
downloaded, at the time the attribute is evaluated.
Typically this will be a single range anchored at the zero point, but if, e.g.
the user agent uses HTTP range requests in response to seeking, then there could
be multiple ranges.
3.14.9.5. Offsets into the media resource
The duration attribute must return the length of the media resource, in seconds.
If no media data is available, then the attributes must return 0. If media data
is available but the length is not known, the attribute must return the
Not-a-Number (NaN) value. If the media resource is known to be unbounded (e.g. a
streaming radio), then the attribute must return the positive Infinity value.
When the length of the media resource changes (e.g. from being unknown to known,
or from indeterminate to known, or from a previously established length to a new
length) the user agent must, once any running scripts have finished, fire a
simple event called durationchange at the media element.
Media elements have a current playback position, which must initially be zero.
The current position is a time.
The currentTime attribute must, on getting, return the current playback
position, expressed in seconds. On setting, the user agent must seek to the new
value (which might raise an exception).
The start content attribute gives the offset into the media resource at which
playback is to begin. The default value is the default start position of the
media resource, or 0 if not enough media data has been obtained yet to determine
the default start position or if the resource doesn't specify a default start
position.
The effective start is the smaller of the start DOM attribute and the end of the
media resource.
The loopstart content attribute gives the offset into the media resource at
which playback is to begin when looping a clip. The default value of the
loopstart content attribute is the value of the start DOM attribute.
The effective loop start is the smaller of the loopStart DOM attribute and the
end of the media resource.
The loopend content attribute gives an offset into the media resource at which
playback is to jump back to the loopstart, when looping the clip. The default
value of the loopend content attribute is the value of the end DOM attribute.
The effective loop end is the greater of the start, loopStart, and loopEnd DOM
attributes, except if that is greater than the end of the media resource, in
which case that's its value.
The end content attribute gives an offset into the media resource at which
playback is to end. The default value is infinity.
The effective end is the greater of the start, loopStart, and end DOM
attributes, except if that is greater than the end of the media resource, in
which case that's its value.
The start, loopstart, loopend, and end attributes must, if specified, contain
value time offsets. To get the time values they represent, user agents must use
the rules for parsing time offsets.
The start, loopStart, loopEnd, and end DOM attributes must reflect the start,
loopstart, loopend, and end content attributes on the media element
respectively.
The playcount content attribute gives the number of times to play the clip. The
default value is 1.
The playCount DOM attribute must reflect the playcount content attribute on the
media element. The value must be limited to only positive non-zero numbers.
The currentLoop attribute must initially have the value 0. It gives the index of
the current loop. It is changed during playback as described below.
When any of the start, loopStart, loopEnd, end, and playCount DOM attributes
change value (either through content attribute mutations reflecting into the DOM
attribute, or direct mutations of the DOM attribute), the user agent must apply
the following steps:
If the playCount DOM attribute's value is less than or equal to the
currentLoop DOM attribute's value, then the currentLoop DOM attribute's value
must be set to playCount-1 (which will make the current loop the last loop).
If the media element's networkState is in the EMPTY state or the LOADING
state, then the user agent must at this point abort these steps.
If the currentLoop is zero, and the current playback position is before the
effective start, the user agent must seek to the effective start.
If the currentLoop is greater than zero, and the current playback position is
before the effective loop start, the user agent must seek to the effective
loop start.
If the currentLoop is less than playCount-1, and the current playback position
is after the effective loop end, the user agent must seek to the effective
loop start, and increase currentLoop by 1.
If the currentLoop is equal to playCount-1, and the current playback position
is after the effective end, the user agent must seek to the effective end and
then the looping will end.
3.14.9.6. The ready states
Media elements have a ready state, which describes to what degree they are ready
to be rendered at the current playback position. The possible values are as
follows; the ready state of a media element at any particular time is the
greatest value describing the state of the element:
DATA_UNAVAILABLE (numeric value 0)
No data for the current playback position is available. Media elements whose
networkState attribute is less than LOADED_FIRST_FRAME are always in the
DATA_UNAVAILABLE state.
CAN_SHOW_CURRENT_FRAME (numeric value 1)
Data for the immediate current playback position is available, but not enough
data is available that the user agent could successfully advance the current
playback position at all without immediately reverting to the DATA_UNAVAILABLE
state. In video, this corresponds to the user agent having data from the
current frame, but not the next frame. In audio, this corresponds to the user
agent only having audio up to the current playback position, but no further.
CAN_PLAY (numeric value 2)
Data for the immediate current playback position is available, as well as
enough data for the user agent to advance the current playback position at
least a little without immediately reverting to the DATA_UNAVAILABLE state. In
video, this corresponds to the user agent having data for the current frame
and the next frame. In audio, this corresponds ot the user agent having data
beyond the current playback position.
CAN_PLAY_THROUGH (numeric value 3)
Data for the immediate current playback position is available, as well as
enough data for the user agent to advance the current playback position at
least a little without immediately reverting to the DATA_UNAVAILABLE state,
and, in addition, the user agent estimates that data is being downloaded at a
rate where the current playback position, if it were to advance at the rate
given by the defaultPlaybackRate attribute, would not overtake the available
data before playback reaches the effective end of the media resource on the
last loop.
When the ready state of a media element whose networkState is not EMPTY changes,
the user agent must follow the steps given below:
If the new ready state is DATA_UNAVAILABLE
The user agent must fire a simple event called dataunavailable at the element.
If the new ready state is CAN_SHOW_CURRENT_FRAME
If the element's loaded-first-frame flag is true, the user agent must fire a
simple event called canshowcurrentframe event.
The first time the networkState attribute switches to this value, the
loaded-first-frame flag is false, and the event is fired by the algorithm
described above for the load() method, in conjunction with other steps.
If the new ready state is CAN_PLAY
The user agent must fire a simple event called canplay.
If the new ready state is CAN_PLAY_THROUGH
The user agent must fire a simple event called canplaythrough event. If the
autoplaying flag is true, and the paused attribute is true, and the media
element has an autoplay attribute specified, then the user agent must also set
the paused attribute to false and fire a simple event called play.
It is possible for the ready state of a media element to jump between these
states discontinuously. For example, the state of a media element whose
leaded-first-frame flag is false can jump straight from DATA_UNAVAILABLE to
CAN_PLAY_THROUGH without passing through the CAN_SHOW_CURRENT_FRAME and CAN_PLAY
states, and thus without firing the canshowcurrentframe and canplay events. The
only state that is guarenteed to be reached is the CAN_SHOW_CURRENT_FRAME state,
which is reached as part of the load() method's processing.
The readyState DOM attribute must, on getting, return the value described above
that describes the current ready state of the media element.
The autoplay attribute is a boolean attribute. When present, the algorithm
described herein will cause the user agent to automatically begin playback of
the media resource as soon as it can do so without stopping.
The autoplay DOM attribute must reflect the content attribute of the same name.
3.14.9.7. Playing the media resource
The paused attribute represents whether the media element is paused or not. The
attribute must initially be true.
A media element is said to be actively playing when its paused attribute is
false, the readyState attribute is either CAN_PLAY or CAN_PLAY_THROUGH, the
element has not ended playback, playback has not stopped due to errors, and the
element has not paused for user interaction.
A media element is said to have ended playback when the element's networkState
attribute is LOADED_METADATA or greater, the current playback position is equal
to the effective end of the media resource, and the currentLoop attribute is
equal to playCount-1.
A media element is said to have stopped due to errors when the element's
networkState attribute is LOADED_METADATA or greater, and the user agent
encounters a non-fatal error during the processing of the media data, and due to
that error, is not able to play the content at the current playback position.
A media element is said to have paused for user interaction when its paused
attribute is false, the readyState attribute is either CAN_PLAY or
CAN_PLAY_THROUGH and the user agent has reached a point in the media resource
where the user has to make a selection for the resource to continue.
It is possible for a media element to have both ended playback and paused for
user interaction at the same time.
When a media element is actively playing and its owner Document is an active
document, its current playback position must increase monotonically at
playbackRate units of media time per unit time of wall clock time. If this value
is not 1, the user agent may apply pitch adjustments to any audio component of
the media resource.
Media resources might be internally scripted or interactive. Thus, a media
element could play in a non-linear fashion. If this happens, the user agent must
act as if the algorithm for seeking was used whenever the current playback
position changes in a discontinuous fashion (so that the relevant events fire).
When a media element that is actively playing stops playing because its
readyState attribute changes to a value lower than CAN_PLAY, without the element
having ended playback, or playback having stopped due to errors, or playback
having paused for user interaction, the user agent must fire a simple event
called timeupdate at the element, and then must fire a simple event called
waiting at the element.
When a media element that is actively playing stops playing because it has
paused for user interaction, the user agent must fire a simple event called
timeupdate at the element.
When currentLoop is less than playCount-1 and the current playback position
reaches the effective loop end, then the user agent must seek to the effective
loop start, increase currentLoop by 1, and fire a simple event called
timeupdate.
When currentLoop is equal to the playCount-1 and the current playback position
reaches the effective end, then the user agent must follow these steps:
The user agent must stop playback.
The ended attribute becomes true.
The user agent must fire a simple event called timeupdate at the element.
The user agent must fire a simple event called ended at the element.
The defaultPlaybackRate attribute gives the desired speed at which the media
resource is to play, as a multiple of its intrinsic speed. The attribute is
mutable, but on setting, if the new value is 0.0, a NOT_SUPPORTED_ERR exception
must be raised instead of the value being changed. It must initially have the
value 1.0.
The playbackRate attribute gives the speed at which the media resource plays, as
a multiple of its intrinsic speed. If it is not equal to the
defaultPlaybackRate, then the implication is that the user is using a feature
such as fast forward or slow motion playback. The attribute is mutable, but on
setting, if the new value is 0.0, a NOT_SUPPORTED_ERR exception must be raised
instead of the value being changed. Otherwise, the playback must change speed
(if the element is actively playing). It must initially have the value 1.0.
When the defaultPlaybackRate or playbackRate attributes change value (either by
being set by script or by being changed directly by the user agent, e.g. in
response to user control) the user agent must, once any running scripts have
finished, fire a simple event called ratechange at the media element.
When the play() method on a media element is invoked, the user agent must run
the following steps.
If the media element's networkState attribute has the value EMPTY, then the
user agent must invoke the load() method and wait for it to return. If that
raises an exception, that exception must be reraised by the play() method.
If the playback has ended, then the user agent must set currentLoop to zero
and seek to the effective start.
The playbackRate attribute must be set to the value of the defaultPlaybackRate
attribute.
If the media element's paused attribute is true, it must be set to false.
The media element's autoplaying flag must be set to false.
The method must then return.
If the second step above involved a seek, the user agent will fire a simple
event called timeupdate at the media element.
If the third step above caused the playbackRate attribute to change value, the
user agent will fire a simple event called ratechange at the media element.
If the fourth step above changed the value of paused, the user agent must fire a
simple event called play at the media element.
When the pause() method is invoked, the user agent must run the following steps:
If the media element's networkState attribute has the value EMPTY, then the
user agent must invoke the load() method and wait for it to return. If that
raises an exception, that exception must be reraised by the pause() method.
If the media element's paused attribute is false, it must be set to true.
The media element's autoplaying flag must be set to false.
The method must then return.
If the second step above changed the value of paused, the user agent must
first fire a simple event called timeupdate at the element, and then fire a
simple event called pause at the element.
When a media element is removed from a Document, the user agent must act as if
the pause() method had been invoked.
Media elements that are actively playing while not in a Document must not play
any video, but should play any audio component. Media elements must not stop
playing just because all references to them have been removed; only once a media
element to which no references exist has reached a point where no further audio
remains to be played for that element (e.g. because the element is paused or
because the end of the clip has been reached) may the element be garbage
collected.
If the media element's ownerDocument stops being an active document, then the
playback will stop until the document is active again.
The ended attribute must return true if the media element has ended playback,
and false otherwise.
The played attribute must return a static normalised TimeRanges object that
represents the ranges of the media resource, if any, that the user agent has so
far rendered, at the time the attribute is evaluated.
3.14.9.8. Seeking
The seeking attribute must initially have the value false.
When the user agent is required to seek to a particular new playback position in
the media resource, it means that the user agent must run the following steps:
If the media element's networkState is less than LOADED_METADATA, then the
user agent must raise an INVALID_STATE_ERR exception (if the seek was in
response to a DOM method call or setting of a DOM attribute), and abort these
steps.
If currentLoop is 0, let min be the effective start. Otherwise, let it be the
effective loop start.
If currentLoop is equal to the value of playCount, let max be the effective
end. Otherwise, let it be the effective loop end.
If the new playback position is more than max, let it be max.
If the new playback position is less than min, let it be min.
If the (possibly now changed) new playback position is not in one of the
ranges given in the seekable attribute, then the user agent must raise an
INDEX_SIZE_ERR exception (if the seek was in response to a DOM method call or
setting of a DOM attribute), and abort these steps.
The current playback position must be set to the given new playback position.
The seeking DOM attribute must be set to true.
The user agent must fire a simple event called timeupdate at the element.
As soon as the user agent has established whether or not the media data for
the new playback position is available, and, if it is, decoded enough data to
play back that position, the seeking DOM attribute must be set to false.
The seekable attribute must return a static normalised TimeRanges object that
represents the ranges of the media resource, if any, that the user agent is able
to seek to, at the time the attribute is evaluated, notwithstanding the looping
attributes (i.e. the effective start and effective end, etc, don't affect the
seeking attribute).
If the user agent can seek to anywhere in the media resource, e.g. because it a
simple movie file and the user agent and the server support HTTP Range requests,
then the attribute would return an object with one range, whose start is the
time of the first frame (typically zero), and whose end is the same as the time
of the first frame plus the duration attribute's value (which would equal the
time of the last frame).
3.14.9.9. Cue ranges
Media elements have a set of cue ranges. Each cue range is made up of the
following information:
A class name
A group of related ranges can be given the same class name so that they can
all be removed at the same time.
A start time
An end time
The actual time range, using the same timeline as the media resource itself.
A "pause" boolean
A flag indicating whether to pause playback on exit.
An "enter" callback
A callback that is called when the current playback position enters the range.
An "exit" callback
A callback that is called when the current playback position exits the range.
An "active" boolean
A flag indicating whether the range is active or not.
The addCueRange(className, start, end, pauseOnExit, enterCallback, exitCallback)
method must, when called, add a cue range to the media element, that cue range
having the class name className, the start time start (in seconds), the end time
end (in seconds), the "pause" boolean with the same value as pauseOnExit, the
"enter" callback enterCallback, the "exit" callback exitCallback, and an
"active" boolean that is true if the current playback position is equal to or
greater than the start time and less than the end time, and false otherwise.
The removeCueRanges(className) method must, when called, remove all the cue
ranges of the media element which have the class name className.
When the current playback position of a media element changes (e.g. due to
playback or seeking), the user agent must run the following steps. If the
current playback position changes while the steps are running, then the user
agent must wait for the steps to complete, and then must immediately rerun the
steps. (These steps are thus run as often as possible or needed — if one
iteration takes a long time, this can cause certain ranges to be skipped over as
the user agent rushes ahead to "catch up".)
Let current ranges be an ordered list of cue ranges, initialised to contain
all the cue ranges of the media element whose start times are less than or
equal to the current playback position and whose end times are greater than
the current playback position, in the order they were added to the element.
Let other ranges be an ordered list of cue ranges, initialised to contain all
the cue ranges of the media element that are not present in current ranges, in
the order they were added to the element.
If none of the cue ranges in current ranges have their "active" boolean set to
"false" (inactive) and none of the cue ranges in other ranges have their
"active" boolean set to "true" (active), then abort these steps.
If the time was reached through the usual monotonic increase of the current
playback position during normal playback, the user agent must then fire a
simple event called timeupdate at the element. (In the other cases, such as
explicit seeks, relevant events get fired as part of the overall process of
changing the current playback position.)
If the time was reached through the usual monotonic increase of the current
playback position during normal playback, and there are cue ranges in other
ranges that have both their "active" boolean and their "pause" boolean set to
"true", then immediately act as if the element's pause() method had been
invoked. (In the other cases, such as explicit seeks, playback is not paused
by exiting a cue range, even if that cue range has its "pause" boolean set to
"true".)
Invoke all the non-null "exit" callbacks for all of the cue ranges in other
ranges that have their "active" boolean set to "true" (active), in list order.
Invoke all the non-null "enter" callbacks for all of the cue ranges in current
ranges that have their "active" boolean set to "false" (inactive), in list
order.
Set the "active" boolean of all the cue ranges in the current ranges list to
"true" (active), and the "active" boolean of all the cue ranges in the other
ranges list to "false" (inactive).
Invoking a callback (an object implementing the VoidCallback interface) means
calling its handleEvent() method.
interface VoidCallback {
void handleEvent();
};The handleEvent method of objects implementing the VoidCallback interface is the
entrypoint for the callback represented by the object.
In the ECMAScript DOM binding, the ECMAScript native Function type must
implement the VoidCallback interface such that invoking the handleEvent() method
of that interface on the object from another language binding invokes the
function itself. In the ECMAScript binding itself, however, the handleEvent()
method of the interface is not directly accessible on Function objects. Such
functions, when invoked, must be called at the scope of the browsing context.
3.14.9.10. User interface
The controls attribute is a boolean attribute. If the attribute is present, or
if scripting is disabled, then the user agent should expose a user interface to
the user. This user interface should include features to begin playback, pause
playback, seek to an arbitrary position in the content (if the content supports
arbitrary seeking), change the volume, and show the media content in manners
more suitable to the user (e.g. full-screen video or in an independent resizable
window). Other controls may also be made available.
If the attribute is absent, then the user agent should avoid making a user
interface available that could conflict with an author-provided user interface.
User agents may make the following features available, however, even when the
attribute is absent:
User agents may provide controls to affect playback of the media resource (e.g.
play, pause, seeking, and volume controls), but such features should not
interfere with the page's normal rendering. For example, such features could be
exposed in the media element's context menu.
Where possible (specifically, for starting, stopping, pausing, and unpausing
playback, for muting or changing the volume of the audio, and for seeking), user
interface features exposed by the user agent must be implemented in terms of the
DOM API described above, so that, e.g., all the same events fire.
The controls DOM attribute must reflect the content attribute of the same name.
The volume attribute must return the playback volume of any audio portions of
the media element, in the range 0.0 (silent) to 1.0 (loudest). Initially, the
volume must be 0.5, but user agents may remember the last set value across
sessions, on a per-site basis or otherwise, so the volume may start at other
values. On setting, if the new value is in the range 0.0 to 1.0 inclusive, the
attribute must be set to the new value and the playback volume must be
correspondingly adjusted as soon as possible after setting the attribute, with
0.0 being silent, and 1.0 being the loudest setting, values in between
increasing in loudness. The range need not be linear. The loudest setting may be
lower than the system's loudest possible setting; for example the user could
have set a maximum volume. If the new value is outside the range 0.0 to 1.0
inclusive, then, on setting, an INDEX_SIZE_ERR exception must be raised instead.
The muted attribute must return true if the audio channels are muted and false
otherwise. On setting, the attribute must be set to the new value; if the new
value is true, audio playback for this media resource must then be muted, and if
false, audio playback must then be enabled.
Whenever either the muted or volume attributes are changed, after any running
scripts have finished executing, the user agent must fire a simple event called
volumechange at the media element.
3.14.9.11. Time range
Objects implementing the TimeRanges interface represent a list of ranges
(periods) of time.
interface TimeRanges {
readonly attribute unsigned long length;
float start(in unsigned long index);
float end(in unsigned long index);
};The length DOM attribute must return the number of ranges represented by the
object.
The start(index) method must return the position of the start of the indexth
range represented by the object, in seconds measured from the start of the
timeline that the object covers.
The end(index) method must return the position of the end of the indexth range
represented by the object, in seconds measured from the start of the timeline
that the object covers.
These methods must raise INDEX_SIZE_ERR exceptions if called with an index
argument greater than or equal to the number of ranges represented by the
object.
When a TimeRanges object is said to be a normalised TimeRanges object, the
ranges it represents must obey the following criteria:
The start of a range must be greater than the end of all earlier ranges.
The start of a range must be less than the end of that same range.
In other words, the ranges in such an object are ordered, don't overlap, and
don't touch (adjacent ranges are folded into one bigger range).
The timelines used by the objects returned by the buffered, seekable and played
DOM attributes of media elements must be the same as that element's media
resource's timeline.
3.14.9.12. Event summary
The following events fire on media elements as part of the processing model
described above: Event name Interface Dispatched when... Preconditions
begin ProgressEvent [PROGRESS] The user agent begins fetching the media
data, synchronously during the load() method call. networkState equals
LOADING
progress ProgressEvent [PROGRESS] The user agent is fetching media data.
networkState is more than EMPTY and less than LOADED
loadedmetadata Event The user agent is fetching media data, and the media
resource's metadata has just been received. networkState equals
LOADED_METADATA
loadedfirstframe Event The user agent is fetching media data, and the
media resource's first frame has just been received. networkState equals
LOADED_FIRST_FRAME
load ProgressEvent [PROGRESS] The user agent finishes downloading the
entire media resource. networkState equals LOADED
abort ProgressEvent [PROGRESS] The user agent stops fetching the media
data before it is completely downloaded. This can be fired synchronously
during the load() method call. error is an object with the code
MEDIA_ERR_ABORTED. networkState equals either EMPTY or LOADED, depending
on when the download was aborted.
error ProgressEvent [PROGRESS] An error occurs while fetching the media
data. error is an object with the code MEDIA_ERR_NETWORK_ERROR or higher.
networkState equals either EMPTY or LOADED, depending on when the download
was aborted.
emptied Event A media element whose networkState was previously not in the
EMPTY state has just switched to that state (either because of a fatal
error during load that's about to be reported, or because the load()
method was reinvoked, in which case it is fired synchronously during the
load() method call). networkState is EMPTY; all the DOM attributes are in
their initial states.
stalled ProgressEvent The user agent is trying to fetch media data, but
data is unexpectedly not forthcoming.
play Event Playback has begun. Fired after the play method has returned.
paused is newly false.
pause Event Playback has been paused. Fired after the pause method has
returned. paused is newly true.
waiting Event Playback has stopped because the next frame is not
available, but the user agent expects that frame to become available in
due course. readyState is either DATA_UNAVAILABLE or
CAN_SHOW_CURRENT_FRAME, and paused is false. Either seeking is true, or
the current playback position is not contained in any of the ranges in
buffered. It is possible for playback to stop for two other reasons
without paused being false, but those two reasons do not fire this event:
maybe playback ended, or playback stopped due to errors.
timeupdate Event The current playback position changed in an interesting
way, for example discontinuously.
ended Event Playback has stopped because the end of the media resource was
reached. currentTime equals the effective end; ended is true.
dataunavailable Event The user agent cannot render the data at the current
playback position because data for the current frame is not immediately
available. The readyState attribute is newly equal to DATA_UNAVAILABLE.
canshowcurrentframe Event The user agent cannot render the data after the
current playback position because data for the next frame is not
immediately available. The readyState attribute is newly equal to
CAN_SHOW_CURRENT_FRAME.
canplay Event The user agent can resume playback of the media data, but
estimates that if playback were to be started now, the media resource
could not be rendered at the current playback rate up to its end without
having to stop for further buffering of content. The readyState attribute
is newly equal to CAN_PLAY.
canplaythrough Event The user agent estimates that if playback were to be
started now, the media resource could be rendered at the current playback
rate all the way to its end without having to stop for further buffering.
The readyState attribute is newly equal to CAN_PLAY_THROUGH.
ratechange Event Either the defaultPlaybackRate or the playbackRate
attribute has just been updated.
durationchange Event The duration attribute has just been updated.
volumechange Event Either the volume attribute or the muted attribute has
changed. Fired after the relevant attribute's setter has returned.
3.14.9.13. Security and privacy considerations
Talk about making sure interactive media files (e.g. SVG) don't have access to
the container DOM (XSS potential); talk about not exposing any sensitive data
like metadata from tracks in the media files (intranet snooping risk)
3.14.10. The source element
Categories
None.
Contexts in which this element may be used:
As a child of a media element, before any prose content.
Content model:
Empty.
Element-specific attributes:
src
type
media
DOM interface:
interface HTMLSourceElement : HTMLElement {
attribute DOMString src;
attribute DOMString type;
attribute DOMString media;
};The source element allows authors to specify multiple media resources for media
elements.
The src attribute gives the address of the media resource. The value must be a
URI (or IRI). This attribute must be present.
The type attribute gives the type of the media resource, to help the user agent
determine if it can play this media resource before downloading it. Its value
must be a MIME type. The codecs parameter may be specified and might be
necessary to specify exactly how the resource is encoded. [RFC2046] [RFC4281]
The following list shows some examples of how to use the codecs= MIME parameter
in the type attribute.
H.264 Simple baseline profile video (main and extended video compatible) level
3 and Low-Complexity AAC audio in MP4 container