ISSUE-56 (urls-webarch) blocks progress to Last Call
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.
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]
An interface that has a complement of URL decomposition IDL attributes has 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 table below demonstrates how the getter 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. |
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. |
The following table is similar; it provides a list of what each of the URL decomposition IDL attributes returns for a given input URL.
Input | protocol
| host
| hostname
| port
| pathname
| search
| hash
|
---|---|---|---|---|---|---|---|
http://example.com/carrot#question%3f
| http:
| example.com
| example.com
| (empty string) | /carrot
| (empty string) | #question%3f
|
https://www.example.com:4443?
| https:
| www.example.com:4443
| www.example.com
| 4443
| /
| ?
| (empty string) |
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.
The HTMLCollection
, HTMLAllCollection
,
HTMLFormControlsCollection
,
HTMLOptionsCollection
,
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.
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 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 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 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 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 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.
The DOMStringMap
interface represents a set of
name-value pairs. It exposes these using the scripting language's
native mechanisms for property access.
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.
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
DATA_CLONE_ERR
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.
In the HTML syntax, namespace prefixes and namespace declarations do not have the same effect as in XML. For instance, the colon has no special meaning in HTML element names.