Status: Last call for comments
Status: Last call for comments
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.
Status: Last call for comments
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;
Selection getSelection();
readonly attribute Element activeElement;
boolean hasFocus();
attribute DOMString designMode;
boolean execCommand(in DOMString commandId);
boolean execCommand(in DOMString commandId, in boolean showUI);
boolean execCommand(in DOMString commandId, in boolean showUI, in DOMString value);
boolean queryCommandEnabled(in DOMString commandId);
boolean queryCommandIndeterm(in DOMString commandId);
boolean queryCommandState(in DOMString commandId);
boolean queryCommandSupported(in DOMString commandId);
DOMString queryCommandValue(in DOMString commandId);
readonly attribute HTMLCollection commands;
// event handler IDL attributes
attribute Function onabort;
attribute Function onblur;
attribute Function oncanplay;
attribute Function oncanplaythrough;
attribute Function onchange;
attribute Function onclick;
attribute Function oncontextmenu;
attribute Function ondblclick;
attribute Function ondrag;
attribute Function ondragend;
attribute Function ondragenter;
attribute Function ondragleave;
attribute Function ondragover;
attribute Function ondragstart;
attribute Function ondrop;
attribute Function ondurationchange;
attribute Function onemptied;
attribute Function onended;
attribute Function onerror;
attribute Function onfocus;
attribute Function onformchange;
attribute Function onforminput;
attribute Function oninput;
attribute Function oninvalid;
attribute Function onkeydown;
attribute Function onkeypress;
attribute Function onkeyup;
attribute Function onload;
attribute Function onloadeddata;
attribute Function onloadedmetadata;
attribute Function onloadstart;
attribute Function onmousedown;
attribute Function onmousemove;
attribute Function onmouseout;
attribute Function onmouseover;
attribute Function onmouseup;
attribute Function onmousewheel;
attribute Function onpause;
attribute Function onplay;
attribute Function onplaying;
attribute Function onprogress;
attribute Function onratechange;
attribute Function onreadystatechange;
attribute Function onscroll;
attribute Function onseeked;
attribute Function onseeking;
attribute Function onselect;
attribute Function onshow;
attribute Function onstalled;
attribute Function onsubmit;
attribute Function onsuspend;
attribute Function ontimeupdate;
attribute Function onvolumechange;
attribute Function onwaiting;
};
Document implements HTMLDocument;Since the HTMLDocument interface holds methods and
attributes related to a number of disparate features, the members of
this interface are described in various different sections.
User agents 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.
Status: Last call for comments
URLReturns the document's address.
referrerReturns the
address of the Document from which the user
navigated to this one, unless it was blocked or there was no such
document, in which case it returns the empty string.
The noreferrer link
type can be used to block the referrer.
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.
lastModifiedReturns the date of the last modification to the document, as
reported by the server, in the form "MM/DD/YYYY hh:mm:ss", in the user's local
time zone.
If the last modification date is not known, the current time is returned instead.
compatModeIn a conforming document, returns the string "CSS1Compat". (In quirks mode
documents, returns the string "BackCompat",
but a conforming document can never trigger quirks
mode.)
charset [ = value ]Returns the document's character encoding.
Can be set, to dynamically change the document's character encoding.
New values that are not IANA-registered aliases supported by the user agent are ignored.
characterSetReturns the document's character encoding.
defaultCharsetReturns what might be the user agent's default character encoding. (The user agent might return another character encoding altogether, e.g. to protect the user's privacy, or if the user agent doesn't use a single default encoding.)
readyStateReturns "loading" while the Document is loading, and "complete" once it has loaded.
The readystatechange event fires on the Document object when this value changes.
Status: Last call for comments
The html element of a document is the
document's root element, if there is one and it's an
html element, or null otherwise.
headReturns the head element.
The head element of a document is the
first head element that is a child of the
html element, if there is one, or null
otherwise.
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.
imagesReturns an HTMLCollection of the img elements in the Document.
embedspluginsReturn an HTMLCollection of the embed elements in the Document.
linksReturns an HTMLCollection of the a and area elements in the Document that have href attributes.
formsReturn an HTMLCollection of the form elements in the Document.
scriptsReturn an HTMLCollection of the script elements in the Document.
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.
Status: Last call for comments
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;