HTML5

[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;

The URL attribute must return the document's address.

The referrer attribute must return either the current address of the active document of the source browsing context at the time the navigation was started (that is, the page which navigated the browsing context to the current document), with any <fragment> component removed; or the empty string if there is no such originating page, or if the UA has been configured not to report referrers in this case, or if the navigation was initiated for a hyperlink with a noreferrer keyword.

The cookie attribute represents the cookies of the resource from which the Document was created.

A Document object that falls into one of the following conditions is a cookie-free Document object:

• A Document that has no browsing context.
• A Document whose address does not use a server-based naming authority.

On getting, if the document is a cookie-free Document object, then the user agent must return the empty string. Otherwise, if the Document's origin is not a scheme/host/port tuple, the user agent must raise a SECURITY_ERR exception. Otherwise, the user agent must first obtain the storage mutex and then return the cookie-string for the document's address for a "non-HTTP" API, decoded as UTF-8, with error handling. [COOKIES]

On setting, if the document is a cookie-free Document object, then the user agent must do nothing. Otherwise, if the Document's origin is not a scheme/host/port tuple, the user agent must raise a SECURITY_ERR exception. Otherwise, the user agent must obtain the storage mutex and then act as it would when receiving a set-cookie-string for the document's address via a "non-HTTP" API, consisting of the new value encoded as UTF-8. [COOKIES] [RFC3629]

Since the cookie attribute is accessible across frames, the path restrictions on cookies are only a tool to help manage which cookies are sent to which parts of the site, and are not in any way a security feature.

---

The lastModified attribute, on getting, must return the date and time of the Document's source file's last modification, in the user's local time zone, in the following format:

1. The month component of the date.
2. A U+002F SOLIDUS character (/).
3. The day component of the date.
4. A U+002F SOLIDUS character (/).
5. The year component of the date.
6. A U+0020 SPACE character.
7. The hours component of the time.
8. A U+003A COLON character (:).
9. The minutes component of the time.
10. A U+003A COLON character (:).
11. The seconds component of the time.

All the numeric components above, other than the year, must be given as two digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) representing the number in base ten, zero-padded if necessary. The year must be given as the shortest possible string of four or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) representing the number in base ten, zero-padded if necessary.

The Document's source file's last modification date and time must be derived from relevant features of the networking protocols used, e.g. from the value of the HTTP Last-Modified header of the document, or from metadata in the file system for local files. If the last modification date and time are not known, the attribute must return the current date and time in the above format.

---

A Document is always set to one of three modes: no-quirks mode, the default; quirks mode, used typically for legacy documents; and limited-quirks mode, also known as "almost standards" mode. The mode is only ever changed from the default by the HTML parser, based on the presence, absence, or value of the DOCTYPE string.

The compatMode IDL attribute must return the literal string "CSS1Compat" unless the document has been set to quirks mode by the HTML parser, in which case it must instead return the literal string "BackCompat".

---

Documents have an associated character encoding. When a Document object is created, the document's character encoding must be initialized to UTF-16. Various algorithms during page loading affect this value, as does the charset setter. [IANACHARSET]

The charset IDL attribute must, on getting, return the preferred MIME name of the document's character encoding. On setting, if the new value is an IANA-registered alias for a character encoding supported by the user agent, the document's character encoding must be set to that character encoding. (Otherwise, nothing happens.)

The characterSet IDL attribute must, on getting, return the preferred MIME name of the document's character encoding.

The defaultCharset IDL attribute must, on getting, return the preferred MIME name of a character encoding, possibly the user's default encoding, or an encoding associated with the user's current geographical location, or any arbitrary encoding name.

---

Each document has a current document readiness. When a Document object is created, it must have its current document readiness set to the string "loading" if the document is associated with an HTML parser or an XML parser, or to the string "complete" otherwise. Various algorithms during page loading affect this value. When the value is set, the user agent must fire a simple event named readystatechange at the Document object.

A Document is said to have an active parser if it is associated with an HTML parser or an XML parser that has not yet been stopped or aborted.

The readyState IDL attribute must, on getting, return the current document readiness.

The head attribute, on getting, must return the head element of the document (a head element or null).

The title attribute must, on getting, run the following algorithm:

1. If the root element is an svg element in the "http://www.w3.org/2000/svg" namespace, and the user agent supports SVG, then return the value that would have been returned by the IDL attribute of the same name on the SVGDocument interface. [SVG]

2. Otherwise, let value be a concatenation of the data of all the child text nodes of the title element, in tree order, or the empty string if the title element is null.

3. Replace any sequence of one or more consecutive space characters in value with a single U+0020 SPACE character.

4. Remove any leading or trailing space characters in value.

5. Return value.

On setting, the following algorithm must be run. Mutation events must be fired as appropriate.

1. If the root element is an svg element in the "http://www.w3.org/2000/svg" namespace, and the user agent supports SVG, then the setter must defer to the setter for the IDL attribute of the same name on the SVGDocument interface (if it is readonly, then this will raise an exception). Stop the algorithm here. [SVG]

2. If the title element is null and the head element is null, then the attribute must do nothing. Stop the algorithm here.
3. If the title element is null, then a new title element must be created and appended to the head element. Let element be that element. Otherwise, let element be the title element.
4. The children of element (if any) must all be removed.
5. A single Text node whose data is the new value being assigned must be appended to element.

The title attribute on the HTMLDocument interface should shadow the attribute of the same name on the SVGDocument interface when the user agent supports both HTML and SVG. [SVG]

The body attribute, on getting, must return the body element of the document (either a body element, a frameset element, or null). On setting, the following algorithm must be run:

1. If the new value is not a body or frameset element, then raise a HIERARCHY_REQUEST_ERR exception and abort these steps.
2. Otherwise, if the new value is the same as the body element, do nothing. Abort these steps.
3. Otherwise, if the body element is not null, then replace that element with the new value in the DOM, as if the root element's replaceChild() method had been called with the new value and the incumbent body element as its two arguments respectively, then abort these steps.
4. Otherwise, the body element is null. Append the new value to the root element.

The images attribute must return an HTMLCollection rooted at the Document node, whose filter matches only img elements.

The embeds attribute must return an HTMLCollection rooted at the Document node, whose filter matches only embed elements.

The plugins attribute must return the same object as that returned by the embeds attribute.

The links attribute must return an HTMLCollection rooted at the Document node, whose filter matches only a elements with href attributes and area elements with href attributes.

The forms attribute must return an HTMLCollection rooted at the Document node, whose filter matches only form elements.

The scripts attribute must return an HTMLCollection rooted at the Document node, whose filter matches only script elements.

---

The getElementsByName(name) method takes a string name, and must return a live NodeList containing all the HTML elements in that document that have a name attribute whose value is equal to the name argument (in a case-sensitive manner), in tree order. When the method is invoked on a Document object again with the same argument, the user agent may return the same as the object returned by the earlier call. In other cases, a new NodeList object must be returned.

The getElementsByClassName(classNames) method takes a string that contains a set of space-separated tokens representing classes. When called, the method must return a live NodeList object containing all the elements in the document, in tree order, that have all the classes specified in that argument, having obtained the classes by splitting a string on spaces. (Duplicates are ignored.) If there are no tokens specified in the argument, then the method must return an empty NodeList. If the document is in quirks mode, then the comparisons for the classes must be done in an ASCII case-insensitive manner, otherwise, the comparisons must be done in a case-sensitive manner. When the method is invoked on a Document object again with the same argument, the user agent may return the same object as the object returned by the earlier call. In other cases, a new NodeList object must be returned.

The getElementsByClassName(classNames) method on the HTMLElement interface must return a live NodeList with the nodes that the HTMLDocument getElementsByClassName() method would return when passed the same argument(s), excluding any elements that are not descendants of the HTMLElement object on which the method was invoked. When the method is invoked on an HTMLElement object again with the same argument, the user agent may return the same object as the object returned by the earlier call. In other cases, a new NodeList object must be returned.

<div id="example">
 <p id="p1" class="aaa bbb"/>
 <p id="p2" class="aaa ccc"/>
 <p id="p3" class="bbb ccc"/>
</div>

---

The HTMLDocument interface supports named properties. The supported property names at any moment consist of the values of the name content attributes of all the applet, embed, form, iframe, img, and fallback-free object elements in the Document that have name content attributes, and the values of the id content attributes of all the applet and fallback-free object elements in the Document that have id content attributes, and the values of the id content attributes of all the img elements in the Document that have both name content attributes and id content attributes.

When the HTMLDocument object is indexed for property retrieval using a name name, then the user agent must return the value obtained using the following steps:

1. Let elements be the list of named elements with the name name in the Document.

   There will be at least one such element, by definition.

2. If elements has only one element, and that element is an iframe element, then return the WindowProxy object of the nested browsing context represented by that iframe element, and abort these steps.

3. Otherwise, if elements has only one element, return that element and abort these steps.

4. Otherwise return an HTMLCollection rooted at the Document node, whose filter matches only named elements with the name name.

Named elements with the name name, for the purposes of the above algorithm, are those that are either:

• applet, embed, form, iframe, img, or fallback-free object elements that have a name content attribute whose value is name, or
• applet or fallback-free object elements that have an id content attribute whose value is name, or
• img elements that have an id content attribute whose value is name, and that have a name content attribute present also.

An object element is said to be fallback-free if it has no object or embed descendants.

[Supplemental, NoInterfaceObject]
interface DOMHTMLImplementation {
  Document createHTMLDocument(in DOMString title);
};
DOMImplementation implements DOMHTMLImplementation;

The createHTMLDocument(title) method, when invoked, must run the following steps:

1. Let doc be a newly created Document object.

2. Mark doc as being an HTML document.

3. Create a DocumentType node with the name attribute set to the string "html", and the other attributes specific to DocumentType objects set to the empty string, null, and empty lists, as appropriate. Append the newly created node to doc.

4. Create an html element, and append it to doc.

5. Create a head element, and append it to the html element created in the previous step.

6. Create a title element, and append it to the head element created in the previous step.

7. Create a Text node, and set its data attribute to the string given by the method's argument (which could be the empty string). Append it to the title element created in the previous step.

8. Create a body element, and append it to the html element created in the earlier step.

9. Return doc.

3.1.6 Loading XML documents

A Document object that is an XML document that was created by the DOMImplementation.createDocument() factory method must also implement the XMLDocumentLoader interface:

[Supplemental, NoInterfaceObject]
interface XMLDocumentLoader {
  boolean load(in DOMString url);
};

The load(url) method must run the following steps:

1. Let document be the Document object on which the method was invoked.

2. Resolve the method's first argument, relative to the entry script's base URL. If this is not successful, throw a SYNTAX_ERR exception and abort these steps. Otherwise, let url be the resulting absolute URL.

3. If the origin of url is not the same as the origin of document, throw a SECURITY_ERR exception and abort these steps.

4. Remove all child nodes of document, without firing any mutation events.

5. Set the current document readiness of document to "loading".

6. Run the remainder of these steps asynchronously, and return true from the method.

7. Let result be an Document object.

8. Let success be false.

9. Fetch url from the origin of document, with the synchronous flag set and the force same-origin flag set.

10. If the fetch attempt was successful, and the resource's Content-Type metadata is an XML MIME type, then run these substeps:

    1. Create a new XML parser associated with the result document.

    2. Pass this parser the fetched document.

    3. If there is an XML well-formedness or XML namespace well-formedness error, then remove all child nodes from result. Otherwise let success be true.

11. Queue a task to run the following steps.

    1. Set the current document readiness of document to "complete".

    2. Replace all the children of document by the children of result (even if it has no children), firing mutation events as if a DocumentFragment containing the new children had been inserted.

    3. Fire a simple event named load at document.