A local date and time consists of a specific proleptic Gregorian date, consisting of a year, a month, and a day, and a time, consisting of an hour, a minute, a second, and a fraction of a second, but expressed without a time zone. [GREGORIAN]
A string is a valid local date and time string representing a date and time if it consists of the following components in the given order:
The rules to parse a local date and time string are as follows. This will return either a date and time, or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that point and returns nothing.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
If position is beyond the end of input or if the character at position is not a U+0054 LATIN CAPITAL LETTER T character (T) then fail. Otherwise, move position forwards one character.
Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Let date be the date with year year, month month, and day day.
Let time be the time with hour hour, minute minute, and second second.
Return date and time.
A global date and time consists of a specific proleptic Gregorian date, consisting of a year, a month, and a day, and a time, consisting of an hour, a minute, a second, and a fraction of a second, expressed with a time-zone offset, consisting of a signed number of hours and minutes. [GREGORIAN]
A string is a valid global date and time string representing a date, time, and a time-zone offset if it consists of the following components in the given order:
This format allows for time-zone offsets from -23:59 to +23:59. In practice, however, the range of offsets of actual time zones is -12:00 to +14:00, and the minutes component of offsets of actual time zones is always either 00, 30, or 45.
The following are some examples of dates written as valid global date and time strings.
0037-12-13T00:00Z"1979-10-14T12:00:00.001-04:00"8592-01-01T02:09+02:09"Several things are notable about these dates:
The best representation of the global date and time string datetime is the valid global date and time string representing datetime with the last character of the string not being a U+005A LATIN CAPITAL LETTER Z character (Z), even if the time zone is UTC, and with a U+002D HYPHEN-MINUS character (-) representing the sign of the time-zone offset when the time zone is UTC.
The rules to parse a global date and time string are as follows. This will return either a time in UTC, with associated time-zone offset information for round tripping or display purposes, or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that point and returns nothing.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
If position is beyond the end of input or if the character at position is not a U+0054 LATIN CAPITAL LETTER T character (T) then fail. Otherwise, move position forwards one character.
Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
If position is beyond the end of input, then fail.
Parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this returns nothing, then fail.
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 time zone.
Let timezone be timezonehours hours and timezoneminutes minutes from UTC.
Return time and timezone.
The rules to parse a time-zone offset component, given an input string and a position, are as follows. This will return either time-zone hours and time-zone minutes, or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that point and returns nothing.
If the character at position is a U+005A LATIN CAPITAL LETTER Z character (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 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.
Otherwise, fail.
Return timezonehours and timezoneminutes.
A week consists of a week-year number and a week number representing a seven-day period starting on a Monday. Each week-year in this calendaring system has either 52 or 53 such seven-day periods, as defined below. The seven-day period starting on the Gregorian date Monday December 29th 1969 (1969-12-29) is defined as week number 1 in week-year 1970. Consecutive weeks are numbered sequentially. The week before the number 1 week in a week-year is the last week in the previous week-year, and vice versa. [GREGORIAN]
A week-year with a number year has 53 weeks if it corresponds to either a year year in the proleptic Gregorian calendar that has a Thursday as its first day (January 1st), or a year year in the proleptic Gregorian calendar that has a Wednesday as its first day (January 1st) and where year is a number divisible by 400, or a number divisible by 4 but not by 100. All other week-years have 52 weeks.
The week number of the last day of a week-year with 53 weeks is 53; the week number of the last day of a week-year with 52 weeks is 52.
The week-year number of a particular day can be different than the number of the year that contains that day in the proleptic Gregorian calendar. The first week in a week-year y is the week that contains the first Thursday of the Gregorian year y.
A string is a valid week string representing a week-year year and week week if it consists of the following components in the given order:
The rules to parse a week string are as follows. This will return either a week-year number and week number, or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that point and 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 at least four characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let that number be the year.
If year is not a number greater than zero, then fail.
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.
If position is beyond the end of input or if the character at position is not a U+0057 LATIN CAPITAL LETTER W character (W), 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 week.
Let maxweek be the week number of the last day of year year.
If week is not a number in the range 1 ≤ week ≤ maxweek, then fail.
If position is not beyond the end of input, then fail.
Return the week-year number year and the week number week.
A string is a valid date or time string if it is also one of the following:
A string is a valid date or time string in content if it consists of zero or more White_Space characters, followed by a valid date or time string, followed by zero or more further White_Space characters.
A string is a valid date string with optional time if it is also one of the following:
A string is a valid date string in content with optional time if it consists of zero or more White_Space characters, followed by a valid date string with optional time, followed by zero or more further White_Space characters.
The rules to parse a date or time string are as follows. The algorithm is invoked with a flag indicating if the in attribute variant or the in content variant is to be used. The algorithm will return either a date, a time, a global date and time, or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that point and returns nothing.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
For the in content variant: skip White_Space characters.
Set start position to the same position as position.
Set the date present and time present flags to true.
Parse a date component to obtain year, month, and day. If this fails, then set the date present flag to false.
If date present is true, and position is not beyond the end of input, and the character at position is a U+0054 LATIN CAPITAL LETTER T character (T), then advance position to the next character in input.
Otherwise, if date present is true, and either position is beyond the end of input or the character at position is not a U+0054 LATIN CAPITAL LETTER T character (T), then set time present to false.
Otherwise, if date present is false, set position back to the same position as start position.
If the time present flag is true, then parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
If the date present and time present flags are both true, but position is beyond the end of input, then fail.
If the date present and time present flags are both true, parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this returns nothing, then fail.
For the in content variant: skip White_Space characters.
If position is not beyond the end of input, then fail.
If the date present flag is true and the time present flag is false, then let date be the date with year year, month month, and day day, and return date.
Otherwise, if the time present flag is true and the date present flag is false, then let time be the time with hour hour, minute minute, and second second, and return time.
Otherwise, 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 being a moment in the UTC time zone; let timezone be timezonehours hours and timezoneminutes minutes from UTC; and return time and timezone.
A simple color consists of three 8-bit numbers in the range 0..255, representing the red, green, and blue components of the color respectively, in the sRGB color space. [SRGB]
A string is a valid simple color if it is exactly seven characters long, and the first character is a U+0023 NUMBER SIGN character (#), and the remaining six characters are all in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F, U+0061 LATIN SMALL LETTER A to U+0066 LATIN SMALL LETTER F, with the first two digits representing the red component, the middle two digits representing the green component, and the last two digits representing the blue component, in hexadecimal.
A string is a valid lowercase simple color if it is a valid simple color and doesn't use any characters in the range U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F.
The rules for parsing simple color values 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 return either a simple color or an error.
Let input be the string being parsed.
If input is not exactly seven characters long, then return an error.
If the first character in input is not a U+0023 NUMBER SIGN character (#), then return an error.
If the last six characters of input are not all in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F, U+0061 LATIN SMALL LETTER A to U+0066 LATIN SMALL LETTER F, then return an error.
Let result be a simple color.
Interpret the second and third characters as a hexadecimal number and let the result be the red component of result.
Interpret the fourth and fifth characters as a hexadecimal number and let the result be the green component of result.
Interpret the sixth and seventh characters as a hexadecimal number and let the result be the blue component of result.
Return result.
The rules for serializing simple color values given a simple color are as given in the following algorithm:
Let result be a string consisting of a single U+0023 NUMBER SIGN character (#).
Convert the red, green, and blue components in turn to two-digit hexadecimal numbers using the digits U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) and U+0061 LATIN SMALL LETTER A to U+0066 LATIN SMALL LETTER F, zero-padding if necessary, and append these numbers to result, in the order red, green, blue.
Return result, which will be a valid lowercase simple color.
Some obsolete legacy attributes parse colors in a more complicated manner, using the rules for parsing a legacy color value, which are 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 return either a simple color or an error.
Let input be the string being parsed.
If input is the empty string, then return an error.
If input is an ASCII
case-insensitive match for the string "transparent", then return an error.
If input is an ASCII case-insensitive match for one of the keywords listed in the SVG color keywords or CSS2 System Colors sections of the CSS3 Color specification, then return the simple color corresponding to that keyword. [CSSCOLOR]
If input is four characters long, and the first character in input is a U+0023 NUMBER SIGN character (#), and the last three characters of input are all in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F, and U+0061 LATIN SMALL LETTER A to U+0066 LATIN SMALL LETTER F, then run these substeps:
Let result be a simple color.
Interpret the second character of input as a hexadecimal digit; let the red component of result be the resulting number multiplied by 17.
Interpret the third character of input as a hexadecimal digit; let the green component of result be the resulting number multiplied by 17.
Interpret the fourth character of input as a hexadecimal digit; let the blue component of result be the resulting number multiplied by 17.
Return result.
Replace any characters in input that
have a Unicode code point greater than U+FFFF (i.e. any characters
that are not in the basic multilingual plane) with the
two-character string "00".
If input is longer than 128 characters, truncate input, leaving only the first 128 characters.
If the first character in input is a U+0023 NUMBER SIGN character (#), remove it.
Replace any character in input that is not in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F, and U+0061 LATIN SMALL LETTER A to U+0066 LATIN SMALL LETTER F with the character U+0030 DIGIT ZERO (0).
While input's length is zero or not a multiple of three, append a U+0030 DIGIT ZERO (0) character to input.
Split input into three strings of equal length, to obtain three components. Let length be the length of those components (one third the length of input).
If length is greater than 8, then remove the leading length-8 characters in each component, and let length be 8.
While length is greater than two and the first character in each component is a U+0030 DIGIT ZERO (0) character, remove that character and reduce length by one.
If length is still greater than two, truncate each component, leaving only the first two characters in each.
Let result be a simple color.
Interpret the first component as a hexadecimal number; let the red component of result be the resulting number.
Interpret the second component as a hexadecimal number; let the green component of result be the resulting number.
Interpret the third component as a hexadecimal number; let the blue component of result be the resulting number.
Return result.
The 2D graphics context has a separate color syntax that also handles opacity.
A set of space-separated tokens is a string containing 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.
Sets of space-separated tokens sometimes have a defined set of allowed values. When a set of allowed values is defined, the tokens must all be from that list of allowed values; other values are non-conforming. If no such set of allowed values is provided, then all values are conforming.
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.
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.
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, abort these steps.
If the character at position is a space character:
Append the character at position to the end of output.
Advance 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.
A set of comma-separated tokens is a string containing zero or more tokens each separated from the next by a single U+002C COMMA character (,), where tokens consist of any string of zero or more characters, neither beginning nor ending with space characters, nor containing any U+002C COMMA characters (,), and optionally surrounded by space characters.
For instance, the string " a ,b,,d d " consists of four
tokens: "a", "b", the empty string, and "d d". Leading and
trailing whitespace around each token doesn't count as part of the
token, and the empty string can be a token.
Sets of comma-separated tokens sometimes have further restrictions on what consists a valid token. When such restrictions are defined, the tokens must all fit within those restrictions; other values are non-conforming. If no such restrictions are specified, then all values are conforming.
When a user agent has to split a string on commas, 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.
Token: If position is past the end of input, jump to the last step.
Collect a sequence of characters that are not U+002C COMMA characters (,). Let s be the resulting sequence (which might be the empty string).
Remove any leading or trailing sequence of space characters from s.
Add s to tokens.
If position is not past the end of input, then the character at position is a U+002C COMMA character (,); advance position past that character.
Jump back to the step labeled token.
Return tokens.
A valid hash-name 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 name attribute of an element with type
type in the document.
The rules for parsing a hash-name 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 attribute whose value
is a case-sensitive match for s or
a name attribute whose value is a
compatibility caseless match for s.
A string is a valid media query if it matches the
media_query_list production of the Media
Queries specification. [MQ]
A string matches the environment of a view if it is the empty string, a string consisting of only space characters, or is a media query that matches that view's environment according to the definitions given in the Media Queries specification. [MQ]
A URL is a string used to identify a resource.
A URL is a valid URL if it is a valid Web address as defined by the Web addresses specification. [WEBADDRESSES]
A URL is a valid non-empty URL if it is a valid URL but it is not the empty string.
A URL is an absolute URL if it is an absolute Web address as defined by the Web addresses specification. [WEBADDRESSES]
To parse a URL url into its component parts, the user agent must use the parse a Web address algorithm defined by the Web addresses specification. [WEBADDRESSES]
Parsing a URL results in the following components, again as defined by the Web addresses specification:
To resolve a URL to an absolute URL relative to either another absolute URL or an element, the user agent must use the resolve a Web address algorithm defined by the Web addresses specification. [WEBADDRESSES]
The document base URL of a Document
object is the absolute URL obtained by running these
substeps:
Let fallback base url be the document's address.
If fallback base url is
about:blank, and the Document's
browsing context has a creator browsing
context, then let fallback base url
be the document base URL of the creator
Document instead.
If there is no base element that is both a
child of the head element and has an
href attribute, then the
document base URL is fallback base
url.
Otherwise, let url be the value of the
href attribute of the first
such element.
Resolve url relative to fallback base
url (thus, the base href attribute isn't affected by
xml:base attributes).
The document base URL is the result of the previous step if it was successful; otherwise it is fallback base url.
This specification defines the URL
about:legacy-compat as a reserved, though
unresolvable, about: URI, for use in DOCTYPEs in HTML
documents when needed for compatibility with XML tools. [ABOUT]
This specification defines the URL
about:srcdoc as a reserved, though
unresolvable, about: URI, that is used as
the document's address of iframe srcdoc documents. [ABOUT]
The term "URL" in this specification is used in a manner distinct from the precise technical meaning it is given in RFC 3986. Readers familiar with that RFC will find it easier to read this specification if they pretend the term "URL" as used herein is really called something else altogether. This is a willful violation of RFC 3986. [RFC3986]
When an xml:base attribute
changes, the attribute's element, and all descendant elements, are
affected by a base URL change.
When a document's document base URL changes, all elements in that document are affected by a base URL change.
When an element is moved from one document to another, if the two documents have different base URLs, then that element and all its descendants are affected by a base URL change.
When an element is affected by a base URL change, it must act as described in the following list:
If the absolute URL identified by the hyperlink is
being shown to the user, or if any data derived from that URL is
affecting the display, then the href attribute should be re-resolved relative to the element
and the UI updated appropriately.
For example, the CSS :link/:visited pseudo-classes might have
been affected.
If the hyperlink has a ping attribute and its absolute URL(s) are being shown to the
user, then the ping
attribute's tokens should be re-resolved relative to the element and the UI updated
appropriately.
q, blockquote,
section, article, ins, or
del element with a cite
attributeIf the absolute URL identified by the cite attribute is being shown to the user, or if
any data derived from that URL is affecting the display, then the
URL should be re-resolved relative to the element and the UI updated
appropriately.
The element is not directly affected.
Changing the base URL doesn't affect the image
displayed by img elements, although subsequent
accesses of the src IDL attribute
from script will return a new absolute URL that might
no longer correspond to the image being shown.
An interface that has a complement of URL decomposition IDL attributes will have seven attributes with the following definitions:
attribute DOMString protocol;
attribute DOMString host;
attribute DOMString hostname;
attribute DOMString port;
attribute DOMString pathname;
attribute DOMString search;
attribute DOMString hash;
protocol [ = value ]Returns the current scheme of the underlying URL.
Can be set, to change the underlying URL's scheme.
host [ = value ]Returns the current host and port (if it's not the default port) in the underlying URL.
Can be set, to change the underlying URL's host and port.
The host and the port are separated by a colon. The port part, if omitted, will be assumed to be the current scheme's default port.
hostname [ = value ]Returns the current host in the underlying URL.
Can be set, to change the underlying URL's host.
port [ = value ]Returns the current port in the underlying URL.
Can be set, to change the underlying URL's port.
pathname [ = value ]Returns the current path in the underlying URL.
Can be set, to change the underlying URL's path.
search [ = value ]Returns the current query component in the underlying URL.
Can be set, to change the underlying URL's query component.
hash [ = value ]Returns the current fragment identifier in the underlying URL.
Can be set, to change the underlying URL's fragment identifier.
The attributes defined to be URL decomposition IDL attributes must act as described for the attributes with the same corresponding names in this section.
In addition, an interface with a complement of URL decomposition IDL attributes will define an input, which is a URL that the attributes act on, and a common setter action, which is a set of steps invoked when any of the attributes' setters are invoked.
The seven URL decomposition IDL attributes have similar requirements.
On getting, if the input is an absolute URL that fulfills the condition given in the "getter condition" column corresponding to the attribute in the table below, the user agent must return the part of the input URL given in the "component" column, with any prefixes specified in the "prefix" column appropriately added to the start of the string and any suffixes specified in the "suffix" column appropriately added to the end of the string. Otherwise, the attribute must return the empty string.
On setting, the new value must first be mutated as described by the "setter preprocessor" column, then mutated by %-escaping any characters in the new value that are not valid in the relevant component as given by the "component" column. Then, if the input is an absolute URL and the resulting new value fulfills the condition given in the "setter condition" column, the user agent must make a new string output by replacing the component of the URL given by the "component" column in the input URL with the new value; otherwise, the user agent must let output be equal to the input. Finally, the user agent must invoke the common setter action with the value of output.
When replacing a component in the URL, if the component is part of an optional group in the URL syntax consisting of a character followed by the component, the component (including its prefix character) must be included even if the new value is the empty string.
The previous paragraph applies in particular to the
":" before a <port> component, the "?" before a <query> component, and the "#" before a <fragment> component.
For the purposes of the above definitions, URLs must be parsed using the URL parsing rules defined in this specification.
| Attribute | Component | Getter Condition | Prefix | Suffix | Setter Preprocessor | Setter Condition |
|---|---|---|---|---|---|---|
protocol
| <scheme> | — | — | U+003A COLON (:) | Remove all trailing U+003A COLON characters (:) | The new value is not the empty string |
host
| <hostport> | input is hierarchical and uses a server-based naming authority | — | — | — | The new value is not the empty string and input is hierarchical and uses a server-based naming authority |
hostname
| <host> | input is hierarchical and uses a server-based naming authority | — | — | Remove all leading U+002F SOLIDUS characters (/) | The new value is not the empty string and input is hierarchical and uses a server-based naming authority |
port
| <port> | input is hierarchical, uses a server-based naming authority, and contained a <port> component (possibly an empty one) | — | — | Remove all characters in the new value from the first that is not in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), if any. Remove any leading U+0030 DIGIT ZERO characters (0) in the new value. If the resulting string is empty, set it to a single U+0030 DIGIT ZERO character (0). | input is hierarchical and uses a server-based naming authority, and the new value, when interpretted as a base-ten integer, is less than or equal to 65535 |
pathname
| <path> | input is hierarchical | — | — | If it has no leading U+002F SOLIDUS character (/), prepend a U+002F SOLIDUS character (/) to the new value | input is hierarchical |
search
| <query> | input is hierarchical, and contained a <query> component (possibly an empty one) | U+003F QUESTION MARK (?) | — | Remove one leading U+003F QUESTION MARK character (?), if any | input is hierarchical |
hash
| <fragment> | input contained a non-empty <fragment> component | U+0023 NUMBER SIGN (#) | — | Remove one leading U+0023 NUMBER SIGN character (#), if any | — |
The table below demonstrates how the getter condition for search results in different results
depending on the exact original syntax of the URL:
| Input URL | search value
| Explanation |
|---|---|---|
http://example.com/
| empty string | No <query> component in input URL. |
http://example.com/?
| ?
| There is a <query> component, but it is empty. The question mark in the resulting value is the prefix. |
http://example.com/?test
| ?test
| The <query> component has the value "test".
|
http://example.com/?test#
| ?test
| The (empty) <fragment> component is not part of the <query> component. |
When a user agent is to fetch a resource or URL, optionally from an origin origin, and optionally with a synchronous flag, the following steps must be run. (When a URL is to be fetched, the URL identifies a resource to be obtained.)
Generate the address of the resource from which Request-URIs
are obtained as required by HTTP for the Referer (sic) header from the
document's current address of the appropriate
Document as given by the following list. [HTTP]
Document.Remove any <fragment> component from the generated address of the resource from which Request-URIs are obtained.
If the origin of the appropriate
Document is not a scheme/host/port tuple, then the
Referer (sic) header must be
omitted, regardless of its value.
If the algorithm was not invoked with the synchronous flag, perform the remaining steps asynchronously.
If the resource is identified by an absolute URL,
and the resource is to be obtained using an idempotent action
(such as an HTTP GET or
equivalent), and it is already being downloaded for other
reasons (e.g. another invocation of this algorithm), and this
request would be identical to the previous one (e.g. same Accept and Origin headers), and the user agent is
configured such that it is to reuse the data from the existing
download instead of initiating a new one, then use the results of
the existing download instead of starting a new one.
Otherwise, at a time convenient to the user and the user agent,
download (or otherwise obtain) the resource, applying the
semantics of the relevant specifications (e.g. performing an HTTP
GET or POST operation, or reading the file from disk, following
redirects, dereferencing javascript:
URLs, etc).
The HTTP specification requires that 301, 302, and 307 redirects, when applied to methods other than the safe methods, not be followed without user confirmation. [HTTP]
For the purposes of the Referer (sic) header, use the
address of the resource from which Request-URIs are
obtained generated in the earlier step.
For the purposes of the Origin
header, if the fetching algorithm was
explicitly initiated from an origin, then the origin that initiated the HTTP request is origin. Otherwise, this is a request from
a "privacy-sensitive" context. [ORIGIN]
If the resource is identified by the URL
about:blank, then the resource is
immediately available and consists of the empty string, with no
metadata.
If there are cookies to be set, then the user agent must run the following substeps:
Wait until ownership of the storage mutex can be taken by this instance of the fetching algorithm.
Take ownership of the storage mutex.
Update the cookies. [COOKIES]
Release the storage mutex so that it is once again free.
If the algorithm was not invoked with the synchronous flag: When the resource is available, or if there is an error of some description, queue a task that uses the resource as appropriate. If the resource can be processed incrementally, as, for instance, with a progressively interlaced JPEG or an HTML file, additional tasks may be queued to process the data as it is downloaded. The task source for these tasks is the networking task source.
Otherwise, return the resource or error information to the calling algorithm.
If the user agent can determine the actual length of the resource
being fetched for an instance of this
algorithm, and if that length is finite, then that length is the
file's size. Otherwise, the
subject of the algorithm (that is, the resource being fetched) has
no known size. (For
example, the HTTP Content-Length header might
provide this information.)
The user agent must also keep track of the number of bytes downloaded for each instance of this algorithm. This number must exclude any out-of-band metadata, such as HTTP headers.
The application cache processing model introduces some changes to the networking model to handle the returning of cached resources.
The navigation processing model handles redirects itself, overriding the redirection handling that would be done by the fetching algorithm.
Whether the type sniffing rules apply to the fetched resource depends on the algorithm that invokes the rules — they are not always applicable.
User agents can implement a variety of transfer protocols, but this specification mostly defines behavior in terms of HTTP. [HTTP]
The HTTP GET method is equivalent to the default retrieval action of the protocol. For example, RETR in FTP. Such actions are idempotent and safe, in HTTP terms.
The HTTP response codes are equivalent to statuses in other protocols that have the same basic meanings. For example, a "file not found" error is equivalent to a 404 code, a server error is equivalent to a 5xx code, and so on.
The HTTP headers are equivalent to fields in other protocols that have the same basic meaning. For example, the HTTP authentication headers are equivalent to the authentication aspects of the FTP protocol.
Anything in this specification that refers to HTTP also applies
to HTTP-over-TLS, as represented by URLs
representing the https scheme.
User agents should report certificate errors to the user and must either refuse to download resources sent with erroneous certificates or must act as if such resources were in fact served with no encryption.
User agents should warn the user that there is a potential problem whenever the user visits a page that the user has previously visited, if the page uses less secure encryption on the second visit.
Not doing so can result in users not noticing man-in-the-middle attacks.
If a user connects to a server with a self-signed certificate, the user agent could allow the connection but just act as if there had been no encryption. If the user agent instead allowed the user to override the problem and then displayed the page as if it was fully and safely encrypted, the user could be easily tricked into accepting man-in-the-middle connections.
If a user connects to a server with full encryption, but the page then refers to an external resource that has an expired certificate, then the user agent will act as if the resource was unavailable, possibly also reporting the problem to the user. If the user agent instead allowed the resource to be used, then an attacker could just look for "secure" sites that used resources from a different host and only apply man-in-the-middle attacks to that host, for example taking over scripts in the page.
If a user bookmarks a site that uses a CA-signed certificate, and then later revisits that site directly but the site has started using a self-signed certificate, the user agent could warn the user that a man-in-the-middle attack is likely underway, instead of simply acting as if the page was not encrypted.
The Content-Type metadata of a resource must be obtained and interpreted in a manner consistent with the requirements of the Content-Type Processing Model specification. [MIMESNIFF]
The algorithm for extracting an encoding from a Content-Type, given a string s, is given in the Content-Type Processing Model specification. It either returns an encoding or nothing. [MIMESNIFF]
The above is out of date now that the relevant section has been removed from MIMESNIFF. Stay tuned; I'll bring it back here soon.
The sniffed type of a resource must be found in a manner consistent with the requirements given in the Content-Type Processing Model specification for finding the sniffed-type of the relevant sequence of octets. [MIMESNIFF]
The rules for sniffing images specifically and the rules for distingushing if a resource is text or binary are also defined in the Content-Type Processing Model specification. Both sets of rules return a MIME type as their result. [MIMESNIFF]
It is imperative that the rules in the Content-Type Processing Model specification be followed exactly. When a user agent uses different heuristics for content type detection than the server expects, security problems can occur. For more details, see the Content-Type Processing Model specification. [MIMESNIFF]
Some IDL attributes are defined to reflect a particular content attribute. This means that on getting, the IDL attribute returns the current value of the content attribute, and on setting, the IDL attribute changes the value of the content attribute to the given value.
In general, on getting, if the content attribute is not present, the IDL attribute must act as if the content attribute's value is the empty string; and on setting, if the content attribute is not present, it must first be added.
If a reflecting IDL attribute is a DOMString
attribute whose content attribute is defined to contain a
URL, then on getting, the IDL attribute must resolve the value of the content
attribute relative to the element and return the resulting
absolute URL if that was successful, or the empty
string otherwise; and on setting, must set the content attribute to
the specified literal value. If the content attribute is absent, the
IDL attribute must return the default value, if the content
attribute has one, or else the empty string.
If a reflecting IDL attribute is a DOMString
attribute whose content attribute is defined to contain one or more
URLs, then on getting, the IDL attribute
must split the content
attribute on spaces and return the concatenation of resolving each token URL to an
absolute URL relative to the element, with a single
U+0020 SPACE character between each URL, ignoring any tokens that
did not resolve successfully. If the content attribute is absent,
the IDL attribute must return the default value, if the content
attribute has one, or else the empty string. On setting, the IDL
attribute must set the content attribute to the specified literal
value.
If a reflecting IDL attribute is a DOMString whose
content attribute is an enumerated attribute, and the
IDL attribute is limited to only known values, then, on
getting, the IDL attribute must return the conforming value
associated with the state the attribute is in (in its canonical
case), or the empty string if the attribute is in a state that has
no associated keyword value; and on setting, if the new value is an
ASCII case-insensitive match for one of the keywords
given for that attribute, then the content attribute must be set to
the conforming value associated with the state that the attribute
would be in if set to the given new value, otherwise, if the new
value is the empty string, then the content attribute must be
removed, otherwise, the setter must raise a SYNTAX_ERR
exception.
If a reflecting IDL attribute is a DOMString but
doesn't fall into any of the above categories, then the getting and
setting must be done in a transparent, case-preserving manner.
If a reflecting IDL attribute is a boolean
attribute, then on getting the IDL attribute must return true if the
content attribute is set, and false if it is absent. On setting, the
content attribute must be removed if the IDL attribute is set to
false, and must be set to have the same value as its name if the IDL
attribute is set to true. (This corresponds to the rules for boolean content attributes.)
If a reflecting IDL attribute is a signed integer type
(long) then, on getting, the content attribute must be
parsed according to the rules for parsing signed integers, and if that is
successful, and the value is in the range of the IDL attribute's
type, the resulting value must be returned. If, on the other hand,
it fails or returns an out of range value, or if the attribute is
absent, then the default value must be returned instead, or 0 if
there is no default value. On setting, the given value must be
converted to the shortest possible string representing the number as
a valid integer and then that string must be used as
the new content attribute value.
If a reflecting IDL attribute is a signed integer type
(long) that is limited to only non-negative
numbers then, on getting, the content attribute must be parsed
according to the rules for parsing non-negative
integers, and if that is successful, and the value is in the
range of the IDL attribute's type, the resulting value must be
returned. If, on the other hand, it fails or returns an out of range
value, or if the attribute is absent, the default value must be
returned instead, or −1 if there is no default value. On
setting, if the value is negative, the user agent must fire an
INDEX_SIZE_ERR exception. Otherwise, the given value
must be converted to the shortest possible string representing the
number as a valid non-negative integer and then that
string must be used as the new content attribute value.
If a reflecting IDL attribute is an unsigned integer
type (unsigned long) then, on getting, the content
attribute must be parsed according to the rules for parsing
non-negative integers, and if that is successful, and the
value is in the range of the IDL attribute's type, the resulting
value must be returned. If, on the other hand, it fails or returns
an out of range value, or if the attribute is absent, the default
value must be returned instead, or 0 if there is no default
value. On setting, the given value must be converted to the shortest
possible string representing the number as a valid
non-negative integer and then that string must be used as the
new content attribute value.
If a reflecting IDL attribute is an unsigned integer type
(unsigned long) that is limited to only
non-negative numbers greater than zero, then the behavior is
similar to the previous case, but zero is not allowed. On getting,
the content attribute must first be parsed according to the
rules for parsing non-negative integers, and if that is
successful, and the value is in the range of the IDL attribute's
type, the resulting value must be returned. If, on the other hand,
it fails or returns an out of range value, or if the attribute is
absent, the default value must be returned instead, or 1 if there is
no default value. On setting, if the value is zero, the user agent
must fire an INDEX_SIZE_ERR exception. Otherwise, the
given value must be converted to the shortest possible string
representing the number as a valid non-negative integer
and then that string must be used as the new content attribute
value.
If a reflecting IDL attribute is a floating point number type
(float), then, on getting, the content attribute must
be parsed according to the rules for parsing floating point
number values, and if that is successful, the resulting value
must be returned. If, on the other hand, it fails, or if the
attribute is absent, the default value must be returned instead, or
0.0 if there is no default value. On setting, the given value must
be converted to the best representation of the number as a
floating point number and then that string must be used as
the new content attribute value.
The values Infinity and Not-a-Number (NaN) values throw an exception on setting, as defined earlier.
If a reflecting IDL attribute is of the type
DOMTokenList or DOMSettableTokenList, then
on getting it must return a DOMTokenList or
DOMSettableTokenList object (as appropriate) whose
underlying string is the element's corresponding content
attribute. When the object mutates its underlying string, the
content attribute must itself be immediately mutated. When the
attribute is absent, then the string represented by the object is
the empty string; when the object mutates this empty string, the
user agent must add the corresponding content attribute, with its
value set to the value it would have been set to after mutating the
empty string. The same DOMTokenList or
DOMSettableTokenList object must be returned every time
for each attribute.
If an element with no attributes has its element.classList.remove()
method invoked, the underlying string won't be changed, since the
result of removing any token from the empty string is still the
empty string. However, if the element.classList.add() method is
then invoked, a class attribute
will be added to the element with the value of the token to be
added.
If a reflecting IDL attribute has the type
HTMLElement, or an interface that descends from
HTMLElement, then, on getting, it must run the
following algorithm (stopping at the first point where a value is
returned):
document.getElementById() method
would find when called on the content attribute's document if it
was passed as its argument the current value of the corresponding
content attribute.On setting, if the given element has an id attribute, then the content attribute must
be set to the value of that id
attribute. Otherwise, the IDL attribute must be set to the empty
string.
The HTMLCollection, HTMLAllCollection,
HTMLFormControlsCollection,
HTMLOptionsCollection, and
HTMLPropertiesCollection interfaces represent various
lists of DOM nodes. Collectively, objects implementing these
interfaces are called collections.
When a collection is created, a filter and a root are associated with the collection.
For example, when the HTMLCollection
object for the document.images attribute is
created, it is associated with a filter that selects only
img elements, and rooted at the root of the
document.
The collection then represents a live view of the subtree rooted at the collection's root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.
The rows list is
not in tree order.
An attribute that returns a collection must return the same object every time it is retrieved.
The HTMLCollection interface represents a generic
collection of elements.
interface HTMLCollection {
readonly attribute unsigned long length;
caller getter object item(in unsigned long index); // only returns Element
caller getter object namedItem(in DOMString name); // only returns Element
};
lengthReturns the number of elements in the collection.
item(index)Returns the item with index index from the collection. The items are sorted in tree order.
Returns null if index is out of range.
namedItem(name)Returns the first item with ID or name name from the collection.
Returns null if no element with that ID or name could be found.
Only a, applet, area,
embed, form, frame,
frameset, iframe, img, and
object elements can have a name for the purpose of
this method; their name is given by the value of their name attribute.
The object's indices of the supported indexed properties are the numbers in the range zero to one less than the number of nodes represented by the collection. If there are no such elements, then there are no supported indexed properties.
The length
attribute must return the number of nodes represented by the
collection.
The item(index) method must return the indexth node in the collection. If there is no indexth node in the collection, then the method must
return null.
The names of the supported named properties consist
of the values of the name attributes of each
a, applet, area,
embed, form, frame,
frameset, iframe, img, and
object element represented by the
collection with a name attribute, plus
the list of IDs that the elements represented by the
collection have.
The namedItem(key) method must return the first node
in the collection that matches the following requirements:
a, applet,
area, embed, form,
frame, frameset, iframe,
img, or object element with a name attribute equal to key,
or,If no such elements are found, then the method must return null.
The HTMLAllCollection interface represents a generic
collection of elements just like
HTMLCollection, with the exception that its namedItem() method
returns an HTMLCollection object when there are
multiple matching elements.
interface HTMLAllCollection : HTMLCollection {
// inherits length and item()
caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
HTMLAllCollection tags(in DOMString tagName);
};
lengthReturns the number of elements in the collection.
item(index)Returns the item with index index from the collection. The items are sorted in tree order.
Returns null if index is out of range.
namedItem(name)namedItem(name)Returns the item with ID or name name from the collection.
If there are multiple matching items, then an HTMLAllCollection object containing all those elements is returned.
Returns null if no element with that ID or name could be found.
Only a, applet, area,
embed, form, frame,
frameset, iframe, img, and
object elements can have a name for the purpose of
this method; their name is given by the value of their name attribute.
tags(tagName)Returns a collection that is a filtered view of the current collection, containing only elements with the given tag name.
The object's indices of the supported indexed
properties and names of the supported named
properties are as defined for HTMLCollection
objects.
The namedItem(key) method must act according to the
following algorithm:
Let collection be an
HTMLAllCollection object rooted at the same node as
the HTMLAllCollection object on which the method was
invoked, whose filter matches only only elements that already
match the filter of the HTMLAllCollection object on
which the method was invoked and that are either:
The tags(tagName) method must return an
HTMLAllCollection rooted at the same node as the
HTMLAllCollection object on which the method was
invoked, whose filter matches only HTML elements whose
local name is the tagName argument and that
already match the filter of the HTMLAllCollection
object on which the method was invoked. In HTML
documents, the argument must first be converted to
ASCII lowercase.
The HTMLFormControlsCollection interface represents
a collection of listed elements in form
and fieldset elements.
interface HTMLFormControlsCollection : HTMLCollection {
// inherits length and item()
caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
};
interface RadioNodeList : NodeList {
attribute DOMString value;
};
lengthReturns the number of elements in the collection.
item(index)Returns the item with index index from the collection. The items are sorted in tree order.
Returns null if index is out of range.
namedItem(name)namedItem(name)Returns the item with ID or name name from the collection.
If there are multiple matching items, then a RadioNodeList object containing all those elements is returned.
Returns null if no element with that ID or name could be found.
Returns the value of the first checked radio button represented by the object.
Can be set, to check the first radio button with the given value represented by the object.
The object's indices of the supported indexed
properties are as defined for HTMLCollection
objects.
The names of the supported named properties consist
of the values of all the id and name attributes of all the elements
represented by the collection.
The namedItem(name) method must act according to the
following algorithm:
id attribute or a name attribute equal to name, then return that node and stop the
algorithm.id attribute or a name attribute equal to name, then return null and stop the algorithm.RadioNodeList object
representing a live view of the
HTMLFormControlsCollection object, further filtered so
that the only nodes in the RadioNodeList object are
those that have either an id attribute
or a name attribute equal to name. The nodes in the RadioNodeList
object must be sorted in tree order.RadioNodeList object.Members of the RadioNodeList interface inherited
from the NodeList interface must behave as they would
on a NodeList object.
The value
IDL attribute on the RadioNodeList object, on getting,
must return the value returned by running the following steps:
Let element be the first element in
tree order represented by the
RadioNodeList object that is an input
element whose type attribute
is in the Radio Button
state and whose checkedness
is true. Otherwise, let it be null.
If element is null, or if it is an
element with no value
attribute, return the empty string.
Otherwise, return the value of element's
value attribute.
On setting, the value IDL attribute must run
the following steps:
Let element be the first element in
tree order represented by the
RadioNodeList object that is an input
element whose type attribute
is in the Radio Button
state and whose value content
attribute is present and equal to the new value, if any. Otherwise,
let it be null.
If element is not null, then set its checkedness to true.
The HTMLOptionsCollection interface represents a
list of option elements. It is always rooted on a
select element and has attributes and methods that
manipulate that element's descendants.
interface HTMLOptionsCollection : HTMLCollection {
// inherits item()
attribute unsigned long length; // overrides inherited length
caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
void add(in HTMLElement element, in optional HTMLElement before);
void add(in HTMLElement element, in long before);
void remove(in long index);
};
length [ = value ]Returns the number of elements in the collection.
When set to a smaller number, truncates the number of option elements in the corresponding container.
When set to a greater number, adds new blank option elements to that container.
item(index)Returns the item with index index from the collection. The items are sorted in tree order.
Returns null if index is out of range.
namedItem(name)namedItem(name)Returns the item with ID or name name from the collection.
If there are multiple matching items, then a NodeList object containing all those elements is returned.
Returns null if no element with that ID could be found.
add(element [, before ] )Inserts element before the node given by before.
The before argument can be a number, in which case element is inserted before the item with that number, or an element from the collection, in which case element is inserted before that element.
If before is omitted, null, or a number out of range, then element will be added at the end of the list.
This method will throw a HIERARCHY_REQUEST_ERR
exception if element is an ancestor of the
element into which it is to be inserted. If element is not an option or
optgroup element, then the method does nothing.
The object's indices of the supported indexed
properties are as defined for HTMLCollection
objects.
On getting, the length
attribute must return the number of nodes represented by the
collection.
On setting, the behavior depends on whether the new value is
equal to, greater than, or less than the number of nodes
represented by the collection at that time. If the
number is the same, then setting the attribute must do nothing. If
the new value is greater, then n new
option elements with no attributes and no child nodes
must be appended to the select element on which the
HTMLOptionsCollection is rooted, where n is the difference between the two numbers (new
value minus old value). Mutation events must be fired as if a
DocumentFragment containing the new option
elements had been inserted. If the new value is lower, then the
last n nodes in the collection must be removed
from their parent nodes, where n is the
difference between the two numbers (old value minus new value).
Setting length never removes
or adds any optgroup elements, and never adds new
children to existing optgroup elements (though it can
remove children from them).
The names of the supported named properties consist
of the values of all the id and name attributes of all the elements
represented by the collection.
The namedItem(name) method must act according to the
following algorithm:
id attribute or a name attribute equal to name, then return that node and stop the
algorithm.id attribute or a name attribute equal to name, then return null and stop the algorithm.NodeList object
representing a live view of the
HTMLOptionsCollection object, further filtered so that
the only nodes in the NodeList object are those that
have either an id attribute or a name attribute equal to name. The nodes in the NodeList object
must be sorted in tree order.NodeList object.The add(element, before)
method must act according to the following algorithm:
If element is not an option
or optgroup element, then return and abort these
steps.
If element is an ancestor of the
select element on which the
HTMLOptionsCollection is rooted, then throw a
HIERARCHY_REQUEST_ERR exception.
If before is an element, but that
element isn't a descendant of the select element on
which the HTMLOptionsCollection is rooted, then throw
a NOT_FOUND_ERR exception.
If element and before are the same element, then return and abort these steps.
If before is a node, then let reference be that node. Otherwise, if before is an integer, and there is a beforeth node in the collection, let reference be that node. Otherwise, let reference be null.
If reference is not null, let parent be the parent node of reference. Otherwise, let parent
be the select element on which the
HTMLOptionsCollection is rooted.
Act as if the DOM Core insertBefore() method was
invoked on the parent node, with element as the first argument and reference as the second argument.
The remove(index) method must act according to
the following algorithm:
If the number of nodes represented by the collection is zero, abort these steps.
If index is not a number greater than or equal to 0 and less than the number of nodes represented by the collection, let element be the first element in the collection. Otherwise, let element be the indexth element in the collection.
Remove element from its parent node.
The HTMLPropertiesCollection interface represents a
collection of elements that add
name-value pairs to a particular item in the microdata
model.
interface HTMLPropertiesCollection : HTMLCollection {
// inherits length and item()
caller getter PropertyNodeList namedItem(in DOMString name); // overrides inherited namedItem()
readonly attribute DOMStringList names;
};
typedef sequence<any> PropertyValueArray;
interface PropertyNodeList : NodeList {
readonly attribute PropertyValueArray values;
};
lengthReturns the number of elements in the collection.
item(index)Returns the element with index index from the collection. The items are sorted in tree order.
Returns null if index is out of range.
namedItem(name)Returns a PropertyNodeList object containing any elements that add a property named name.
namesReturns a DOMStringList with the property names of the elements in the collection.
valuesReturns an array of the various values that the relevant elements have.
The object's indices of the supported indexed
properties are as defined for HTMLCollection
objects.
The names of the supported named properties consist of the property names of all the elements represented by the collection.
The names
attribute must return a live DOMStringList
object giving the property names of all the elements
represented by the collection, listed in tree
order, but with duplicates removed, leaving only the first
occurrence of each name. The same object must be returned each
time.
The namedItem(name) method must return a
PropertyNodeList object representing a
live view of the HTMLPropertiesCollection
object, further filtered so that the only nodes in the
PropertyNodeList object are those that have a property name equal to name. The nodes in the PropertyNodeList
object must be sorted in tree order, and the same
object must be returned each time a particular name is queried.
Members of the PropertyNodeList interface inherited
from the NodeList interface must behave as they would
on a NodeList object.
The values
IDL attribute on the PropertyNodeList object, on
getting, must return a newly constructed array whose values are the
values obtained from the itemValue DOM property of each of the
elements represented by the object, in tree order.
The DOMTokenList interface represents an interface
to an underlying string that consists of a set of
space-separated tokens.
DOMTokenList objects are always
case-sensitive, even when the underlying string might
ordinarily be treated in a case-insensitive manner.
interface DOMTokenList {
readonly attribute unsigned long length;
getter DOMString item(in unsigned long index);
boolean contains(in DOMString token);
void add(in DOMString token);
void remove(in DOMString token);
boolean toggle(in DOMString token);
stringifier DOMString ();
};
lengthReturns the number of tokens in the string.
item(index)Returns the token with index index. The tokens are returned in the order they are found in the underlying string.
Returns null if index is out of range.
contains(token)Returns true if the token is present; false otherwise.
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
add(token)Adds token, unless it is already present.
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
remove(token)Removes token if it is present.
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
toggle(token)Adds token if it is not present, or removes it if it is. Returns true if token is now present (it was added); returns false if it is not (it was removed).
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
The length
attribute must return the number of tokens that result from splitting the underlying string on
spaces. This is the length.
The object's indices of the supported indexed properties are the numbers in the range zero to length-1, unless the length is zero, in which case there are no supported indexed properties.
The item(index) method must split the underlying string on spaces,
preserving the order of the tokens as found in the underlying
string, and then return the indexth item in this
list. If index is equal to or greater than the
number of tokens, then the method must return null.
For example, if the string is "a b
a c" then there are four tokens: the token with index 0 is
"a", the token with index 1 is "b", the token with index 2 is "a", and the token with index 3 is "c".
The contains(token) method must run the following
algorithm:
SYNTAX_ERR exception and stop the
algorithm.INVALID_CHARACTER_ERR exception and stop the
algorithm.The add(token) method must run the following
algorithm:
SYNTAX_ERR exception and stop the
algorithm.INVALID_CHARACTER_ERR exception and stop the
algorithm.DOMTokenList object's underlying string then stop the
algorithm.DOMTokenList object's underlying
string is not the empty string and the last character of that
string is not a space character, then append a U+0020
SPACE character to the end of that string.DOMTokenList object's underlying string.The remove(token) method must run the following
algorithm:
SYNTAX_ERR exception and stop the
algorithm.INVALID_CHARACTER_ERR exception and stop the
algorithm.The toggle(token) method must run the following
algorithm:
SYNTAX_ERR exception and stop the
algorithm.INVALID_CHARACTER_ERR exception and stop the
algorithm.DOMTokenList object's underlying string then remove the given token from the underlying string and stop the
algorithm, returning false.DOMTokenList object's underlying
string is not the empty string and the last character of that
string is not a space character, then append a U+0020
SPACE character to the end of that string.DOMTokenList object's underlying string.Objects implementing the DOMTokenList interface must
stringify to the object's
underlying string representation.
The DOMSettableTokenList interface is the same as the
DOMTokenList interface, except that it allows the
underlying string to be directly changed.
interface DOMSettableTokenList : DOMTokenList {
attribute DOMString value;
};
valueReturns the underlying string.
Can be set, to change the underlying string.
An object implementing the DOMSettableTokenList
interface must act as defined for the DOMTokenList
interface, except for the value attribute defined
here.
The value
attribute must return the underlying string on getting, and must
replace the underlying string with the new value on setting.
When a user agent is required to obtain a structured clone of an object, it must run the following algorithm, which either returns a separate object, or throws an exception.
Let input be the object being cloned.
Let memory be a list of objects, initially empty. (This is used to catch cycles.)
Let output be the object resulting from calling the internal structured cloning algorithm with input and memory.
Return output.
The internal structured cloning algorithm is always called with two arguments, input and memory, and its behavior depends on the type of input, as follows:
Return the undefined value.
Return the null value.
Return the false value.
Return the true value.
Return a newly constructed Number object with the same value as input.
Return a newly constructed String object with the same value as input.
Date objectReturn a newly constructed Date object with the same value as input.
RegExp objectReturn a newly constructed RegExp object with the same pattern and flags as input.
The value of the lastIndex property is not copied.
ImageData objectReturn a newly constructed ImageData object
with the same width and
height as input, and with a newly constructed
CanvasPixelArray for its data attribute, with the same
length and pixel
values as the input's.
File objectReturn a newly constructed File object corresponding to the same underlying data.
Blob objectReturn a newly constructed Blob object corresponding to the same underlying data.
FileList objectReturn a newly constructed FileList object containing a list of newly constructed File objects corresponding to the same underlying data as those in input, maintaining their relative order.
Return the null value.
If input is in memory, then throw a
NOT_SUPPORTED_ERR exception and abort the overall
structured clone algorithm.
Otherwise, let new memory be a list consisting of the items in memory with the addition of input.
Create a new object, output, of the same type as input: either an Array or an Object.
For each enumerable property in input, add a corresponding property to output having the same name, and having a value created from invoking the internal structured cloning algorithm recursively with the value of the property as the "input" argument and new memory as the "memory" argument. The order of the properties in the input and output objects must be the same.
This does not walk the prototype chain.
Return output.
Error)Return the null value.
The DOMStringMap interface represents a set of
name-value pairs. It exposes these using the scripting language's
native mechanisms for property access.
When a DOMStringMap object is instantiated, it is
associated with three algorithms, one for getting the list of
name-value pairs, one for setting names to certain values, and one
for deleting names.
interface DOMStringMap {
getter DOMString (in DOMString name);
setter void (in DOMString name, in DOMString value);
creator void (in DOMString name, in DOMString value);
deleter void (in DOMString name);
};
The names of the supported named properties on a
DOMStringMap object at any instant are the names of
each pair returned from the algorithm for getting the list of
name-value pairs at that instant.
When a DOMStringMap object is indexed to retrieve a
named property name, the value returned must be
the value component of the name-value pair whose name component is
name in the list returned by the algorithm for
getting the list of name-value pairs.
When a DOMStringMap object is indexed to create or
modify a named property name with value value, the algorithm for setting names to certain
values must be run, passing name as the name and
the result of converting value to a
DOMString as the value.
When a DOMStringMap object is indexed to delete a
named property named name, the algorithm for
deleting names must be run, passing name as the
name.
The DOMStringMap interface definition
here is only intended for JavaScript environments. Other language
bindings will need to define how DOMStringMap is to be
implemented for those languages.
The dataset attribute on
elements exposes the data-*
attributes on the element.
Given the following fragment and elements with similar constructions:
<img class="tower" id="tower5" data-x="12" data-y="5"
data-ai="robotarget" data-hp="46" data-ability="flames"
src="towers/rocket.png alt="Rocket Tower">
...one could imagine a function splashDamage() that takes some arguments, the first
of which is the element to process:
function splashDamage(node, x, y, damage) {
if (node.classList.contains('tower') && // checking the 'class' attribute
node.dataset.x == x && // reading the 'data-x' attribute
node.dataset.y == y) { // reading the 'data-y' attribute
var hp = parseInt(node.dataset.hp); // reading the 'data-hp' attribute
hp = hp - damage;
if (hp < 0) {
hp = 0;
node.dataset.ai = 'dead'; // setting the 'data-ai' attribute
delete node.dataset.ability; // removing the 'data-ability' attribute
}
node.dataset.hp = hp; // setting the 'data-hp' attribute
}
}
DOM3 Core defines mechanisms for checking for interface support, and for obtaining implementations of interfaces, using feature strings. [DOMCORE]
Authors are strongly discouraged from using these, as they are notoriously unreliable and imprecise. Authors are encouraged to rely on explicit feature testing or the graceful degradation behavior intrinsic to some of the features in this specification.
For historical reasons, user agents should return the true value
when the hasFeature(feature, version)
method of the DOMImplementation interface is invoked
with feature set to either "HTML" or "XHTML" and version set to either "1.0" or
"2.0".
The following are DOMException codes. [DOMCORE]
INDEX_SIZE_ERRDOMSTRING_SIZE_ERRHIERARCHY_REQUEST_ERRWRONG_DOCUMENT_ERRINVALID_CHARACTER_ERRNO_DATA_ALLOWED_ERRNO_MODIFICATION_ALLOWED_ERRNOT_FOUND_ERRNOT_SUPPORTED_ERRINUSE_ATTRIBUTE_ERRINVALID_STATE_ERRSYNTAX_ERRINVALID_MODIFICATION_ERRNAMESPACE_ERRINVALID_ACCESS_ERRVALIDATION_ERRTYPE_MISMATCH_ERRSECURITY_ERRNETWORK_ERRABORT_ERRURL_MISMATCH_ERRQUOTA_EXCEEDED_ERRPARSE_ERRSERIALIZE_ERRThere is an implied strong reference from any IDL attribute that returns a pre-existing object to that object.
The HTML namespace is: http://www.w3.org/1999/xhtml
The MathML namespace is: http://www.w3.org/1998/Math/MathML
The SVG namespace is: http://www.w3.org/2000/svg
The XLink namespace is: http://www.w3.org/1999/xlink
The XML namespace is: http://www.w3.org/XML/1998/namespace
The XMLNS namespace is: http://www.w3.org/2000/xmlns/
Data mining tools and other user agents that perform operations on content without running scripts, evaluating CSS or XPath expressions, or otherwise exposing the resulting DOM to arbitrary content, may "support namespaces" by just asserting that their DOM node analogues are in certain namespaces, without actually exposing the above strings.
Every XML and HTML document in an HTML UA is represented by a
Document object. [DOMCORE]
The document's address is an absolute URL
that is set when the Document is created. The
document's current address is an absolute URL
that can change during the lifetime of the Document,
for example when the user navigates to
a fragment identifier on the
page or when the pushState() method is called
with a new URL. The document's
current address must be set to the document's
address when the Document is created.
Interactive user agents typically expose the document's current address in their user interface.
When a Document is created by a script using the createDocument()
or createHTMLDocument()
APIs, the document's address is the same as the
document's address of the script's document.
Document objects are assumed to be XML
documents unless they are flagged as being HTML
documents when they are created. Whether a document is an
HTML document or an XML document affects the behavior of
certain APIs and the case-sensitivity of some selectors.
All Document objects (in user agents implementing
this specification) must also implement
the HTMLDocument interface, available using
binding-specific methods. (This is the case whether or not the
document in question is an HTML
document or indeed whether it contains any HTML
elements at all.) Document objects must also implement the document-level interface
of any other namespaces that the UA supports.
For example, if an HTML implementation also
supports SVG, then the Document object implements both
HTMLDocument and SVGDocument.
Because the HTMLDocument interface is
now obtained using binding-specific casting methods instead of
simply being the primary interface of the document object, it is no
longer defined as inheriting from Document.
[OverrideBuiltins]
interface HTMLDocument {
// resource metadata management
[PutForwards=href] readonly attribute Location location;
readonly attribute DOMString URL;
attribute DOMString domain;
readonly attribute DOMString referrer;
attribute DOMString cookie;
readonly attribute DOMString lastModified;
readonly attribute DOMString compatMode;
attribute DOMString charset;
readonly attribute DOMString characterSet;
readonly attribute DOMString defaultCharset;
readonly attribute DOMString readyState;
// DOM tree accessors
getter any (in DOMString name);
attribute DOMString title;
attribute DOMString dir;
attribute HTMLElement body;
readonly attribute HTMLHeadElement head;
readonly attribute HTMLCollection images;
readonly attribute HTMLCollection embeds;
readonly attribute HTMLCollection plugins;
readonly attribute HTMLCollection links;
readonly attribute HTMLCollection forms;
readonly attribute HTMLCollection scripts;
NodeList getElementsByName(in DOMString elementName);
NodeList getElementsByClassName(in DOMString classNames);
NodeList getItems(in optional DOMString typeNames); // microdata
// dynamic markup insertion
attribute DOMString innerHTML;
HTMLDocument open(in optional DOMString type, in optional DOMString replace);
WindowProxy open(in DOMString url, in DOMString name, in DOMString features, in optional boolean replace);
void close();
void write(in DOMString... text);
void writeln(in DOMString... text);
// user interaction
Selection getSelection();
readonly attribute Element activeElement;
boolean hasFocus();
attribute DOMString designMode;
boolean execCommand(in DOMString commandId);
boolean execCommand(in DOMString commandId, in boolean showUI);
boolean execCommand(in DOMString commandId, in boolean showUI, in DOMString value);
boolean queryCommandEnabled(in DOMString commandId);
boolean queryCommandIndeterm(in DOMString commandId);
boolean queryCommandState(in DOMString commandId);
boolean queryCommandSupported(in DOMString commandId);
DOMString queryCommandValue(in DOMString commandId);
readonly attribute HTMLCollection commands;
// event handler IDL attributes
attribute Function onabort;
attribute Function onblur;
attribute Function oncanplay;
attribute Function oncanplaythrough;
attribute Function onchange;
attribute Function onclick;
attribute Function oncontextmenu;
attribute Function ondblclick;
attribute Function ondrag;
attribute Function ondragend;
attribute Function ondragenter;
attribute Function ondragleave;
attribute Function ondragover;
attribute Function ondragstart;
attribute Function ondrop;
attribute Function ondurationchange;
attribute Function onemptied;
attribute Function onended;
attribute Function onerror;
attribute Function onfocus;
attribute Function onformchange;
attribute Function onforminput;
attribute Function oninput;
attribute Function oninvalid;
attribute Function onkeydown;
attribute Function onkeypress;
attribute Function onkeyup;
attribute Function onload;
attribute Function onloadeddata;
attribute Function onloadedmetadata;
attribute Function onloadstart;
attribute Function onmousedown;
attribute Function onmousemove;
attribute Function onmouseout;
attribute Function onmouseover;
attribute Function onmouseup;
attribute Function onmousewheel;
attribute Function onpause;
attribute Function onplay;
attribute Function onplaying;
attribute Function onprogress;
attribute Function onratechange;
attribute Function onreadystatechange;
attribute Function onscroll;
attribute Function onseeked;
attribute Function onseeking;
attribute Function onselect;
attribute Function onshow;
attribute Function onstalled;
attribute Function onsubmit;
attribute Function onsuspend;
attribute Function ontimeupdate;
attribute Function onvolumechange;
attribute Function onwaiting;
};
Document implements HTMLDocument;
Since the HTMLDocument interface holds methods and
attributes related to a number of disparate features, the members of
this interface are described in various different sections.
User agents must raise a
SECURITY_ERR exception whenever any of the members of
an HTMLDocument object are accessed by scripts whose
effective script origin is not the same as the Document's effective
script origin.
URLReturns the document's address.
referrerReturns the
address of the Document from which the user
navigated to this one, unless it was blocked or there was no such
document, in which case it returns the empty string.
The noreferrer link
type can be used to block the referrer.
The URL
attribute must return the document's address.
The referrer attribute
must return either the current address of the active document
of the source browsing context at the time the
navigation was started (that is, the page which navigated the browsing context
to the current document), with any <fragment> component removed; or
the empty string if there is no such originating page, or if the UA
has been configured not to report referrers in this case, or if the
navigation was initiated for a hyperlink with a noreferrer keyword.
In the case of HTTP, the referrer IDL attribute will
match the Referer (sic) header
that was sent when fetching the current
page.
Typically user agents are configured to not report
referrers in the case where the referrer uses an encrypted protocol
and the current page does not (e.g. when navigating from an https: page to an http:
page).
cookie [ = value ]Returns the HTTP cookies that apply to the
Document. If there are no cookies or cookies can't be
applied to this resource, the empty string will be returned.
Can be set, to add a new cookie to the element's set of HTTP cookies.
If the contents are sandboxed into a unique origin (in an
iframe with the sandbox attribute) or the
resource was labeled as text/html-sandboxed, a
SECURITY_ERR exception will be thrown on getting and
setting.
The cookie
attribute represents the cookies of the resource from which the
Document was created.
Some Document objects are cookie-free Document
objects. Any Document object created by the createDocument() or createHTMLDocument()
factory methods is a cookie-free Document
object. Any Document whose address does not use a server-based
naming authority is a cookie-free Document
object. Other specifications can also define
Document objects as being cookie-free Document
objects.
On getting, if the document is a
cookie-free Document object, then the user
agent must return the empty string. Otherwise, if the
Document's origin is not a
scheme/host/port tuple, the user agent must raise a
SECURITY_ERR exception. Otherwise, the user agent must
first obtain the storage mutex and then return the
cookie-string for the document's address for a
"non-HTTP" API. [COOKIES]
On setting, if the document is a cookie-free
Document object, then the user agent must do
nothing. Otherwise, if the Document's
origin is not a scheme/host/port tuple, the user agent
must raise a SECURITY_ERR exception. Otherwise, the
user agent must obtain the storage mutex and then act
as it would when receiving a set-cookie-string for
the document's address via a "non-HTTP" API, consisting
of the new value. [COOKIES]
Since the cookie attribute is accessible
across frames, the path restrictions on cookies are only a tool to
help manage which cookies are sent to which parts of the site, and
are not in any way a security feature.
lastModifiedReturns the date of the last modification to the document, as
reported by the server, in the form "MM/DD/YYYY hh:mm:ss", in the user's local
time zone.
If the last modification date is not known, the current time is returned instead.
The lastModified
attribute, on getting, must return the date and time of the
Document's source file's last modification, in the
user's local time zone, in the following format:
All the numeric components above, other than the year, must be given as two digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) representing the number in base ten, zero-padded if necessary. The year must be given as the shortest possible string of four or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) representing the number in base ten, zero-padded if necessary.
The Document's source file's last modification date
and time must be derived from relevant features of the networking
protocols used, e.g. from the value of the HTTP Last-Modified header of the
document, or from metadata in the file system for local files. If
the last modification date and time are not known, the attribute
must return the current date and time in the above format.
compatModeIn a conforming document, returns the string "CSS1Compat". (In quirks mode
documents, returns the string "BackCompat",
but a conforming document can never trigger quirks
mode.)
A Document is always set to one of three modes:
no-quirks mode, the default; quirks mode, used
typically for legacy documents; and limited-quirks mode,
also known as "almost standards" mode. The mode is only ever changed
from the default by the HTML parser, based on the
presence, absence, or value of the DOCTYPE string.
The compatMode IDL
attribute must return the literal string "CSS1Compat" unless the document has been set to
quirks mode by the HTML parser, in which
case it must instead return the literal string "BackCompat".
charset [ = value ]Returns the document's character encoding.
Can be set, to dynamically change the document's character encoding.
New values that are not IANA-registered aliases supported by the user agent are ignored.
characterSetReturns the document's character encoding.
defaultCharsetReturns what might be the user agent's default character encoding. (The user agent might return another character encoding altogether, e.g. to protect the user's privacy, or if the user agent doesn't use a single default encoding.)
Documents have an associated character encoding. When a Document
object is created, the document's character encoding
must be initialized to UTF-16. Various algorithms during page
loading affect this value, as does the charset setter. [IANACHARSET]
The charset
IDL attribute must, on getting, return the preferred MIME
name of the document's character encoding. On
setting, if the new value is an IANA-registered alias for a
character encoding supported by the user agent, the document's
character encoding must be set to that character
encoding. (Otherwise, nothing happens.)
The characterSet
IDL attribute must, on getting, return the preferred MIME
name of the document's character encoding.
The defaultCharset
IDL attribute must, on getting, return the preferred MIME
name of a character encoding, possibly the user's default
encoding, or an encoding associated with the user's current
geographical location, or any arbitrary encoding name.
readyStateReturns "loading" while the Document is loading, and "complete" once it has loaded.
The readystatechange event fires on the Document object when this value changes.
Each document has a current document readiness. When a
Document object is created, it must have its
current document readiness set to the string "loading"
if the document is associated with an HTML parser or an
XML parser, or to the string "complete"
otherwise. Various algorithms during page loading affect this
value. When the value is set, the user agent must fire a
simple event named readystatechange at the
Document object.
A Document is said to have an active
parser if it is associated with an HTML parser or
an XML parser that has not yet been stopped or aborted.
The readyState IDL
attribute must, on getting, return the current document
readiness.
The html element of a document is the
document's root element, if there is one and it's an
html element, or null otherwise.
headReturns the head element.
The head element of a document is the
first head element that is a child of the
html element, if there is one, or null
otherwise.
The head
attribute, on getting, must return the head
element of the document (a head element or
null).
title [ = value ]Returns the document's title, as given by the
title element.
Can be set, to update the document's title. If there is no
head element,
the new value is ignored.
In SVG documents, the SVGDocument interface's
title attribute takes
precedence.
The title element of a document is the
first title element in the document (in tree order), if
there is one, or null otherwise.
The title attribute must,
on getting, run the following algorithm:
If the root element is an svg
element in the "http://www.w3.org/2000/svg"
namespace, and the user agent supports SVG, then return the value
that would have been returned by the IDL attribute of the same name
on the SVGDocument interface. [SVG]
Otherwise, let value be a concatenation
of the data of all the child text
nodes of the title element, in
tree order, or the empty string if the
title element is null.
Replace any sequence of one or more consecutive space characters in value with a single U+0020 SPACE character.
Remove any leading or trailing space characters in value.
Return value.
On setting, the following algorithm must be run. Mutation events must be fired as appropriate.
If the root element is an svg
element in the "http://www.w3.org/2000/svg"
namespace, and the user agent supports SVG, then the setter must
defer to the setter for the IDL attribute of the same name on the
SVGDocument interface (if it is readonly, then this
will raise an exception). Stop the algorithm here. [SVG]
title element is null and
the head element is null, then the
attribute must do nothing. Stop the algorithm here.title element is null, then a
new title element must be created and appended to
the head element. Let element be that element. Otherwise, let element be the title
element.Text node whose data is the new value
being assigned must be appended to element.The title attribute on
the HTMLDocument interface should shadow the attribute
of the same name on the SVGDocument interface when the
user agent supports both HTML and SVG. [SVG]
body [ = value ]Returns the body element.
Can be set, to replace the body element.
If the new value is not a body or frameset element, this will throw a HIERARCHY_REQUEST_ERR exception.
The body element of a document is the first child of
the html element that is either a
body element or a frameset element. If
there is no such element, it is null. If the body
element is null, then when the specification requires that events be
fired at "the body element", they must instead be fired at the
Document object.
The body
attribute, on getting, must return the body element of
the document (either a body element, a
frameset element, or null). On setting, the following
algorithm must be run:
body or
frameset element, then raise a
HIERARCHY_REQUEST_ERR exception and abort these
steps.replaceChild() method had been
called with the new value and the
incumbent body element as its two arguments respectively,
then abort these steps.imagesReturns an HTMLCollection of the img elements in the Document.
embedspluginsReturn an HTMLCollection of the embed elements in the Document.
linksReturns an HTMLCollection of the a and area elements in the Document that have href attributes.
formsReturn an HTMLCollection of the form elements in the Document.
scriptsReturn an HTMLCollection of the script elements in the Document.
The images
attribute must return an HTMLCollection rooted at the
Document node, whose filter matches only
img elements.
The embeds
attribute must return an HTMLCollection rooted at the
Document node, whose filter matches only
embed elements.
The plugins
attribute must return the same object as that returned by the embeds attribute.
The links
attribute must return an HTMLCollection rooted at the
Document node, whose filter matches only a
elements with href
attributes and area elements with href attributes.
The forms
attribute must return an HTMLCollection rooted at the
Document node, whose filter matches only
form elements.
The scripts
attribute must return an HTMLCollection rooted at the
Document node, whose filter matches only
script elements.
getElementsByName(name)Returns a NodeList of elements in the
Document that have a name
attribute with the value name.
getElementsByClassName(classes)getElementsByClassName(classes)Returns a NodeList of the elements in the object
on which the method was invoked (a Document or an
Element) that have all the classes given by classes.
The classes argument is interpreted as a space-separated list of classes.
The getElementsByName(name) method takes a string name, and must return a live
NodeList containing all the HTML elements
in that document that have a name attribute
whose value is equal to the name argument (in a
case-sensitive manner), in tree order.
When the method is invoked on a Document object again
with the same argument, the user agent may return the same as the
object returned by the earlier call. In other cases, a new
NodeList object must be returned.
The getElementsByClassName(classNames) method takes a string that
contains a set of space-separated tokens representing
classes. When called, the method must return a live
NodeList object containing all the elements in the
document, in tree order, that have all the classes
specified in that argument, having obtained the classes by splitting a string on
spaces. (Duplicates are ignored.) If there are no tokens
specified in the argument, then the method must return an empty
NodeList. If the document is in quirks
mode, then the comparisons for the classes must be done in an
ASCII case-insensitive manner, otherwise, the
comparisons must be done in a case-sensitive manner.
When the method is invoked on a Document object again
with the same argument, the user agent may return the same object as
the object returned by the earlier call. In other cases, a new
NodeList object must be returned.
The getElementsByClassName(classNames) method on the
HTMLElement interface must return a live
NodeList with the nodes that the
HTMLDocument getElementsByClassName()
method would return when passed the same argument(s), excluding any
elements that are not descendants of the HTMLElement
object on which the method was invoked.
When the method is invoked on an HTMLElement object
again with the same argument, the user agent may return the same
object as the object returned by the earlier call. In other cases, a
new NodeList object must be returned.
HTML, SVG, and MathML elements define which classes they are in
by having an attribute with no namespace with the name class containing a space-separated list of classes
to which the element belongs. Other specifications may also allow
elements in their namespaces to be labeled as being in specific
classes.
Given the following XHTML fragment:
<div id="example"> <p id="p1" class="aaa bbb"/> <p id="p2" class="aaa ccc"/> <p id="p3" class="bbb ccc"/> </div>
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 HTMLDocument interface supports named properties. The names
of the supported named properties at any moment consist of
the values of the name content
attributes of all the applet, embed,
form, iframe, img, and
fallback-free object elements in the
Document that have name
content attributes, and the values of the id content attributes of all the
applet and fallback-free
object elements in the Document that have
id content attributes, and the values
of the id content attributes of all the
img elements in the Document that have
both name content attributes and
id content attributes.
When the
HTMLDocument object is indexed for property
retrieval using a name name, then the user
agent must return the value obtained using the following steps:
Let elements be the list of named elements with
the name name in the Document.
There will be at least one such element, by definition.
If elements has only one element, and that
element is an iframe element, then return the
WindowProxy object of the nested browsing
context represented by that iframe element,
and abort these steps.
Otherwise, if elements has only one element, return that element and abort these steps.
Otherwise return an HTMLCollection rooted at the
Document node, whose filter matches only named elements with
the name name.
Named elements with the name name, for the purposes of the above algorithm, are those that are either:
applet, embed, form,
iframe, img, or
fallback-free object elements that have a
name content attribute whose value
is name, orapplet or fallback-free
object elements that have an id content attribute whose value is name, orimg elements that have an id content attribute whose value is name, and that have a name content attribute present also.An object element is said to be
fallback-free if it has no object or
embed descendants.
The dir
attribute on the HTMLDocument interface is defined
along with the dir content
attribute.
XML documents can be created from script using the
createDocument()
method on the DOMImplementation interface.
HTML documents can be created using the createHTMLDocument()
method:
[Supplemental, NoInterfaceObject]
interface DOMHTMLImplementation {
Document createHTMLDocument(in DOMString title);
};
DOMImplementation implements DOMHTMLImplementation;
implementation . createHTMLDocument( title )Returns a new Document, with a basic DOM already
constructed with an appropriate title element.
The createHTMLDocument(title) method, when invoked, must run the
following steps:
Let doc be a newly created
Document object.
Mark doc as being an HTML document.
Create a DocumentType node with the name attribute set to the string "html", and the other attributes specific to
DocumentType objects set to the empty string, null,
and empty lists, as appropriate. Append the newly created node to
doc.
Create an html element, and append it to doc.
Create a head element, and append it to the
html element created in the previous step.
Create a title element, and append it to the
head element created in the previous step.
Create a Text node, and set its data attribute to the string given by the method's
argument (which could be the empty string). Append it to the
title element created in the previous step.
Create a body element, and append it to the
html element created in the earlier step.
Return doc.
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 not use elements, attributes, or attribute values for purposes other than their appropriate intended semantic purpose. Authors must not use elements, attributes, or attribute values that are not permitted by this specification or other applicable specifications.
For example, the following document is non-conforming, despite being syntactically correct:
<!DOCTYPE HTML>
<html lang="en-GB">
<head> <title> Demonstration </title> </head>
<body>
<table>
<tr> <td> My favourite animal is the cat. </td> </tr>
<tr>
<td>
—<a href="http://example.org/~ernest/"><cite>Ernest</cite></a>,
in an essay from 1992
</td>
</tr>
</table>
</body>
</html>
...because the data placed in the cells is clearly not tabular
data (and the cite element mis-used). A corrected
version of this document might be:
<!DOCTYPE HTML> <html lang="en-GB"> <head> <title> Demonstration </title> </head> <body> <blockquote> <p> My favourite animal is the cat. </p> </blockquote> <p> —<a href="http://example.org/~ernest/">Ernest</a>, in an essay from 1992 </p> </body> </html>
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).
<body> <h1>ABC Company</h1> <h2>Leading the way in widget design since 1432</h2> ...
The hgroup element is intended for these kinds of
situations:
<body> <hgroup> <h1>ABC Company</h1> <h2>Leading the way in widget design since 1432</h2> </hgroup> ...
In the next example, there is a non-conforming attribute value ("carpet") and a non-conforming attribute ("texture"), which is not permitted by this specification:
<label>Carpet: <input type="carpet" name="c" texture="deep pile"></label>
Here would be an alternative and correct way to mark this up:
<label>Carpet: <input type="text" class="carpet" name="c" data-texture="deep pile"></label>
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.
The nodes representing HTML elements in the DOM must implement, and expose to scripts, the interfaces listed for them in the relevant sections of this specification. This includes HTML elements in XML documents, even when those documents are in another context (e.g. inside an XSLT transform).
Elements in the DOM represent things; that is, they have intrinsic meaning, also known as semantics.
For example, an ol element
represents an ordered list.
The basic interface, from which all the HTML
elements' interfaces inherit, and which
must be used by elements that have no additional
requirements, is the HTMLElement interface.
interface HTMLElement : Element {
// DOM tree accessors
NodeList getElementsByClassName(in DOMString classNames);
// dynamic markup insertion
attribute DOMString innerHTML;
attribute DOMString outerHTML;
void insertAdjacentHTML(in DOMString position, in DOMString text);
// metadata attributes
attribute DOMString id;
attribute DOMString title;
attribute DOMString lang;
attribute DOMString dir;
attribute DOMString className;
readonly attribute DOMTokenList classList;
readonly attribute DOMStringMap dataset;
// microdata
attribute boolean itemScope;
attribute DOMString itemType;
attribute DOMString itemId;
[PutForwards=value] readonly attribute DOMSettableTokenList itemRef;
[PutForwards=value] readonly attribute DOMSettableTokenList itemProp;
readonly attribute HTMLPropertiesCollection properties;
attribute any itemValue;
// user interaction
attribute boolean hidden;
void click();
void scrollIntoView();
void scrollIntoView(in boolean top);
attribute long tabIndex;
void focus();
void blur();
attribute DOMString accessKey;
readonly attribute DOMString accessKeyLabel;
attribute boolean draggable;
attribute DOMString contentEditable;
readonly attribute boolean isContentEditable;
attribute HTMLMenuElement contextMenu;
attribute DOMString spellcheck;
// command API
readonly attribute DOMString commandType;
readonly attribute DOMString label;
readonly attribute DOMString icon;
readonly attribute boolean disabled;
readonly attribute boolean checked;
// styling
readonly attribute CSSStyleDeclaration style;
// event handler IDL attributes
attribute Function onabort;
attribute Function onblur;
attribute Function oncanplay;
attribute Function oncanplaythrough;
attribute Function onchange;
attribute Function onclick;
attribute Function oncontextmenu;
attribute Function ondblclick;
attribute Function ondrag;
attribute Function ondragend;
attribute Function ondragenter;
attribute Function ondragleave;
attribute Function ondragover;
attribute Function ondragstart;
attribute Function ondrop;
attribute Function ondurationchange;
attribute Function onemptied;
attribute Function onended;
attribute Function onerror;
attribute Function onfocus;
attribute Function onformchange;
attribute Function onforminput;
attribute Function oninput;
attribute Function oninvalid;
attribute Function onkeydown;
attribute Function onkeypress;
attribute Function onkeyup;
attribute Function onload;
attribute Function onloadeddata;
attribute Function onloadedmetadata;
attribute Function onloadstart;
attribute Function onmousedown;
attribute Function onmousemove;
attribute Function onmouseout;
attribute Function onmouseover;
attribute Function onmouseup;
attribute Function onmousewheel;
attribute Function onpause;
attribute Function onplay;
attribute Function onplaying;
attribute Function onprogress;
attribute Function onratechange;
attribute Function onreadystatechange;
attribute Function onscroll;
attribute Function onseeked;
attribute Function onseeking;
attribute Function onselect;
attribute Function onshow;
attribute Function onstalled;
attribute Function onsubmit;
attribute Function onsuspend;
attribute Function ontimeupdate;
attribute Function onvolumechange;
attribute Function onwaiting;
};
interface HTMLUnknownElement : HTMLElement { };
The HTMLElement interface holds methods and
attributes related to a number of disparate features, and the
members of this interface are therefore described in various
different sections of this specification.
The HTMLUnknownElement interface must be used for
HTML elements that are not defined by this
specification (or other applicable specifications).
The following attributes are common to and may be specified on all HTML elements (even those not defined in this specification):
accesskeyclasscontenteditablecontextmenudirdraggablehiddeniditemiditempropitemrefitemscopeitemtypelangspellcheckstyletabindextitleThe following event handler content attributes may be specified on any HTML element:
onabortonblur*oncanplayoncanplaythroughonchangeonclickoncontextmenuondblclickondragondragendondragenterondragleaveondragoverondragstartondropondurationchangeonemptiedonendedonerror*onfocus*onformchangeonforminputoninputoninvalidonkeydownonkeypressonkeyuponload*onloadeddataonloadedmetadataonloadstartonmousedownonmousemoveonmouseoutonmouseoveronmouseuponmousewheelonpauseonplayonplayingonprogressonratechangeonreadystatechangeonscrollonseekedonseekingonselectonshowonstalledonsubmitonsuspendontimeupdateonvolumechangeonwaitingThe attributes marked with an asterisk have a
different meaning when specified on body elements as
those elements expose event handlers of the
Window object with the same names.
While these attributes apply to all elements, they
are not useful on all elements. For example, only media elements will ever receive a volumechange event fired by
the user agent.
Custom data attributes
(e.g. data-foldername or data-msgid) can be specified on any HTML element, to store custom data
specific to the page.
In HTML documents, elements in the HTML
namespace 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 no
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 no
namespace specified.
To enable assistive technology products to expose a more
fine-grained interface than is otherwise possible with HTML elements
and attributes, a set of annotations for assistive technology
products can be specified (the ARIA role and aria-* attributes).
id attributeThe id attribute specifies its
element's unique identifier (ID). The
value must be unique amongst all the IDs in the element's home
subtree and must contain at least one character. The value
must not contain any space
characters.
An element's unique identifier can be used for a variety of purposes, most notably as a way to link to specific parts of a document using fragment identifiers, as a way to target an element when scripting, and as a way to style a specific element from CSS.
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 element's
home subtree (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.
title attributeThe 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.
Caution is advised with respect to the use of newlines in title attributes.
For instance, the following snippet actually defines an abbreviation's expansion with a line break in it:
<p>My logs show that there was some interest in <abbr title="Hypertext Transport Protocol">HTTP</abbr> today.</p>
Some elements, such as link, abbr, and
input, define additional semantics for the title attribute beyond the semantics
described above.
lang and xml:lang attributesThe lang attribute (in
no namespace) 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 BCP 47 language code, or the empty
string. Setting the attribute to the empty string indicates that the
primary language is unknown. [BCP47]
The lang
attribute in the XML namespace is defined in XML. [XML]
If these attributes are omitted from an element, then the language of this element is the same as the language of its parent element, if any.
The lang attribute in no namespace
may be used on any HTML
element.
The lang
attribute in the XML namespace may be used on
HTML elements in XML documents, as well as
elements in other namespaces if the relevant specifications allow it
(in particular, MathML and SVG allow lang attributes in the
XML namespace to be specified on their
elements). If both the lang attribute
in no namespace and the lang attribute in the XML
namespace are specified on the same element, they must
have exactly the same value when compared in an ASCII
case-insensitive manner.
Authors must not use the lang attribute in the XML
namespace on HTML elements in HTML
documents. To ease migration to and from XHTML, authors may
specify an attribute in no namespace with no prefix and with the
literal localname "xml:lang" on HTML
elements in HTML documents, but such attributes
must only be specified if a lang
attribute in no namespace is also specified, and both attributes
must have the same value when compared in an ASCII
case-insensitive manner.
The attribute in no namespace with no prefix and
with the literal localname "xml:lang" has no
effect on language processing.
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 a lang attribute in the
XML namespace set or is an HTML element and has a lang in no namespace attribute set. That
attribute specifies the language of the node.
If both the lang attribute in no
namespace and the lang attribute in the XML
namespace are set on an element, user agents must use
the lang attribute
in the XML namespace, and the lang attribute in no namespace must be
ignored for the purposes of determining
the element's language.
If no explicit language is given for any ancestors of the node, including the root element, but there is a pragma-set default language set, then that is the language of the node.
If there is no pragma-set default language, 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, and in cases where the higher-level protocol reports multiple languages, the language of the node is unknown (the empty string).
If the resulting value is not a recognized language code, then it must be treated as an unknown language having the given language code, distinct from all other languages. For the purposes of round-tripping or communicating with other services that expect language codes, user agents should pass unknown language codes through unmodified.
Thus, for instance, an element with lang="xyzzy" would be matched by the selector :lang(xyzzy) (e.g. in CSS), but it would not be
matched by :lang(abcde), even though both are
equally invalid. Similarly, if a Web browser and screen reader
working in unison communicated about the language of the element,
the browser would tell the screen reader that the language was
"xyzzy", even if it knew it was invalid, just in case the screen
reader actually supported a language with that code after all.
User agents may use the element's language to determine proper processing or rendering (e.g. in the selection of appropriate fonts or pronunciations, or for dictionary selection).
The lang IDL attribute
must reflect the lang
content attribute in no namespace.