A URL is a string used to identify a resource.
A URL is a valid URL if at least one of the following conditions holds:
The URL is a valid IRI reference and it has no query component. [RFC3987]
The URL is a valid IRI reference and its query component contains no unescaped non-ASCII characters. [RFC3987]
The URL is a valid IRI reference and the character encoding of
the URL's Document
is UTF-8 or UTF-16. [RFC3987]
A string is a valid non-empty URL if it is a valid URL but it is not the empty string.
A string is a valid URL potentially surrounded by spaces if, after stripping leading and trailing whitespace from it, it is a valid URL.
A string is a valid non-empty URL potentially surrounded by spaces if, after stripping leading and trailing whitespace from it, it is a valid non-empty URL.
To parse a URL url into its component parts, the user agent must use the parse an address algorithm defined by the IRI specification. [RFC3987]
Parsing a URL can fail. If it does not, then it results in the following components, again as defined by the IRI specification:
To resolve a URL to an absolute URL relative to either another absolute URL or an element, the user agent must use the following steps. Resolving a URL can result in an error, in which case the URL is not resolvable.
Let url be the URL being resolved.
Let encoding be determined as follows:
Document
, and the URL character
encoding is the document's character encoding.If encoding is a UTF-16 encoding, then change the value of encoding to UTF-8.
If the algorithm was invoked with an absolute URL to use as the base URL, let base be that absolute URL.
Otherwise, let base be the base URI of
the element, as defined by the XML Base specification, with
the base URI of the document entity being defined as the
document base URL of the Document
that
owns the element. [XMLBASE]
For the purposes of the XML Base specification, user agents
must act as if all Document
objects represented XML
documents.
It is possible for xml:base
attributes to be present
even in HTML fragments, as such attributes can be added
dynamically using script. (Such scripts would not be conforming,
however, as xml:base
attributes
are not allowed in HTML documents.)
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.
Return the result of applying the resolve an address algorithm defined by the IRI specification to resolve url relative to base using encoding encoding. [RFC3987]
A URL is an absolute URL if resolving it results in the same output regardless of what it is resolved relative to, and that output is not a failure.
An absolute URL is a hierarchical URL if, when resolved and then parsed, there is a character immediately after the <scheme> component and it is a U+002F SOLIDUS character (/).
An absolute URL is an authority-based URL if, when resolved and then parsed, there are two characters immediately after the <scheme> component and they are both U+002F SOLIDUS characters (//).
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 an authority-based URL | — | — | — | The new value is not the empty string and input is an authority-based URL |
hostname
| <host> | input is an authority-based URL | — | — | Remove all leading U+002F SOLIDUS characters (/) | The new value is not the empty string and input is an authority-based URL |
port
| <port> | input is an authority-based URL, 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 an authority-based URL, and the new value, when interpreted as a base-ten integer, is less than or equal to 65535 |
pathname
| <path> | input is a hierarchical URL | — | — | 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 a hierarchical URL, 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 a hierarchical URL |
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, a manual redirect flag, a force same-origin flag, and/or a block cookies 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.
This is the main step.
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, if the resource is identified by an absolute
URL with a scheme that does not define a mechanism to
obtain the resource (e.g. it is a mailto:
URL) or that the user agent does not support, then act as if the
resource was an HTTP 204 No Content response with no other
metadata.
Otherwise, 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.
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, dereferencing javascript:
URLs,
etc).
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 algorithm was not invoked with the block cookies flag, and 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 fetched resource is an HTTP redirect or equivalent, then:
Abort these steps and return failure from this algorithm, as if the remote host could not be contacted.
Continue, using the fetched resource (the redirect) as the result of the algorithm.
First, apply any relevant requirements for redirects (such as showing any appropriate prompts). Then, redo main step, but using the target of the redirect as the resource to fetch, rather than the original resource.
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. That would be an appropriate prompt for the purposes of the requirement in the paragraph above. [HTTP]
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 Media Type Sniffing specification. [MIMESNIFF]
The sniffed type of a resource must be found in a manner consistent with the requirements given in the Media Type Sniffing 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 Media Type Sniffing specification. Both sets of rules return a MIME type as their result. [MIMESNIFF]
It is imperative that the rules in the Media Type Sniffing 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 Media Type Sniffing specification. [MIMESNIFF]
The algorithm for extracting an encoding from a Content-Type, given a string s, is as follows. It either returns an encoding or nothing.
Find the first seven characters in s
that are an ASCII case-insensitive match for the word
"charset
". If no such match is found, return
nothing.
Skip any U+0009, U+000A, U+000C, U+000D, or U+0020
characters that immediately follow the word "charset
" (there might not be any).
If the next character is not a U+003D EQUALS SIGN ('='), return nothing and abort these steps.
Skip any U+0009, U+000A, U+000C, U+000D, or U+0020 characters that immediately follow the equals sign (there might not be any).
Process the next character as follows:
This requirement is a willful violation of the HTTP specification, motivated by the need for backwards compatibility with legacy content. [HTTP]
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 content attribute must be set to the given
new value.
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 the empty string 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
(double
), 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 Element item(in unsigned long index); caller getter object namedItem(in DOMString name); // only returns Element };
length
Returns 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 HTMLAllCollection
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); };
length
Returns 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; };
length
Returns 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); attribute long selectedIndex; };
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.
selectedIndex
[ = value ]Returns the index of the first selected item, if any, or −1 if there is no selected item.
Can be set, to change the selection.
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 selectedIndex
IDL attribute must act like the identically named attribute on the
select
element on which the
HTMLOptionsCollection
is rooted
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; };
length
Returns 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.
names
Returns a DOMStringList
with the property names of the elements in the collection.
values
Returns 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 (); };
length
Returns 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; };
value
Returns 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.
If input is in memory, then throw a DATA_CLONE_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
)Throw a DATA_CLONE_ERR
exception and abort the
overall structured clone algorithm.
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_ERR
DOMSTRING_SIZE_ERR
HIERARCHY_REQUEST_ERR
WRONG_DOCUMENT_ERR
INVALID_CHARACTER_ERR
NO_DATA_ALLOWED_ERR
NO_MODIFICATION_ALLOWED_ERR
NOT_FOUND_ERR
NOT_SUPPORTED_ERR
INUSE_ATTRIBUTE_ERR
INVALID_STATE_ERR
SYNTAX_ERR
INVALID_MODIFICATION_ERR
NAMESPACE_ERR
INVALID_ACCESS_ERR
VALIDATION_ERR
TYPE_MISMATCH_ERR
SECURITY_ERR
NETWORK_ERR
ABORT_ERR
URL_MISMATCH_ERR
QUOTA_EXCEEDED_ERR
TIMEOUT_ERR
NOT_READABLE_ERR
DATA_CLONE_ERR
ENCODING_ERR
[Supplemental] exception DOMException { const unsigned short URL_MISMATCH_ERR = 21; const unsigned short QUOTA_EXCEEDED_ERR = 22; const unsigned short DATA_CLONE_ERR = 25; };
There 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.