HTML

[OverrideBuiltins]
partial interface Document {
  // 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 readyState;

  // DOM tree accessors
  getter object (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(DOMString elementName);
  NodeList getItems(optional DOMString typeNames); // microdata 
  readonly attribute DOMElementMap cssElementMap;

  // dynamic markup insertion
  Document open(optional DOMString type, optional DOMString replace);
  WindowProxy open(DOMString url, DOMString name, DOMString features, optional boolean replace);
  void close();
  void write(DOMString... text);
  void writeln(DOMString... text);

  // user interaction
  readonly attribute WindowProxy? defaultView;
  readonly attribute Element? activeElement;
  boolean hasFocus();
           attribute DOMString designMode;
  boolean execCommand(DOMString commandId);
  boolean execCommand(DOMString commandId, boolean showUI);
  boolean execCommand(DOMString commandId, boolean showUI, DOMString value);
  boolean queryCommandEnabled(DOMString commandId);
  boolean queryCommandIndeterm(DOMString commandId);
  boolean queryCommandState(DOMString commandId);
  boolean queryCommandSupported(DOMString commandId);
  DOMString queryCommandValue(DOMString commandId);
  readonly attribute HTMLCollection commands;

  // event handler IDL attributes
  [TreatNonCallableAsNull] attribute Function? onabort;
  [TreatNonCallableAsNull] attribute Function? onblur;
  [TreatNonCallableAsNull] attribute Function? oncanplay;
  [TreatNonCallableAsNull] attribute Function? oncanplaythrough;
  [TreatNonCallableAsNull] attribute Function? onchange;
  [TreatNonCallableAsNull] attribute Function? onclick;
  [TreatNonCallableAsNull] attribute Function? oncontextmenu;
  [TreatNonCallableAsNull] attribute Function? oncuechange;
  [TreatNonCallableAsNull] attribute Function? ondblclick;
  [TreatNonCallableAsNull] attribute Function? ondrag;
  [TreatNonCallableAsNull] attribute Function? ondragend;
  [TreatNonCallableAsNull] attribute Function? ondragenter;
  [TreatNonCallableAsNull] attribute Function? ondragleave;
  [TreatNonCallableAsNull] attribute Function? ondragover;
  [TreatNonCallableAsNull] attribute Function? ondragstart;
  [TreatNonCallableAsNull] attribute Function? ondrop;
  [TreatNonCallableAsNull] attribute Function? ondurationchange;
  [TreatNonCallableAsNull] attribute Function? onemptied;
  [TreatNonCallableAsNull] attribute Function? onended;
  [TreatNonCallableAsNull] attribute Function? onerror;
  [TreatNonCallableAsNull] attribute Function? onfocus;
  [TreatNonCallableAsNull] attribute Function? oninput;
  [TreatNonCallableAsNull] attribute Function? oninvalid;
  [TreatNonCallableAsNull] attribute Function? onkeydown;
  [TreatNonCallableAsNull] attribute Function? onkeypress;
  [TreatNonCallableAsNull] attribute Function? onkeyup;
  [TreatNonCallableAsNull] attribute Function? onload;
  [TreatNonCallableAsNull] attribute Function? onloadeddata;
  [TreatNonCallableAsNull] attribute Function? onloadedmetadata;
  [TreatNonCallableAsNull] attribute Function? onloadstart;
  [TreatNonCallableAsNull] attribute Function? onmousedown;
  [TreatNonCallableAsNull] attribute Function? onmousemove;
  [TreatNonCallableAsNull] attribute Function? onmouseout;
  [TreatNonCallableAsNull] attribute Function? onmouseover;
  [TreatNonCallableAsNull] attribute Function? onmouseup;
  [TreatNonCallableAsNull] attribute Function? onmousewheel;
  [TreatNonCallableAsNull] attribute Function? onpause;
  [TreatNonCallableAsNull] attribute Function? onplay;
  [TreatNonCallableAsNull] attribute Function? onplaying;
  [TreatNonCallableAsNull] attribute Function? onprogress;
  [TreatNonCallableAsNull] attribute Function? onratechange;
  [TreatNonCallableAsNull] attribute Function? onreset;
  [TreatNonCallableAsNull] attribute Function? onscroll;
  [TreatNonCallableAsNull] attribute Function? onseeked;
  [TreatNonCallableAsNull] attribute Function? onseeking;
  [TreatNonCallableAsNull] attribute Function? onselect;
  [TreatNonCallableAsNull] attribute Function? onshow;
  [TreatNonCallableAsNull] attribute Function? onstalled;
  [TreatNonCallableAsNull] attribute Function? onsubmit;
  [TreatNonCallableAsNull] attribute Function? onsuspend;
  [TreatNonCallableAsNull] attribute Function? ontimeupdate;
  [TreatNonCallableAsNull] attribute Function? onvolumechange;
  [TreatNonCallableAsNull] attribute Function? onwaiting;

  // special event handler IDL attributes that only apply to Document objects
  [TreatNonCallableAsNull,LenientThis] attribute Function? onreadystatechange;
};

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 throw a SecurityError 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 throw a SecurityError 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.

---

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. Strip leading and trailing whitespace from 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 act as if it was the setter for the IDL attribute of the same name on the Document interface defined by the SVG specification. 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 IDL attribute defined above must replace the attribute of the same name on the Document interface defined by the SVG specification 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 throw a HierarchyRequestError 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 cssElementMap IDL attribute allows authors to define CSS element reference identifiers, which are used in certain CSS features to override the normal ID-based mapping. [CSSIMAGES]

When a Document is created, it must be associated with an initially-empty CSS ID overrides list, which consists of a list of mappings each of which consists of a string name mapped to an Element node.

Each entry in the CSS ID overrides list, while it is in the list and is either in the Document or is an img, video, or canvas element, defines a CSS element reference identifier mapping the given name to the given Element. [CSSIMAGES]

On getting, the cssElementMap IDL attribute must return a DOMElementMap object, associated with the following algorithms, which expose the current mappings:

The algorithm for getting the list of name-element mappings

Return the Document's CSS ID overrides list, maintaining the order in which the entries were originally added to the list.

The algorithm for for mapping a name to a certain element

Let name be the name passed to the algorithm and element be the Element passed to the algorithm.

If element is null, run the algorithm for deleting mappings by name, passing it name.

Otherwise, if there is an entry in the Document's CSS ID overrides list whose name is name, replace its current value with element.

Otherwise, add a mapping to the Document's CSS ID overrides list whose name is name and whose element is element.

The algorithm for deleting mappings by name

If there is an entry in the Document's CSS ID overrides list whose name is the name passed to this algorithm, remove it. This also undefines the CSS element reference identifier for that name. [CSSIMAGES]

The same object must be returned each time.

---

The Document interface supports named properties. The supported property names at any moment consist of the values of the name content attributes of all the applet, exposed embed, form, iframe, img, and exposed object elements in the Document that have name content attributes, and the values of the id content attributes of all the applet and exposed 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.

To determine the value of a named property name when the Document object is indexed for property retrieval, 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, exposed embed, form, iframe, img, or exposed object elements that have a name content attribute whose value is name, or
• applet or exposed 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 embed or object element is said to be exposed if it has no exposed object ancestor, and, for object elements, is additionally either not showing its fallback content or has no object or embed descendants.

3.1.5 Loading XML documents

partial interface XMLDocument {
  boolean load(DOMString url);
};

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

1. Let document be the XMLDocument 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 SyntaxError 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 SecurityError 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 a 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.