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
};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 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);
};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 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 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 ();
};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 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.
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_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_ERRTIMEOUT_ERRDATA_CLONE_ERRThe 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.