The Document object

The DOM specification defines a Document interface, which this specification extends significantly:

enum DocumentReadyState { "loading", "interactive", "complete" };

[OverrideBuiltins]
partial /*sealed*/ interface Document {
  // resource metadata management
  [PutForwards=href, Unforgeable] readonly attribute Location? location;
  attribute DOMString domain;
  readonly attribute DOMString referrer;
  attribute DOMString cookie;
  readonly attribute DOMString lastModified;
  readonly attribute DocumentReadyState readyState;

  // DOM tree accessors
  getter object (DOMString name);
  attribute DOMString title;
  attribute DOMString dir;
  attribute HTMLElement? body;
  readonly attribute HTMLHeadElement? head;
  [SameObject] readonly attribute HTMLCollection images;
  [SameObject] readonly attribute HTMLCollection embeds;
  [SameObject] readonly attribute HTMLCollection plugins;
  [SameObject] readonly attribute HTMLCollection links;
  [SameObject] readonly attribute HTMLCollection forms;
  [SameObject] readonly attribute HTMLCollection scripts;
  NodeList getElementsByName(DOMString elementName);
  NodeList getItems(optional DOMString typeNames = ""); // microdata
  [SameObject] readonly attribute DOMElementMap cssElementMap;
  readonly attribute HTMLScriptElement? currentScript;

  // dynamic markup insertion
  Document open(optional DOMString type = "text/html", optional DOMString replace = "");
  WindowProxy open(DOMString url, DOMString name, DOMString features, optional boolean replace = false);
  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, optional boolean showUI = false, optional 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;

  // special event handler IDL attributes that only apply to Document objects
  [LenientThis] attribute EventHandler onreadystatechange;

  // also has obsolete members
};
Document implements GlobalEventHandlers;

Resource metadata management

document . 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.

The referrer attribute must return the document's 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).

document . 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 (e.g. in an iframe with the sandbox attribute), a SecurityError exception will be thrown on getting and setting.

The cookie attribute represents the cookies of the resource identified by the document's address.

A Document object that falls into one of the following conditions is a cookie-averse 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-averse 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 using the UTF-8 decoder. [[!COOKIES]]

On setting, if the document is a cookie-averse 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]] [[!ENCODING]]

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.

document . 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.

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 ASCII digits representing the number in base ten, zero-padded if necessary. The year must be given as the shortest possible string of four or more ASCII digits 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.

document . 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.

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, an XML parser, or an XSLT processor, and 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.

DOM tree accessors

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.

document . 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.

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

document . title [ = value ]

Returns the document's title, as given by the title element for HTML and as given by the SVG title element for SVG.

Can be set, to update the document's title. If there is no appropriate element to update, the new value is ignored.

The title element of a document is the first title element in the document (in tree order), if there is one, or null otherwise.

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

1. If the root element is an svg element in the SVG namespace, then let value be a concatenation of the data of all the child Text nodes of the first title element in the SVG namespace that is a child of the root element. [[!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. Strip and collapse whitespace in value.

4. Return value.

On setting, the steps corresponding to the first matching condition in the following list must be run:

If the root element is an svg element in the SVG namespace [[!SVG]]

1. Let element be the first title element in the SVG namespace that is a child of the root element, if any. If there isn't one, create a title element in the SVG namespace, append it to the root element, and let element be that element. [[!SVG]]

2. Act as if the textContent IDL attribute of element was set to the new value being assigned.

If the root element is in the HTML namespace

1. If the title element is null and the head element is null, then abort these steps.

2. If the title element is null, then create a new title element and append it to the head element, and let element be the newly created element; otherwise, let element be the title element.

3. Act as if the textContent IDL attribute of element was set to the new value being assigned.

Otherwise

Do nothing.

document . 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 HierarchyRequestError 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.

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, if there is no root element, throw a HierarchyRequestError exception and abort these steps.
5. Otherwise, the body element is null, but there's a root element. Append the new value to the root element.

document . images

Returns an HTMLCollection of the img elements in the Document.

document . embeds

document . plugins

Return an HTMLCollection of the embed elements in the Document.

document . links

Returns an HTMLCollection of the a and area elements in the Document that have href attributes.

document . forms

Return an HTMLCollection of the form elements in the Document.

document . scripts

Return an HTMLCollection of the script elements in the Document.

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.

collection = document . getElementsByName(name)

Returns a NodeList of elements in the Document that have a name attribute with the value name.

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.

element . cssElementMap

Returns a DOMElementMap object for the Document representing the current CSS element reference identifiers.

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 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]]

document . currentScript

Returns the script element that is currently executing. In the case of reentrant script execution, returns the one that most recently started executing amongst those that have not yet finished executing.

Returns null if the Document is not currently executing a script element (e.g. because the running script is an event handler, or a timeout).

The currentScript attribute, on getting, must return the value to which it was most recently initialised. When the Document is created, the currentScript must be initialised to null.

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 non-empty name content attributes, and the values of the id content attributes of all the applet and exposed object elements in the Document that have non-empty id content attributes, and the values of the id content attributes of all the img elements in the Document that have both non-empty name content attributes and non-empty id content attributes. The supported property names must be in tree order, ignoring later duplicates, with values from id attributes coming before values from name attributes when the same element contributes both.

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 non-empty 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.

The dir attribute on the Document interface is defined along with the dir content attribute.

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 API base URL specified by the entry settings object. 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 in parallel, 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, using the referrer source specified by the entry settings object, with the blocking 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.

Nested browsing contexts

Certain elements (for example, iframe elements) can instantiate further browsing contexts. These are called nested browsing contexts. If a browsing context P has a Document D with an element E that nests another browsing context C inside it, then C is said to be nested through D, and E is said to be the browsing context container of C. If the browsing context container element E is in the Document D, then P is said to be the parent browsing context of C and C is said to be a child browsing context of P. Otherwise, the nested browsing context C has no parent browsing context.

A browsing context A is said to be an ancestor of a browsing context B if there exists a browsing context A' that is a child browsing context of A and that is itself an ancestor of B, or if the browsing context A is the parent browsing context of B.

A browsing context that is not a nested browsing context has no parent browsing context, and is the top-level browsing context of all the browsing contexts for which it is an ancestor browsing context.

The transitive closure of parent browsing contexts for a nested browsing context gives the list of ancestor browsing contexts.

The list of the descendant browsing contexts of a Document d is the (ordered) list returned by the following algorithm:

1. Let list be an empty list.

2. For each child browsing context of d that is nested through an element that is in the Document d, in the tree order of the elements nesting those browsing contexts, run these substeps:

   1. Append that child browsing context to the list list.

   2. Append the list of the descendant browsing contexts of the active document of that child browsing context to the list list.

3. Return the constructed list.

A Document is said to be fully active when it is the active document of its browsing context, and either its browsing context is a top-level browsing context, or it has a parent browsing context and the Document through which it is nested is itself fully active.

Because they are nested through an element, child browsing contexts are always tied to a specific Document in their parent browsing context. User agents must not allow the user to interact with child browsing contexts of elements that are in Documents that are not themselves fully active.

A nested browsing context can have a seamless browsing context flag set, if it is embedded through an iframe element with a seamless attribute.

A nested browsing context can be put into a delaying load events mode. This is used when it is navigated, to delay the load event of the browsing context container before the new Document is created.

The document family of a browsing context consists of the union of all the Document objects in that browsing context's session history and the document families of all those Document objects. The document family of a Document object consists of the union of all the document families of the browsing contexts that are nested through the Document object.

Auxiliary browsing contexts

It is possible to create new browsing contexts that are related to a top-level browsing context without being nested through an element. Such browsing contexts are called auxiliary browsing contexts. Auxiliary browsing contexts are always top-level browsing contexts.

An auxiliary browsing context has an opener browsing context, which is the browsing context from which the auxiliary browsing context was created.

Secondary browsing contexts

User agents may support secondary browsing contexts, which are browsing contexts that form part of the user agent's interface, apart from the main content area.

Security

A browsing context A is familiar with a second browsing context B if one of the following conditions is true:

• Either the origin of the active document of A is the same as the origin of the active document of B, or
• The browsing context A is a nested browsing context with a top-level browsing context, and its top-level browsing context is B, or
• The browsing context B is an auxiliary browsing context and A is familiar with B's opener browsing context, or
• The browsing context B is not a top-level browsing context, but there exists an ancestor browsing context of B whose active document has the same origin as the active document of A (possibly in fact being A itself).

A browsing context A is allowed to navigate a second browsing context B if the following algorithm terminates positively:

1. If A is not the same browsing context as B, and A is not one of the ancestor browsing contexts of B, and B is not a top-level browsing context, and A's active document's active sandboxing flag set has its sandboxed navigation browsing context flag set, then abort these steps negatively.

2. Otherwise, if B is a top-level browsing context, and is one of the ancestor browsing contexts of A, and A's node document's active sandboxing flag set has its sandboxed top-level navigation browsing context flag set, then abort these steps negatively.

3. Otherwise, if B is a top-level browsing context, and is neither A nor one of the ancestor browsing contexts of A, and A's Document's active sandboxing flag set has its sandboxed navigation browsing context flag set, and A is not the one permitted sandboxed navigator of B, then abort these steps negatively.

4. Otherwise, terminate positively!

An element has a browsing context scope origin if its Document's browsing context is a top-level browsing context or if all of its Document's ancestor browsing contexts all have active documents whose origin are the same origin as the element's node document's origin. If an element has a browsing context scope origin, then its value is the origin of the element's node document.

Groupings of browsing contexts

Each browsing context is defined as having a list of one or more directly reachable browsing contexts. These are:

• The browsing context itself.
• All the browsing context's child browsing contexts.
• The browsing context's parent browsing context.
• All the browsing contexts that have the browsing context as their opener browsing context.
• The browsing context's opener browsing context.

The transitive closure of all the browsing contexts that are directly reachable browsing contexts forms a unit of related browsing contexts.

Each unit of related browsing contexts is then further divided into the smallest number of groups such that every member of each group has an active document with an effective script origin that, through appropriate manipulation of the document.domain attribute, could be made to be the same as other members of the group, but could not be made the same as members of any other group. Each such group is a unit of related similar-origin browsing contexts.

There is also at most one event loop per unit of related similar-origin browsing contexts (though several units of related similar-origin browsing contexts can have a shared event loop).

Browsing context names

Browsing contexts can have a browsing context name. By default, a browsing context has no name (its name is not set).

A valid browsing context name is any string with at least one character that does not start with a U+005F LOW LINE character. (Names starting with an underscore are reserved for special keywords.)

A valid browsing context name or keyword is any string that is either a valid browsing context name or that is an ASCII case-insensitive match for one of: _blank, _self, _parent, or _top.

These values have different meanings based on whether the page is sandboxed or not, as summarised in the following (non-normative) table. In this table, "current" means the browsing context that the link or script is in, "parent" means the parent browsing context of the one the link or script is in, "master" means the nearest ancestor browsing context of the one the link or script is in that is not itself in a seamless iframe, "top" means the top-level browsing context of the one the link or script is in, "new" means a new top-level browsing context or auxiliary browsing context is to be created, subject to various user preferences and user agent policies, "none" means that nothing will happen, and "maybe new" means the same as "new" if the "allow-popups" keyword is also specified on the sandbox attribute (or if the user overrode the sandboxing), and the same as "none" otherwise.

Most of the restrictions on sandboxed browsing contexts are applied by other algorithms, e.g. the navigation algorithm, not the rules for choosing a browsing context given a browsing context name given below.

An algorithm is allowed to show a popup if any of the following conditions is true:

• The task in which the algorithm is running is currently processing an activation behaviour whose click event was trusted.

• The task in which the algorithm is running is currently running the event listener for a trusted event whose type is in the following list:

  • change
  • click
  • dblclick
  • mouseup
  • reset
  • submit

• The task in which the algorithm is running was queued by an algorithm that was allowed to show a popup, and the chain of such algorithms started within a user-agent defined timeframe.

  For example, if a user clicked a button, it might be acceptable for a popup to result from that after 4 seconds, but it would likely not be acceptable for a popup to result from that after 4 hours.

The rules for choosing a browsing context given a browsing context name are as follows. The rules assume that they are being applied in the context of a browsing context, as part of the execution of a task.

1. If the given browsing context name is the empty string or _self, then the chosen browsing context must be the current one.

   If the given browsing context name is _self, then this is an explicit self-navigation override, which overrides the behaviour of the seamless browsing context flag set by the seamless attribute on iframe elements.

2. If the given browsing context name is _parent, then the chosen browsing context must be the parent browsing context of the current one, unless there isn't one, in which case the chosen browsing context must be the current browsing context.

3. If the given browsing context name is _top, then the chosen browsing context must be the top-level browsing context of the current one, if there is one, or else the current browsing context.

4. If the given browsing context name is not _blank and there exists a browsing context whose name is the same as the given browsing context name, and the current browsing context is familiar with that browsing context, and the user agent determines that the two browsing contexts are related enough that it is ok if they reach each other, then that browsing context must be the chosen one. If there are multiple matching browsing contexts, the user agent should select one in some arbitrary consistent manner, such as the most recently opened, most recently focused, or more closely related.

   If the browsing context is chosen by this step to be the current browsing context, then this is also an explicit self-navigation override.

5. Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and abilities — it is determined by the rules given for the first applicable option from the following list:

   If the algorithm is not allowed to show a popup and the user agent has been configured to not show popups (i.e. the user agent has a "popup blocker" enabled)

   There is no chosen browsing context. The user agent may inform the user that a popup has been blocked.

   If the current browsing context's active document's active sandboxing flag set has the sandboxed auxiliary navigation browsing context flag set.

   Typically, there is no chosen browsing context.

   The user agent may offer to create a new top-level browsing context or reuse an existing top-level browsing context. If the user picks one of those options, then the designated browsing context must be the chosen one (the browsing context's name isn't set to the given browsing context name). The default behaviour (if the user agent doesn't offer the option to the user, or if the user declines to allow a browsing context to be used) must be that there must not be a chosen browsing context.

   If this case occurs, it means that an author has explicitly sandboxed the document that is trying to open a link.

   If the user agent has been configured such that in this instance it will create a new browsing context, and the browsing context is being requested as part of following a hyperlink whose link types include the noreferrer keyword

   A new top-level browsing context must be created. If the given browsing context name is not _blank, then the new top-level browsing context's name must be the given browsing context name (otherwise, it has no name). The chosen browsing context must be this new browsing context. The creation of such a browsing context is a new start for session storage.

   If it is immediately navigated, then the navigation will be done with replacement enabled.

   If the user agent has been configured such that in this instance it will create a new browsing context, and the noreferrer keyword doesn't apply

   A new auxiliary browsing context must be created, with the opener browsing context being the current one. If the given browsing context name is not _blank, then the new auxiliary browsing context's name must be the given browsing context name (otherwise, it has no name). The chosen browsing context must be this new browsing context.

   If it is immediately navigated, then the navigation will be done with replacement enabled.

   If the user agent has been configured such that in this instance it will reuse the current browsing context

   The chosen browsing context is the current browsing context.

   If the user agent has been configured such that in this instance it will not find a browsing context

   There must not be a chosen browsing context.

   User agent implementors are encouraged to provide a way for users to configure the user agent to always reuse the current browsing context.

   If the current browsing context's active document's active sandboxing flag set has the sandboxed navigation browsing context flag set and the chosen browsing context picked above, if any, is a new browsing context (whether top-level or auxiliary), then all the flags that are set in the current browsing context's active document's active sandboxing flag set when the new browsing context is created must be set in the new browsing context's popup sandboxing flag set, and the current browsing context must be set as the new browsing context's one permitted sandboxed navigator.

Security

This section describes a security model that is underdefined, imperfect, and does not match implementations. Work is ongoing to attempt to resolve this, but in the meantime, please do not rely on this section for precision. Implementors are urged to send their feedback on how cross-origin cross-global access to Window and Location objects should work. See bug 20701.

User agents must throw a SecurityError exception whenever any properties of a Window object are accessed when the incumbent settings object specifies an effective script origin that is not the same as the Window object's Document's effective script origin, with the following exceptions:

• The location attribute
• The postMessage() method
• The window attribute
• The frames attribute
• The self attribute
• The top attribute
• The parent attribute
• The opener attribute
• The closed attribute
• The close() method
• The blur() method
• The focus() method
• The dynamic nested browsing context properties

When the incumbent settings object specifies an effective script origin that is different than a Window object's Document's effective script origin, the user agent must act as if any changes to that Window object's properties, getters, setters, etc, were not present, and as if all the properties of that Window object had their [[\Enumerable]] attribute set to false.

For members that return objects (including function objects), each distinct effective script origin that is not the same as the Window object's Document's effective script origin must be provided with a separate set of objects. These objects must have the prototype chain appropriate for the script for which the objects are created (not those that would be appropriate for scripts whose global object, as specified by their settings object, is the Window object in question).

APIs for creating and navigating browsing contexts by name

window = window . open( [ url [, target [, features [, replace ] ] ] ] )

Opens a window to show url (defaults to about:blank), and returns it. The target argument gives the name of the new window. If a window exists with that name already, it is reused. The replace attribute, if true, means that whatever page is currently open in that window will be removed from the window's session history. The features argument can be used to influence the rendering of the new window.

window . name [ = value ]

Returns the name of the window.

Can be set, to change the name.

window . close()

Closes the window.

window . closed

Returns true if the window has been closed, false otherwise.

window . stop()

Cancels the document load.

The open() method on Window objects provides a mechanism for navigating an existing browsing context or opening and navigating an auxiliary browsing context.

When the method is invoked, the user agent must run the following steps:

1. Let entry settings be the entry settings object when the method was invoked.

2. Let url be the first argument.

3. Let target be the second argument.

4. Let features be the third argument.

5. Let replace be the fourth argument.

6. Let source browsing context be the responsible browsing context specified by entry settings.

7. If target is the empty string, let it be the string "_blank" instead.

8. If the user has indicated a preference for which browsing context to navigate, follow these substeps:

   1. Let target browsing context be the browsing context indicated by the user.

   2. If target browsing context is a new top-level browsing context, let the source browsing context be set as target browsing context's one permitted sandboxed navigator.

   For example, suppose there is a user agent that supports control-clicking a link to open it in a new tab. If a user clicks in that user agent on an element whose onclick handler uses the window.open() API to open a page in an iframe, but, while doing so, holds the control key down, the user agent could override the selection of the target browsing context to instead target a new tab.

   Otherwise, apply the rules for choosing a browsing context given a browsing context name using target as the name and source browsing context as the context in which the algorithm is executed. If this results in there not being a chosen browsing context, then throw an InvalidAccessError exception and abort these steps. Otherwise, let target browsing context be the browsing context so obtained.

9. If target browsing context was just created, either as part of the rules for choosing a browsing context given a browsing context name or due to the user indicating a preference for navigating a new top-level browsing context, then let new be true. Otherwise, let it be false.

10. Interpret features as defined in the CSSOM View specification. [[!CSSOMVIEW]]

11. If url is the empty string, run the appropriate steps from the following list:

    If new is false

    Jump to the step labeled end.

    If new is true

    Let resource be the URL "about:blank".

    Otherwise, resolve url relative to the API base URL specified by entry settings, and let resource be the resulting absolute URL, if any. If the resolve a URL algorithm failed, then run one of the following two steps instead:

    • Let resource be a resource representing an inline error page.

    • If new is false, jump to the step labeled end, otherwise, let resource be the URL "about:blank".

12. If resource is "about:blank" and new is true, queue a task to fire a simple event named load at target browsing context's Window object, with target override set to target browsing context's Window object's Document object.

    Otherwise, navigate target browsing context to resource, with exceptions enabled. If new is true, then replacement must be enabled also. The source browsing context is source browsing context.

13. End: Return the WindowProxy object of target browsing context.

The name attribute of the Window object must, on getting, return the current name of the browsing context, if one is set, or the empty string otherwise; and, on setting, set the name of the browsing context to the new value.

The name gets reset when the browsing context is navigated to another domain.

The close() method on Window objects should, if all the following conditions are met, close the browsing context A:

• The corresponding browsing context A is script-closable.
• The responsible browsing context specified by the incumbent settings object is familiar with the browsing context A.
• The responsible browsing context specified by the incumbent settings object is allowed to navigate the browsing context A.

A browsing context is script-closable if it is an auxiliary browsing context that was created by a script (as opposed to by an action of the user), or if it is a top-level browsing context whose session history contains only one Document.

The closed attribute on Window objects must return true if the Window object's browsing context has been discarded, and false otherwise.

The stop() method on Window objects should, if there is an existing attempt to navigate the browsing context and that attempt is not currently running the unload a document algorithm, cancel that navigation; then, it must abort the active document of the browsing context of the Window object on which it was invoked.

Accessing other browsing contexts

window . length

Returns the number of child browsing contexts.

window[index]

Returns the indicated child browsing context.

The length IDL attribute on the Window interface must return the number of child browsing contexts that are nested through elements that are in the Document that is the active document of that Window object, if that Window's browsing context shares the same event loop as the responsible document specified by the entry settings object accessing the IDL attribute; otherwise, it must return zero.

The supported property indices on the Window object at any instant are the numbers in the range 0 .. n-1, where n is the number returned by the length IDL attribute. If n is zero then there are no supported property indices.

To determine the value of an indexed property index of a Window object, the user agent must return the WindowProxy object of the indexth child browsing context of the Document that is nested through an element that is in the Document, sorted in the order that the elements nesting those browsing contexts were most recently inserted into the Document, the WindowProxy object of the most recently inserted browsing context container's nested browsing context being last.

These properties are the dynamic nested browsing context properties.

Named access on the Window object

window[name]

Returns the indicated element or collection of elements.

As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to this API can vary over time, as new features are added to the Web platform, for example. Instead of this, use document.getElementById() or document.querySelector().

The Window interface supports named properties. The supported property names at any moment consist of the following, in tree order, ignoring later duplicates:

• the browsing context name of any child browsing context of the active document whose name is not the empty string,
• the value of the name content attribute for all a, applet, area, embed, form, frameset, img, and object elements in the active document that have a non-empty name content attribute, and
• the value of the id content attribute of any HTML element in the active document with a non-empty id content attribute.

To determine the value of a named property name when the Window object is indexed for property retrieval, the user agent must return the value obtained using the following steps:

1. Let objects be the list of named objects with the name name in the active document.

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

2. If objects contains a nested browsing context, then return the WindowProxy object of the nested browsing context corresponding to the first browsing context container in tree order whose browsing context is in objects, and abort these steps.

3. Otherwise, if objects 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 objects with the name name. (By definition, these will all be elements.)

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

• child browsing contexts of the active document whose name is name,
• a, applet, area, embed, form, frameset, img, or object elements that have a name content attribute whose value is name, or
• HTML elements that have an id content attribute whose value is name.

Garbage collection and browsing contexts

A browsing context has a strong reference to each of its Documents and its WindowProxy object, and the user agent itself has a strong reference to its top-level browsing contexts.

A Document has a strong reference to its Window object.

A Window object has a strong reference to its Document object through its document attribute. Thus, references from other scripts to either of those objects will keep both alive. Similarly, both Document and Window objects have implied strong references to the WindowProxy object.

Each script has a strong reference to its settings object, and each environment settings object has strong references to its global object, responsible browsing context, and responsible document (if any).

When a browsing context is to discard a Document, the user agent must run the following steps:

1. Set the Document's salvageable state to false.

2. Run any unloading document cleanup steps for the Document that are defined by this specification and other applicable specifications.

3. Abort the Document.

4. Remove any tasks associated with the Document in any task source, without running those tasks.

5. Discard all the child browsing contexts of the Document.

6. Lose the strong reference from the Document's browsing context to the Document.

Whenever a Document object is discarded, it is also removed from the list of the worker's Documents of each worker whose list contains that Document.

When a browsing context is discarded, the strong reference from the user agent itself to the browsing context must be severed, and all the Document objects for all the entries in the browsing context's session history must be discarded as well.

User agents may discard top-level browsing contexts at any time (typically, in response to user requests, e.g. when a user force-closes a window containing one or more top-level browsing contexts). Other browsing contexts must be discarded once their WindowProxy object is eligible for garbage collection.

Closing browsing contexts

When the user agent is required to close a browsing context, it must run the following steps:

1. Let specified browsing context be the browsing context being closed.

2. Prompt to unload the active document of the specified browsing context. If the user refused to allow the document to be unloaded, then abort these steps.

3. Unload the active document of the specified browsing context with the recycle parameter set to false.

4. Remove the specified browsing context from the user interface (e.g. close or hide its tab in a tabbed browser).

5. Discard the specified browsing context.

User agents should offer users the ability to arbitrarily close any top-level browsing context.

Browser interface elements

To allow Web pages to integrate with Web browsers, certain Web browser interface elements are exposed in a limited way to scripts in Web pages.

Each interface element is represented by a BarProp object:

interface BarProp {
  attribute boolean visible;
};

window . locationbar . visible

Returns true if the location bar is visible; otherwise, returns false.

window . menubar . visible

Returns true if the menu bar is visible; otherwise, returns false.

window . personalbar . visible

Returns true if the personal bar is visible; otherwise, returns false.

window . scrollbars . visible

Returns true if the scroll bars are visible; otherwise, returns false.

window . statusbar . visible

Returns true if the status bar is visible; otherwise, returns false.

window . toolbar . visible

Returns true if the toolbar is visible; otherwise, returns false.

The visible attribute, on getting, must return either true or a value determined by the user agent to most accurately represent the visibility state of the user interface element that the object represents, as described below. On setting, the new value must be discarded.

The following BarProp objects exist for each Document object in a browsing context. Some of the user interface elements represented by these objects might have no equivalent in some user agents; for those user agents, except when otherwise specified, the object must act as if it was present and visible (i.e. its visible attribute must return true).

The location bar BarProp object

Represents the user interface element that contains a control that displays the URL of the active document, or some similar interface concept.

The menu bar BarProp object

Represents the user interface element that contains a list of commands in menu form, or some similar interface concept.

The personal bar BarProp object

Represents the user interface element that contains links to the user's favorite pages, or some similar interface concept.

The scrollbar BarProp object

Represents the user interface element that contains a scrolling mechanism, or some similar interface concept.

The status bar BarProp object

Represents a user interface element found immediately below or after the document, as appropriate for the user's media, which typically provides information about ongoing network activity or information about elements that the user's pointing device is current indicating. If the user agent has no such user interface element, then the object may act as if the corresponding user interface element was absent (i.e. its visible attribute may return false).

The toolbar BarProp object

Represents the user interface element found immediately above or before the document, as appropriate for the user's media, which typically provides session history traversal controls (back and forward buttons, reload buttons, etc). If the user agent has no such user interface element, then the object may act as if the corresponding user interface element was absent (i.e. its visible attribute may return false).

The locationbar attribute must return the location bar BarProp object.

The menubar attribute must return the menu bar BarProp object.

The personalbar attribute must return the personal bar BarProp object.

The scrollbars attribute must return the scrollbar BarProp object.

The statusbar attribute must return the status bar BarProp object.

The toolbar attribute must return the toolbar BarProp object.

For historical reasons, the status attribute on the Window object must, on getting, return the last string it was set to, and on setting, must set itself to the new value. When the Window object is created, the attribute must be set to the empty string. It does not do anything else.

The WindowProxy object

As mentioned earlier, each browsing context has a WindowProxy object. This object is unusual in that all operations that would be performed on it must be performed on the Window object of the browsing context's active document instead. It is thus indistinguishable from that Window object in every way until the browsing context is navigated.

There is no WindowProxy interface object.

The WindowProxy object allows scripts to act as if each browsing context had a single Window object, while still keeping separate Window objects for each Document.

var x = window;
x instanceof Window; // true
x === this; // true

Relaxing the same-origin restriction

document . domain [ = domain ]

Returns the current domain used for security checks.

Can be set to a value that removes subdomains, to change the effective script origin to allow pages on other subdomains of the same domain (if they do the same thing) to access each other. (Can't be set in sandboxed iframes.)

The domain attribute on Document objects must be initialised to the document's domain, if it has one, and the empty string otherwise. If the document's domain starts with a U+005B LEFT SQUARE BRACKET character ([) and ends with a U+005D RIGHT SQUARE BRACKET character (]), it is an IPv6 address; these square brackets must be omitted when initialising the attribute's value.

On getting, the attribute must return its current value, unless the Document has no browsing context, in which case it must return the empty string.

On setting, the user agent must run the following algorithm:

1. If the Document has no browsing context, throw a SecurityError exception and abort these steps.

2. If the Document's active sandboxing flag set has its sandboxed document.domain browsing context flag set, throw a SecurityError exception and abort these steps.

3. If the new value is an IPv4 or IPv6 address, let new value be the new value.

   Otherwise, strictly split the new value on U+002E FULL STOP characters (.), apply the domain to ASCII algorithm to each returned token, and let new value be the result of concatenating the results of applying that algorithm to each token, in the same order, separated by U+002E FULL STOP characters (.). [[!URL]]

   If the domain to ASCII algorithm returns failure, e.g. because a component is too long or because it contains invalid characters, then throw a SecurityError exception and abort these steps.

4. If new value is not exactly equal to the current value of the document.domain attribute, then run these substeps:

   1. If the current value is an IPv4 or IPv6 address, throw a SecurityError exception and abort these steps.

   2. If new value, prefixed by a U+002E FULL STOP (.), does not exactly match the end of the current value, throw a SecurityError exception and abort these steps.

      If the new value is an IPv4 or IPv6 address, it cannot match the new value in this way and thus an exception will be thrown here.

   3. If new value matches a suffix in the Public Suffix List, or, if new value, prefixed by a U+002E FULL STOP (.), matches the end of a suffix in the Public Suffix List, then throw a SecurityError exception and abort these steps. [[!PSL]]

      Suffixes must be compared in an ASCII case-insensitive manner, after applying the domain to ASCII algorithm to their individual components, . [[!URL]]

5. Release the storage mutex.

6. Set the attribute's value to new value.

7. If the effective script origin of the Document is an alias, set it to the value of the effective script origin (essentially de-aliasing the effective script origin).

8. If new value is not the empty string, then run these substeps:

   1. Set the host part of the effective script origin tuple of the Document to new value.

   2. Set the port part of the effective script origin tuple of the Document to "manual override" (a value that, for the purposes of comparing origins, is identical to "manual override" but not identical to any other value).

The domain of a Document is the host part of the document's origin, if the value of that origin is a scheme/host/port tuple. If it isn't, then the document does not have a domain.

The domain attribute is used to enable pages on different hosts of a domain to access each others' DOMs.

Do not use the document.domain attribute when using shared hosting. If an untrusted third party is able to host an HTTP server at the same IP address but on a different port, then the same-origin protection that normally protects two different sites on the same host will fail, as the ports are ignored when comparing origins after the document.domain attribute has been used.

The session history of browsing contexts

The sequence of Documents in a browsing context is its session history. Each browsing context, including nested browsing contexts, has a distinct session history. A browsing context's session history consists of a flat list of session history entries. Each session history entry consists, at a minimum, of a URL, and each entry may in addition have a state object, a title, a Document object, form data, a scroll position, and other information associated with it.

Each entry, when first created, has a Document. However, when a Document is not active, it's possible for it to be discarded to free resources. The URL and other data in a session history entry is then used to bring a new Document into being to take the place of the original, should the user agent find itself having to reactivate that Document.

Titles associated with session history entries need not have any relation with the current title of the Document. The title of a session history entry is intended to explain the state of the document at that point, so that the user can navigate the document's history.

URLs without associated state objects are added to the session history as the user (or script) navigates from page to page.

Each Document object in a browsing context's session history is associated with a unique History object which must all model the same underlying session history.

The history attribute of the Window interface must return the object implementing the History interface for that Window object's newest Document.

A state object is an object representing a user interface state.

Pages can add state objects to the session history. These are then returned to the script when the user (or script) goes back in the history, thus enabling authors to use the "navigation" metaphor even in one-page applications.

At any point, one of the entries in the session history is the current entry. This is the entry representing the active document of the browsing context. Which entry is the current entry is changed by the algorithms defined in this specification, e.g. during session history traversal.

The current entry is usually an entry for the address of the Document. However, it can also be one of the entries for state objects added to the history by that document.

An entry with persisted user state is one that also has user-agent defined state. This specification does not specify what kind of state can be stored.

For example, some user agents might want to persist the scroll position, or the values of form controls.

User agents that persist the value of form controls are encouraged to also persist their directionality (the value of the element's dir attribute). This prevents values from being displayed incorrectly after a history traversal when the user had originally entered the values with an explicit, non-default directionality.

Entries that consist of state objects share the same Document as the entry for the page that was active when they were added.

Contiguous entries that differ just by fragment identifier also share the same Document.

All entries that share the same Document (and that are therefore merely different states of one particular document) are contiguous by definition.

Each Document in a browsing context can also have a latest entry. This is the entry for that Document to which the browsing context's session history was most recently traversed. When a Document is created, it initially has no latest entry.

User agents may discard the Document objects of entries other than the current entry that are not referenced from any script, reloading the pages afresh when the user or script navigates back to such pages. This specification does not specify when user agents should discard Document objects and when they should cache them.

Entries that have had their Document objects discarded must, for the purposes of the algorithms given below, act as if they had not. When the user or script navigates back or forwards to a page which has no in-memory DOM objects, any other entries that shared the same Document object with it must share the new object as well.

The History interface

interface History {
  readonly attribute long length;
  readonly attribute any state;
  void go(optional long delta);
  void back();
  void forward();
  void pushState(any data, DOMString title, optional DOMString? url = null);
  void replaceState(any data, DOMString title, optional DOMString? url = null);
};

window . history . length

Returns the number of entries in the joint session history.

window . history . state

Returns the current state object.

window . history . go( [ delta ] )

Goes back or forward the specified number of steps in the joint session history.

A zero delta will reload the current page.

If the delta is out of range, does nothing.

window . history . back()

Goes back one step in the joint session history.

If there is no previous page, does nothing.

window . history . forward()

Goes forward one step in the joint session history.

If there is no next page, does nothing.

window . history . pushState(data, title [, url ] )

Pushes the given data onto the session history, with the given title, and, if provided and not null, the given URL.

window . history . replaceState(data, title [, url ] )

Updates the current entry in the session history to have the given data, title, and, if provided and not null, URL.

The joint session history of a top-level browsing context is the union of all the session histories of all browsing contexts of all the fully active Document objects that share that top-level browsing context, with all the entries that are current entries in their respective session histories removed except for the current entry of the joint session history.

The current entry of the joint session history is the entry that most recently became a current entry in its session history.

Entries in the joint session history are ordered chronologically by the time they were added to their respective session histories. Each entry has an index; the earliest entry has index 0, and the subsequent entries are numbered with consecutively increasing integers (1, 2, 3, etc).

Since each Document in a browsing context might have a different event loop, the actual state of the joint session history can be somewhat nebulous. For example, two sibling iframe elements could both traverse from one unique origin to another at the same time, so their precise order might not be well-defined; similarly, since they might only find out about each other later, they might disagree about the length of the joint session history.

All the getters and setters for attributes, and all the methods, defined on the History interface, when invoked on a History object associated with a Document that is not fully active, must throw a SecurityError exception instead of operating as described below.

The length attribute of the History interface must return the number of entries in the top-level browsing context's joint session history.

The actual entries are not accessible from script.

The state attribute of the History interface must return the last value it was set to by the user agent. Initially, its value must be null.

When the go(delta) method is invoked, if the argument to the method was omitted or has the value zero, the user agent must act as if the location.reload() method was called instead. Otherwise, the user agent must traverse the history by a delta whose value is the value of the method's argument.

When the back() method is invoked, the user agent must traverse the history by a delta −1.

When the forward()method is invoked, the user agent must traverse the history by a delta +1.

Each top-level browsing context has a session history traversal queue, initially empty, to which tasks can be added.

Each top-level browsing context, when created, must begin running the following algorithm, known as the session history event loop for that top-level browsing context, in parallel:

1. Wait until this top-level browsing context's session history traversal queue is not empty.

2. Pull the first task from this top-level browsing context's session history traversal queue, and execute it.

3. Return to the first step of this algorithm.

The session history event loop helps coordinate cross-browsing-context transitions of the joint session history: since each browsing context might, at any particular time, have a different event loop (this can happen if the user agent has more than one event loop per unit of related browsing contexts), transitions would otherwise have to involve cross-event-loop synchronisation.

To traverse the history by a delta delta, the user agent must append a task to this top-level browsing context's session history traversal queue, the task consisting of running the following steps:

1. Let delta be the argument to the method.

2. If the index of the current entry of the joint session history plus delta is less than zero or greater than or equal to the number of items in the joint session history, then abort these steps.

3. Let specified entry be the entry in the joint session history whose index is the sum of delta and the index of the current entry of the joint session history.

4. Let specified browsing context be the browsing context of the specified entry.

5. If the specified browsing context's active document's unload a document algorithm is currently running, abort these steps.

6. Queue a task that consists of running the following substeps. The relevant event loop is that of the specified browsing context's active document. The task source for the queued task is the history traversal task source.

   1. If there is an ongoing attempt to navigate specified browsing context that has not yet matured (i.e. it has not passed the point of making its Document the active document), then cancel that attempt to navigate the browsing context.

   2. If the specified browsing context's active document is not the same Document as the Document of the specified entry, then run these substeps:

      1. Fully exit fullscreen.

      2. Prompt to unload the active document of the specified browsing context. If the user refused to allow the document to be unloaded, then abort these steps.

      3. Unload the active document of the specified browsing context with the recycle parameter set to false.

   3. Traverse the history of the specified browsing context to the specified entry.

When the user navigates through a browsing context, e.g. using a browser's back and forward buttons, the user agent must traverse the history by a delta equivalent to the action specified by the user.

The pushState(data, title, url) method adds a state object entry to the history.

The replaceState(data, title, url) method updates the state object, title, and optionally the URL of the current entry in the history.

When either of these methods is invoked, the user agent must run the following steps:

1. Let cloned data be a structured clone of the specified data. If this throws an exception, then rethrow that exception and abort these steps.

2. If the third argument is not null, run these substeps:

   1. Resolve the value of the third argument, relative to the API base URL specified by the entry settings object.
   2. If that fails, throw a SecurityError exception and abort these steps.
   3. Compare the resulting parsed URL to the result of applying the URL parser algorithm to the document's address. If any component of these two URLs differ other than the path, query, and fragment components, then throw a SecurityError exception and abort these steps.
   4. If the origin of the resulting absolute URL is not the same as the origin of the responsible document specified by the entry settings object, and either the path or query components of the two parsed URLs compared in the previous step differ, throw a SecurityError exception and abort these steps. (This prevents sandboxed content from spoofing other pages on the same origin.)

   5. Let new URL be the resulting absolute URL.

   For the purposes of the comparisons in the above substeps, the path and query components can only be the same if the scheme component of both parsed URLs are relative schemes.

3. If the third argument is null, then let new URL be the URL of the current entry.

4. If the method invoked was the pushState() method:

   1. Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.

      This doesn't necessarily have to affect the user agent's user interface.

   2. Remove any tasks queued by the history traversal task source that are associated with any Document objects in the top-level browsing context's document family.

   3. If appropriate, update the current entry to reflect any state that the user agent wishes to persist. The entry is then said to be an entry with persisted user state.

   4. Add a state object entry to the session history, after the current entry, with cloned data as the state object, the given title as the title, and new URL as the URL of the entry.

   5. Update the current entry to be this newly added entry.

   Otherwise, if the method invoked was the replaceState() method:

   1. Update the current entry in the session history so that cloned data is the entry's new state object, the given title is the new title, and new URL is the entry's new URL.

5. If the current entry in the session history represents a non-GET request (e.g. it was the result of a POST submission) then update it to instead represent a GET request (or equivalent).

6. Set the document's address to new URL.

   Since this is neither a navigation of the browsing context nor a history traversal, it does not cause a hashchange event to be fired.

7. Set history.state to a structured clone of cloned data.

8. Let the latest entry of the Document of the current entry be the current entry.

The title is purely advisory. User agents might use the title in the user interface.

User agents may limit the number of state objects added to the session history per page. If a page hits the UA-defined limit, user agents must remove the entry immediately after the first entry for that Document object in the session history after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but as a LIFO buffer for navigation.)

<!DOCTYPE HTML>
<!-- this is http://example.com/line?x=5 -->
<title>Line Game - 5</title>
<p>You are at coordinate 5 on the line.</p>
<p>
 <a href="?x=6">Advance to 6</a> or
 <a href="?x=4">retreat to 4</a>?
</p>

<!DOCTYPE HTML>
<!-- this starts off as http://example.com/line?x=5 -->
<title>Line Game - 5</title>
<p>You are at coordinate <span id="coord">5</span> on the line.</p>
<p>
 <a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
 <a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
</p>
<script>
 var currentPage = 5; // prefilled by server
 function go(d) {
   setupPage(currentPage + d);
   history.pushState(currentPage, document.title, '?x=' + currentPage);
 }
 onpopstate = function(event) {
   setupPage(event.state);
 }
 function setupPage(page) {
   currentPage = page;
   document.title = 'Line Game - ' + currentPage;
   document.getElementById('coord').textContent = currentPage;
   document.links[0].href = '?x=' + (currentPage+1);
   document.links[0].textContent = 'Advance to ' + (currentPage+1);
   document.links[1].href = '?x=' + (currentPage-1);
   document.links[1].textContent = 'retreat to ' + (currentPage-1);
 }
</script>

<!DOCTYPE HTML>
<TITLE>Line</TITLE>
<SCRIPT>
 setInterval(function () { document.title = 'Line - ' + new Date(); }, 1000);
 var i = 1;
 function inc() {
   set(i+1);
   history.pushState(i, 'Line - ' + i);
 }
 function set(newI) {
   i = newI;
   document.forms.F.I.value = newI;
 }
</SCRIPT>
<BODY ONPOPSTATE="set(event.state)">
<FORM NAME=F>
State: <OUTPUT NAME=I>1</OUTPUT> <INPUT VALUE="Increment" TYPE=BUTTON ONCLICK="inc()">
</FORM>

The Location interface

Each Document object in a browsing context's session history is associated with a unique instance of a Location object.

document . location [ = value ]

window . location [ = value ]

Returns a Location object with the current page's location.

Can be set, to navigate to another page.

The location attribute of the Document interface must return the Location object for that Document object, if it is in a browsing context, and null otherwise.

The location attribute of the Window interface must return the Location object for that Window object's Document.

Location objects provide a representation of the address of the active document of their Document's browsing context, and allow the current entry of the browsing context's session history to be changed, by adding or replacing entries in the history object.

[Unforgeable] interface Location {
  void assign(DOMString url);
  void replace(DOMString url);
  void reload();

  [SameObject] readonly attribute DOMString[] ancestorOrigins;
};
Location implements URLUtils;

location . assign(url)

Navigates to the given page.

location . replace(url)

Removes the current page from the session history and navigates to the given page.

location . reload()

Reloads the current page.

location . ancestorOrigins

Returns an array values are the origins of the ancestor browsing contexts, from the parent browsing context to the top-level browsing context.

The relevant Document is the Location object's associated Document object's browsing context's active document.

When the assign(url) method is invoked, the UA must resolve the argument, relative to the API base URL specified by the entry settings object, and if that is successful, must navigate the browsing context to the specified url, with exceptions enabled. If the browsing context's session history contains only one Document, and that was the about:blank Document created when the browsing context was created, then the navigation must be done with replacement enabled.

When the replace(url) method is invoked, the UA must resolve the argument, relative to the API base URL specified by the entry settings object, and if that is successful, navigate the browsing context to the specified url with replacement enabled and exceptions enabled.

Navigation for the assign() and replace() methods must be done with the responsible browsing context specified by the incumbent settings object as the source browsing context.

If the resolving step of the assign() and replace() methods is not successful, then the user agent must instead throw a SyntaxError exception.

When the reload() method is invoked, the user agent must run the appropriate steps from the following list:

If the currently executing task is the dispatch of a resize event in response to the user resizing the browsing context

Repaint the browsing context and abort these steps.

If the browsing context's active document is an iframe srcdoc document

Reprocess the iframe attributes of the browsing context's browsing context container.

If the browsing context's active document has its reload override flag set

Perform an overridden reload, with the browsing context being navigated as the responsible browsing context.

Otherwise

Navigate the browsing context to the document's address with replacement enabled and exceptions enabled. The source browsing context must be the browsing context being navigated. This is a reload-triggered navigation.

When a user requests that the active document of a browsing context be reloaded through a user interface element, the user agent should navigate the browsing context to the same resource as that Document, with replacement enabled. In the case of non-idempotent methods (e.g. HTTP POST), the user agent should prompt the user to confirm the operation first, since otherwise transactions (e.g. purchases or database modifications) could be repeated. User agents may allow the user to explicitly override any caches when reloading. If browsing context's active document's reload override flag is set, then the user agent may instead perform an overridden reload rather than the navigation described in this paragraph (with the browsing context being reloaded as the source browsing context).

The Location interface also supports the URLUtils interface. [[!URL]]

When the object is created, and whenever the the address of the relevant Document changes, the user agent must invoke the object's URLUtils interface's set the input algorithm with the address of the relevant Document as the given value.

The object's URLUtils interface's get the base algorithm must return the API base URL specified by the entry settings object, if there is one, or null otherwise.

The object's URLUtils interface's query encoding is the document's character encoding.

When the object's URLUtils interface invokes its update steps with the string value, the user agent must run the following steps:

1. If any of the following conditions are met, let mode be normal navigation; otherwise, let it be replace navigation:

   • The Location object's relevant Document has completely loaded, or
   • In the task in which the algorithm is running, an activation behaviour is currently being processed whose click event was trusted, or
   • In the task in which the algorithm is running, the event listener for a trusted click event is being handled.

2. If mode is normal navigation, then act as if the assign() method had been called with value as its argument. Otherwise, act as if the replace() method had been called with value as its argument.

The ancestorOrigins attribute, on getting, must return a read only array whose values are determined as follows. The same object must be returned each time the attribute's value is obtained for any particular Location object.

1. Let output be an empty ordered list of strings.

2. Let current be the browsing context of the Document with which the Location object is associated.

3. Loop: If current has no parent browsing context, jump to the step labeled end.

4. Let current be current's parent browsing context.

5. Append the Unicode serialisation of current's active document's origin to output as a new value.

6. Return to the step labeled loop.

7. End: Let output be the values of the array, in the same order.

Implementation notes for session history

This section is non-normative.

The History interface is not meant to place restrictions on how implementations represent the session history to the user.

For example, session history could be implemented in a tree-like manner, with each page having multiple "forward" pages. This specification doesn't define how the linear list of pages in the history object are derived from the actual session history as seen from the user's perspective.

Similarly, a page containing two iframes has a history object distinct from the iframes' history objects, despite the fact that typical Web browsers present the user with just one "Back" button, with a session history that interleaves the navigation of the two inner frames and the outer page.

Security: It is suggested that to avoid letting a page "hijack" the history navigation facilities of a UA by abusing pushState(), the UA provide the user with a way to jump back to the previous page (rather than just going back to the previous state). For example, the back button could have a drop down showing just the pages in the session history, and not showing any of the states. Similarly, an aural browser could have two "back" commands, one that goes back to the previous state, and one that jumps straight back to the previous page.

In addition, a user agent could ignore calls to pushState() that are invoked on a timer, or from event listeners that are not triggered in response to a clear user action, or that are invoked in rapid succession.

Opening the input stream

The open() method comes in several variants with different numbers of arguments.

document = document . open( [ type [, replace ] ] )

Causes the Document to be replaced in-place, as if it was a new Document object, but reusing the previous object, which is then returned.

If the type argument is omitted or has the value "text/html", then the resulting Document has an HTML parser associated with it, which can be given data to parse using document.write(). Otherwise, all content passed to document.write() will be parsed as plain text.

If the replace argument is present and has the value "replace", the existing entries in the session history for the Document object are removed.

The method has no effect if the Document is still being parsed.

Throws an InvalidStateError exception if the Document is an XML document.

window = document . open( url, name, features [, replace ] )

Works like the window.open() method.

Document objects have an ignore-opens-during-unload counter, which is used to prevent scripts from invoking the document.open() method (directly or indirectly) while the document is being unloaded. Initially, the counter must be set to zero.

When called with two arguments (or fewer), the document.open() method must act as follows:

1. If the Document object is not flagged as an HTML document, throw an InvalidStateError exception and abort these steps.

2. If the Document object is not an active document, then abort these steps.

3. Let type be the value of the first argument.

4. If the second argument is an ASCII case-insensitive match for the value "replace", then let replace be true.

   Otherwise, if the browsing context's session history contains only one Document, and that was the about:blank Document created when the browsing context was created, and that Document has never had the unload a document algorithm invoked on it (e.g. by a previous call to document.open()), then let replace be true.

   Otherwise, let replace be false.

5. If the Document has an active parser whose script nesting level is greater than zero, then the method does nothing. Abort these steps and return the Document object on which the method was invoked.

   This basically causes document.open() to be ignored when it's called in an inline script found during parsing, while still letting it have an effect when called from a non-parser task such as a timer callback or event handler.

6. Similarly, if the Document's ignore-opens-during-unload counter is greater than zero, then the method does nothing. Abort these steps and return the Document object on which the method was invoked.

   This basically causes document.open() to be ignored when it's called from a beforeunload pagehide, or unload event handler while the Document is being unloaded.

7. Release the storage mutex.

8. Set the Document's salvageable state to false.

9. Prompt to unload the Document object. If the user refused to allow the document to be unloaded, then abort these steps and return the Document object on which the method was invoked.

10. Unload the Document object, with the recycle parameter set to true.

11. Abort the Document.

12. Unregister all event listeners registered on the Document node and its descendants.

13. Remove any tasks associated with the Document in any task source.

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

15. Replace the Document's singleton objects with new instances of those objects. (This includes in particular the Window, Location, History, ApplicationCache, and Navigator, objects, the various BarProp objects, the two Storage objects, the various HTMLCollection objects, and objects defined by other specifications, like Selection. It also includes all the Web IDL prototypes in the JavaScript binding, including the Document object's prototype.)

    The new Window object has a new environment settings object.

16. Change the document's character encoding to UTF-8.

17. If the Document is ready for post-load tasks, then set the Document object's reload override flag and set the Document's reload override buffer to the empty string.

18. Set the Document's salvageable state back to true.

19. Change the document's address to the address of the responsible document specified by the entry settings object.

20. If the Document's iframe load in progress flag is set, set the Document's mute iframe load flag.

21. Create a new HTML parser and associate it with the document. This is a script-created parser (meaning that it can be closed by the document.open() and document.close() methods, and that the tokenizer will wait for an explicit call to document.close() before emitting an end-of-file token). The encoding confidence is irrelevant.

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

23. If type is an ASCII case-insensitive match for the string "replace", then, for historical reasons, set it to the string "text/html".

    Otherwise:

    If the type string contains a U+003B SEMICOLON character (;), remove the first such character and all characters from it up to the end of the string.

    Strip leading and trailing whitespace from type.

24. If type is not now an ASCII case-insensitive match for the string "text/html", then act as if the tokenizer had emitted a start tag token with the tag name "pre" followed by a single U+000A LINE FEED (LF) character, then switch the HTML parser's tokenizer to the PLAINTEXT state.

25. Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.

    This doesn't necessarily have to affect the user agent's user interface.

26. Remove any tasks queued by the history traversal task source that are associated with any Document objects in the top-level browsing context's document family.

27. Remove any earlier entries that share the same Document.

28. If replace is false, then add a new entry, just before the last entry, and associate with the new entry the text that was parsed by the previous parser associated with the Document object, as well as the state of the document at the start of these steps. This allows the user to step backwards in the session history to see the page before it was blown away by the document.open() call. This new entry does not have a Document object, so a new one will be created if the session history is traversed to that entry.

29. Finally, set the insertion point to point at just before the end of the input stream (which at this point will be empty).

30. Return the Document on which the method was invoked.

The document.open() method does not affect whether a Document is ready for post-load tasks or completely loaded.

When called with four arguments, the open() method on the Document object must call the open() method on the Window object of the Document object, with the same arguments as the original call to the open() method, and return whatever that method returned. If the Document object has no Window object, then the method must throw an InvalidAccessError exception.

Closing the input stream

document . close()

Closes the input stream that was opened by the document.open() method.

Throws an InvalidStateError exception if the Document is an XML document.

The close() method must run the following steps:

1. If the Document object is not flagged as an HTML document, throw an InvalidStateError exception and abort these steps.

2. If there is no script-created parser associated with the document, then abort these steps.

3. Insert an explicit "EOF" character at the end of the parser's input stream.

4. If there is a pending parsing-blocking script, then abort these steps.

5. Run the tokenizer, processing resulting tokens as they are emitted, and stopping when the tokenizer reaches the explicit "EOF" character or spins the event loop.

document.write()

document . write(text...)

In general, adds the given string(s) to the Document's input stream.

This method has very idiosyncratic behaviour. In some cases, this method can affect the state of the HTML parser while the parser is running, resulting in a DOM that does not correspond to the source of the document (e.g. if the string written is the string "<plaintext>" or "<!--"). In other cases, the call can clear the current page first, as if document.open() had been called. In yet more cases, the method is simply ignored, or throws an exception. To make matters worse, the exact behaviour of this method can in some cases be dependent on network latency, which can lead to failures that are very hard to debug. For all these reasons, use of this method is strongly discouraged.

This method throws an InvalidStateError exception when invoked on XML documents.

Document objects have an ignore-destructive-writes counter, which is used in conjunction with the processing of script elements to prevent external scripts from being able to use document.write() to blow away the document by implicitly calling document.open(). Initially, the counter must be set to zero.

The document.write(...) method must act as follows:

1. If the method was invoked on an XML document, throw an InvalidStateError exception and abort these steps.

2. If the Document object is not an active document, then abort these steps.

3. If the insertion point is undefined and either the Document's ignore-opens-during-unload counter is greater than zero or the Document's ignore-destructive-writes counter is greater than zero, abort these steps.

4. If the insertion point is undefined, call the open() method on the document object (with no arguments). If the user refused to allow the document to be unloaded, then abort these steps. Otherwise, the insertion point will point at just before the end of the (empty) input stream.

5. Insert the string consisting of the concatenation of all the arguments to the method into the input stream just before the insertion point.

6. If the Document object's reload override flag is set, then append the string consisting of the concatenation of all the arguments to the method to the Document's reload override buffer.

7. If there is no pending parsing-blocking script, have the HTML parser process the characters that were inserted, one at a time, processing resulting tokens as they are emitted, and stopping when the tokenizer reaches the insertion point or when the processing of the tokenizer is aborted by the tree construction stage (this can happen if a script end tag token is emitted by the tokenizer).

   If the document.write() method was called from script executing inline (i.e. executing because the parser parsed a set of script tags), then this is a reentrant invocation of the parser.

8. Finally, return from the method.

document.writeln()

document . writeln(text...)

Adds the given string(s) to the Document's input stream, followed by a newline character. If necessary, calls the open() method implicitly first.

This method throws an InvalidStateError exception when invoked on XML documents.

The document.writeln(...) method, when invoked, must act as if the document.write() method had been invoked with the same argument(s), plus an extra argument consisting of a string containing a single line feed character (U+000A).

Simple dialogs

window . alert(message)

Displays a modal alert with the given message, and waits for the user to dismiss it.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

result = window . confirm(message)

Displays a modal OK/Cancel prompt with the given message, waits for the user to dismiss it, and returns true if the user clicks OK and false if the user clicks Cancel.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

result = window . prompt(message [, default] )

Displays a modal text field prompt with the given message, waits for the user to dismiss it, and returns the value that the user entered. If the user cancels the prompt, then returns null instead. If the second argument is present, then the given value is used as a default.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

Logic that depends on tasks or microtasks, such as media elements loading their media data, are stalled when these methods are invoked.

The alert(message) method, when invoked, must run the following steps:

1. If the event loop's termination nesting level is non-zero, optionally abort these steps.

2. Release the storage mutex.

3. Optionally, abort these steps. (For example, the user agent might give the user the option to ignore all alerts, and would thus abort at this step whenever the method was invoked.)

4. If the method was invoked with no arguments, then let message be the empty string; otherwise, let message be the method's first argument.

5. Show the given message to the user.

6. Optionally, pause while waiting for the user to acknowledge the message.

The confirm(message) method, when invoked, must run the following steps:

1. If the event loop's termination nesting level is non-zero, optionally abort these steps, returning false.

2. Release the storage mutex.

3. Optionally, return false and abort these steps. (For example, the user agent might give the user the option to ignore all prompts, and would thus abort at this step whenever the method was invoked.)

4. Show the given message to the user, and ask the user to respond with a positive or negative response.

5. Pause until the user responds either positively or negatively.

6. If the user responded positively, return true; otherwise, the user responded negatively: return false.

The prompt(message, default) method, when invoked, must run the following steps:

1. If the event loop's termination nesting level is non-zero, optionally abort these steps, returning null.

2. Release the storage mutex.

3. Optionally, return null and abort these steps. (For example, the user agent might give the user the option to ignore all prompts, and would thus abort at this step whenever the method was invoked.)

4. Show the given message to the user, and ask the user to either respond with a string value or abort. The response must be defaulted to the value given by default.

5. Pause while waiting for the user's response.

6. If the user aborts, then return null; otherwise, return the string that the user responded with.

Printing

window . print()

Prompts the user to print the page.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

When the print() method is invoked, if the Document is ready for post-load tasks, then the user agent must run the printing steps in parallel. Otherwise, the user agent must only set the print when loaded flag on the Document.

User agents should also run the printing steps whenever the user asks for the opportunity to obtain a physical form (e.g. printed copy), or the representation of a physical form (e.g. PDF copy), of a document.

The printing steps are as follows:

1. The user agent may display a message to the user or abort these steps (or both).

   For instance, a kiosk browser could silently ignore any invocations of the print() method.

   For instance, a browser on a mobile device could detect that there are no printers in the vicinity and display a message saying so before continuing to offer a "save to PDF" option.

2. The user agent must fire a simple event named beforeprint at the Window object of the Document that is being printed, as well as any nested browsing contexts in it.

   The beforeprint event can be used to annotate the printed copy, for instance adding the time at which the document was printed.

3. The user agent must release the storage mutex.

4. The user agent should offer the user the opportunity to obtain a physical form (or the representation of a physical form) of the document. The user agent may wait for the user to either accept or decline before returning; if so, the user agent must pause while the method is waiting. Even if the user agent doesn't wait at this point, the user agent must use the state of the relevant documents as they are at this point in the algorithm if and when it eventually creates the alternate form.

5. The user agent must fire a simple event named afterprint at the Window object of the Document that is being printed, as well as any nested browsing contexts in it.

   The afterprint event can be used to revert annotations added in the earlier event, as well as showing post-printing UI. For instance, if a page is walking the user through the steps of applying for a home loan, the script could automatically advance to the next step after having printed a form or other.

Dialogs implemented using separate documents with showModalDialog()

This feature is in the process of being removed from the Web platform. (This is a long process that takes many years.) Using the showModalDialog() API at this time is highly discouraged.

The showModalDialog(url, argument) method, when invoked, must cause the user agent to run the following steps:

1. Resolve url relative to the API base URL specified by the entry settings object.

   If this fails, then throw a SyntaxError exception and abort these steps.

2. If the event loop's termination nesting level is non-zero, optionally abort these steps, returning the empty string.

3. Release the storage mutex.

4. If the user agent is configured such that this invocation of showModalDialog() is somehow disabled, then return the empty string and abort these steps.

   User agents are expected to disable this method in certain cases to avoid user annoyance (e.g. as part of their popup blocker feature). For instance, a user agent could require that a site be white-listed before enabling this method, or the user agent could be configured to only allow one modal dialog at a time.

5. If the active sandboxing flag set of the active document of the responsible browsing context specified by the incumbent settings object has its sandboxed auxiliary navigation browsing context flag set, then return the empty string and abort these steps.

6. Let incumbent origin be the effective script origin specified by the incumbent settings object at the time the showModalDialog() method was called.

7. Let the list of background browsing contexts be a list of all the browsing contexts that:

   • are part of the same unit of related browsing contexts as the browsing context of the Window object on which the showModalDialog() method was called, and that
   • have an active document whose origin is the same as incumbent origin,

   ...as well as any browsing contexts that are nested inside any of the browsing contexts matching those conditions.

8. Disable the user interface for all the browsing contexts in the list of background browsing contexts. This should prevent the user from navigating those browsing contexts, causing events to be sent to those browsing context, or editing any content in those browsing contexts. However, it does not prevent those browsing contexts from receiving events from sources other than the user, from running scripts, from running animations, and so forth.

9. Create a new auxiliary browsing context, with the opener browsing context being the browsing context of the Window object on which the showModalDialog() method was called. The new auxiliary browsing context has no name.

   This browsing context's Documents' Window objects all implement the WindowModal interface.

10. Set all the flags in the new browsing context's popup sandboxing flag set that are set in the active sandboxing flag set of the active document of the responsible browsing context specified by the incumbent settings object. The responsible browsing context specified by the incumbent settings object must be set as the new browsing context's one permitted sandboxed navigator.

11. Let the dialog arguments of the new browsing context be set to the value of argument, or the undefined value if the argument was omitted.

12. Let the dialog arguments' origin be incumbent origin.

13. Let the return value of the new browsing context be the undefined value.

14. Let the return value origin be incumbent origin.

15. Navigate the new browsing context to the absolute URL that resulted from resolving url earlier, with replacement enabled, and with the responsible browsing context specified by the incumbent settings object as the source browsing context.

16. Spin the event loop until the new browsing context is closed. The user agent must allow the user to indicate that the browsing context is to be closed.

17. Reenable the user interface for all the browsing contexts in the list of background browsing contexts.

18. If the auxiliary browsing context's return value origin at the time the browsing context was closed was the same as incumbent origin, then let return value be the auxiliary browsing context's return value as it stood when the browsing context was closed.

    Otherwise, let return value be undefined.

19. Return return value.

The Window objects of Documents hosted by browsing contexts created by the above algorithm must also implement the WindowModal interface.

When this happens, the members of the WindowModal interface, in JavaScript environments, appear to actually be part of the Window interface (e.g. they are on the same prototype chain as the window.alert() method).

[NoInterfaceObject]
interface WindowModal {
  readonly attribute any dialogArguments;
  attribute any returnValue;
};

window . dialogArguments

Returns the argument argument that was passed to the showModalDialog() method.

window . returnValue [ = value ]

Returns the current return value for the window.

Can be set, to change the value that will be returned by the showModalDialog() method.

Such browsing contexts have associated dialog arguments, which are stored along with the dialog arguments' origin. These values are set by the showModalDialog() method in the algorithm above, when the browsing context is created, based on the arguments provided to the method.

The dialogArguments IDL attribute, on getting, must check whether its browsing context's active document's effective script origin is the same as the dialog arguments' origin. If it is, then the browsing context's dialog arguments must be returned unchanged. Otherwise, the IDL attribute must return undefined.

These browsing contexts also have an associated return value and return value origin. As with the previous two values, these values are set by the showModalDialog() method in the algorithm above, when the browsing context is created.

The returnValue IDL attribute, on getting, must check whether its browsing context's active document's effective script origin is the same as the current return value origin. If it is, then the browsing context's return value must be returned unchanged. Otherwise, the IDL attribute must return undefined. On setting, the attribute must set the return value to the given new value, and the return value origin to the browsing context's active document's effective script origin.

The window.close() method can be used to close the browsing context.

The Navigator object

The navigator attribute of the Window interface must return an instance of the Navigator interface, which represents the identity and state of the user agent (the client), and allows Web pages to register themselves as potential protocol and content handlers:

interface Navigator {
  // objects implementing this interface also implement the interfaces given below
};
Navigator implements NavigatorID;
Navigator implements NavigatorLanguage;
Navigator implements NavigatorOnLine;
Navigator implements NavigatorContentUtils;
Navigator implements NavigatorStorageUtils;
Navigator implements NavigatorPlugins;

These interfaces are defined separately so that other specifications can re-use parts of the Navigator interface.

[NoInterfaceObject, Exposed=(Window,Worker)]
interface NavigatorID {
  readonly attribute DOMString appCodeName; // constant "Mozilla"
  readonly attribute DOMString appName;
  readonly attribute DOMString appVersion;
  readonly attribute DOMString platform;
  readonly attribute DOMString product; // constant "Gecko"
  boolean taintEnabled(); // constant false
  readonly attribute DOMString userAgent;
  readonly attribute DOMString vendorSub;
};

[NoInterfaceObject, Exposed=(Window,Worker)]
interface NavigatorLanguage {
  readonly attribute DOMString? language;
  readonly attribute DOMString[] languages;
};

[NoInterfaceObject]
interface NavigatorContentUtils {
  // content handler registration
  void registerProtocolHandler(DOMString scheme, DOMString url, DOMString title);
  void registerContentHandler(DOMString mimeType, DOMString url, DOMString title);
  DOMString isProtocolHandlerRegistered(DOMString scheme, DOMString url);
  DOMString isContentHandlerRegistered(DOMString mimeType, DOMString url);
  void unregisterProtocolHandler(DOMString scheme, DOMString url);
  void unregisterContentHandler(DOMString mimeType, DOMString url);
};

[NoInterfaceObject]
interface NavigatorStorageUtils {
  readonly attribute boolean cookieEnabled;
  void yieldForStorageUpdates();
};

[NoInterfaceObject]
interface NavigatorPlugins {
  [SameObject] readonly attribute PluginArray plugins;
  [SameObject] readonly attribute MimeTypeArray mimeTypes;
  readonly attribute boolean javaEnabled;
};

interface PluginArray {
  void refresh(optional boolean reload = false);
  readonly attribute unsigned long length;
  getter Plugin? item(unsigned long index);
  getter Plugin? namedItem(DOMString name);
};

interface MimeTypeArray {
  readonly attribute unsigned long length;
  getter MimeType? item(unsigned long index);
  getter MimeType? namedItem(DOMString name);
};

interface Plugin {
  readonly attribute DOMString name;
  readonly attribute DOMString description;
  readonly attribute DOMString filename;
  readonly attribute unsigned long length;
  getter MimeType? item(unsigned long index);
  getter MimeType? namedItem(DOMString name);
};

interface MimeType {
  readonly attribute DOMString type;
  readonly attribute DOMString description;
  readonly attribute DOMString suffixes; // comma-separated
  readonly attribute Plugin enabledPlugin;
};

The External interface

The external attribute of the Window interface must return an instance of the External interface.

interface External {
  void AddSearchProvider(DOMString engineURL);
  unsigned long IsSearchProviderInstalled(DOMString engineURL);
};

For historical reasons, members on this interface are capitalized.

window . external . AddSearchProvider( url )

Adds the search engine described by the OpenSearch description document at url. [[!OPENSEARCH]]

The OpenSearch description document has to be on the same server as the script that calls this method.

installed = window . external . IsSearchProviderInstalled( url )

Returns a value based on comparing url to the URLs of the results pages of the installed search engines.

0

None of the installed search engines match url.

1

One or more installed search engines match url, but none are the user's default search engine.

2

The user's default search engine matches url.

The url is compared to the URLs of the results pages of the installed search engines using a prefix match. Only results pages on the same domain as the script that calls this method are checked.

Another way of exposing search engines using OpenSearch description documents is using a link element with the search link type.

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

1. Optionally, abort these steps. User agents may implement the method as a stub method that never does anything, or may arbitrarily ignore invocations with particular arguments for security, privacy, or usability reasons.

2. Resolve the value of the method's first argument relative to the API base URL specified by the entry settings object.

3. If this fails, abort these steps.

4. Process the resulting absolute URL as the URL to an OpenSearch description document. [[!OPENSEARCH]]

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

1. Optionally, return 0 and abort these steps. User agents may implement the method as a stub method that never returns a non-zero value, or may arbitrarily ignore invocations with particular arguments for security, privacy, or usability reasons.

2. If the origin specified by the entry settings object is an opaque identifier (i.e. it has no host component), then return 0 and abort these steps.

3. Let host1 be the host component of the origin specified by the entry settings object.

4. Resolve the scriptURL argument relative to the API base URL specified by the entry settings object.

5. If this fails, return 0 and abort these steps.

6. Let host2 be the host component of the resulting parsed URL.

7. If the longest suffix in the Public Suffix List that matches the end of host1 is different than the longest suffix in the Public Suffix List that matches the end of host2, then return 0 and abort these steps. [[!PSL]]

   If the next domain component of host1 and host2 after their common suffix are not the same, then return 0 and abort these steps.

8. Let search engines be the list of search engines known by the user agent and made available to the user by the user agent for which the resulting absolute URL is a prefix match of the search engine's URL, if any. For search engines registered using OpenSearch description documents, the URL of the search engine corresponds to the URL given in a Url element whose rel attribute is "results" (the default). [[!OPENSEARCH]]

9. If search engines is empty, return 0 and abort these steps.

10. If the user's default search engine (as determined by the user agent) is one of the search engines in search engines, then return 2 and abort these steps.

11. Return 1.