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.
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.
Each Document
object has a reload override flag that is originally unset. The flag is set by the document.open()
and document.write()
methods in certain situations. When the flag is set, the Document
also has a reload override buffer which is a Unicode string that is used as the source of the document when it is reloaded.
When the user agent is to perform an overridden reload, it must act as follows:
Let source be the value of the browsing context's active document's reload override buffer.
Navigate the browsing context to a resource whose source is source, with replacement enabled. When the navigate algorithm creates a Document
object for this purpose, set that Document
's reload override flag and set its reload override buffer to source.
All Document
objects (in user agents implementing this specification) 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 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); // 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 readonly attribute WindowProxy defaultView; 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 oncuechange; 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 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 onreset; 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 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.
URL
Returns the document's address.
referrer
Returns 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.
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.
lastModified
Returns 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.
compatMode
In a conforming document, returns the string "CSS1Compat
". (In quirks mode documents, returns the string "BackCompat
", but a conforming document can never trigger quirks mode.)
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.
characterSet
Returns the document's character encoding.
defaultCharset
Returns 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.)
readyState
Returns "loading" while the Document
is loading, "interactive" once it is finished parsing but still loading sub-resources, and "complete" once it has loaded.
The readystatechange
event fires on the Document
object when this value changes.
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.
head
Returns 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.
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.
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.
images
Returns an HTMLCollection
of the img
elements in the Document
.
embeds
plugins
Return an HTMLCollection
of the embed
elements in the Document
.
links
Returns an HTMLCollection
of the a
and area
elements in the Document
that have href
attributes.
forms
Return an HTMLCollection
of the form
elements in the Document
.
scripts
Return an HTMLCollection
of the script
elements in the Document
.
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.
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 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;