This is a snapshot of an early working draft and has therefore been superseded by the HTML standard.

This document will not be further updated.

HTML5

Draft Standard — Call For Comments — 27 October 2009

6.10 Session history and navigation

6.10.1 The session history of browsing contexts

The sequence of Documents in a browsing context is its session history.

History objects provide a representation of the pages in the session history of browsing contexts. Each browsing context, including nested browsing context, has a distinct session history.

Each Document object in a browsing context's session history is associated with a unique instance of the History object, although they all must 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 Document.

History objects represent their browsing context's session history as a flat list of session history entries. Each session history entry consists of either a URL or a state object, or both, and may in addition have a title, a Document object, form data, a scroll position, and other information associated with it.

This does not imply that the user interface need be linear. See the notes below.

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

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

Pages can add state objects between their entry in the session history and the next ("forward") entry. 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. The current entry is usually an entry for the location of the Document. However, it can also be one of the entries for state objects added to the history by that document.

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.

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.

6.10.2 The History interface

interface History {
  readonly attribute long length;
  void go(in optional long delta);
  void back();
  void forward();
  void pushState(in any data, in DOMString title, in optional DOMString url);
  void replaceState(in any data, in DOMString title, in optional DOMString url);
  void clearState();
};
window . history . length

Returns the number of entries in the joint session history.

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, the given URL.

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

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

window . history . clearState()

Removes all state objects for the current page from the session history.

The joint session history of a History object is the union of all the session histories of all browsing contexts of all the fully active Document objects that share the History object's 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 was the 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. (Since all these browsing contexts by definition share an event loop, there is always a well-defined sequential order in which their session histories had their entries added.) 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).

The length attribute of the History interface must return the number of entries in the joint session history.

The actual entries are not accessible from script.

The go(delta) method causes the UA to run the following steps:

  1. If the argument to the method was omitted or has the value zero, then act as if the location.reload() method was called instead, and abort these steps.

  2. Let delta be the argument to the method.

  3. 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 the user agent must do nothing.

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

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

  6. If the Document of the specified entry of the specified browsing context is not the same as the Document of the current entry of the specified browsing context, then release the storage mutex.

  7. 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 translate this action into the equivalent invocations of the history.go(delta) method on the various affected window objects.

Some of the other members of the History interface are defined in terms of the go() method, as follows:

Member Definition
back() Must do the same as go(-1)
forward() Must do the same as go(1)

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

The replaceState(data, title, url) method updates the current entry in the history to have a state object.

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

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

  2. If a third argument is specified, run these substeps:

    1. Resolve the value of the third argument, relative to the first script's base URL.
    2. If that fails, raise a SECURITY_ERR exception and abort these steps.
    3. Compare the resulting absolute URL to the document's address. If any part of these two URLs differ other than the <path>, <query>, and <fragment> components, then raise a SECURITY_ERR exception and abort these steps.

    For the purposes of the comparison in the above substeps, the <path> and <query> components can only be the same if the URLs use a hierarchical <scheme>.

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

    1. Remove from the session history any entries for the Document from the entry after the current entry up to the last entry in the session history that references the same Document object, if any. If the current entry is the last entry in the session history, or if there are no entries after the current entry that reference the same Document object, then no entries are removed.

    2. 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, if the third argument is present, the absolute URL that was found earlier in this algorithm as the URL of the entry.

    3. Update the current entry to be the 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, if the third argument is present, the absolute URL that was found earlier in this algorithm is the entry's new URL.

  4. If the third argument is present, set the document's current address to the absolute URL that was found earlier in this algorithm.

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

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

The clearState() method removes all the state objects for the Document object from the session history.

When this method is invoked, the user agent must remove from the session history all the entries from the first state object entry for that Document object up to the last entry that references that same Document object, if any.

Then, if the current entry was removed in the previous step, the current entry must be set to the last entry for that Document object in the session history.

Consider a game where the user can navigate along a line, such that the user is always at some coordinate, and such that the user can bookmark the page corresponding to a particular coordinate, to return to it later.

A static page implementing the x=5 position in such a game could look like the following:

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

The problem with such a system is that each time the user clicks, the whole page has to be reloaded. Here instead is another way of doing it, using script:

<!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)">Advance to 6</a> or
 <a href="?x=4" onclick="go(-1)">retreat to 4</a>?
</p>
<script>
 var currentPage = 5; // prefilled by server
 function go(d) {
   history.pushState(currentPage, 'Line Game - ' + currentPage, '?x=' + currentPage);
   setupPage(currentPage + d);
 }
 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>

In systems without script, this still works like the previous example. However, users that do have script support can now navigate much faster, since there is no network access for the same experience. Furthermore, contrary to the experience the user would have with just a naïve script-based approach, bookmarking and navigating the session history still work.

In the example above, the data argument to the pushState() method is the same information as would be sent to the server, but in a more convenient form, so that the script doesn't have to parse the URL each time the user navigates.

6.10.3 Activating state object entries

When an entry in the session history is activated (which happens during session history traversal), the user agent must run the following steps:

  1. If the entry is a state object entry, let state be a structured clone of that state object. Otherwise, let state be null.

  2. Run the appropriate steps according to the conditions described:

    If the current document readiness is set to the string "complete"

    Synchronously fire a popstate event on the Window object of the Document, using the PopStateEvent interface, with the state attribute set to the value of state. This event must bubble but not be cancelable and has no default action.

    Otherwise

    Let the Document's pending state object be state. (If there was already a pending state object, the previous one is discarded.)

    The event will then be fired just after the load event.

The pending state object must be initially null.


interface PopStateEvent : Event {
  readonly attribute any state;
  void initPopStateEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any stateArg);
};
event . state

Returns the information that was provided to pushState() or replaceState().

The initPopStateEvent() method must initialize the event in a manner analogous to the similarly-named method in the DOM Events interfaces. [DOMEVENTS]

The state attribute represents the context information for the event, or null, if the state represented is the initial state of the Document.

6.10.4 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 HTMLDocument 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 their document's current address, and allow the current entry of the browsing context's session history to be changed, by adding or replacing entries in the history object.

interface Location {
  stringifier readonly attribute DOMString href;
  void assign(in DOMString url);
  void replace(in DOMString url);
  void reload();

  // URL decomposition IDL attributes 
           attribute DOMString protocol;
           attribute DOMString host;
           attribute DOMString hostname;
           attribute DOMString port;
           attribute DOMString pathname;
           attribute DOMString search;
           attribute DOMString hash;

  // resolving relative URLs
  DOMString resolveURL(in DOMString url);
};
location . href [ = value ]

Returns the current page's location.

Can be set, to navigate to another page.

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.

url = location . resolveURL(url)

Resolves the given relative URL to an absolute URL.

The href attribute must return the current address of the associated Document object, as an absolute URL.

On setting, the user agent must act as if the assign() method had been called with the new value as its argument.

When the assign(url) method is invoked, the UA must resolve the argument, relative to the first script's base URL, and if that is successful, must navigate the browsing context to the specified url. 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 first script's base URL, and if that is successful, navigate the browsing context to the specified url with replacement enabled.

Navigation for the assign() and replace() methods must be done with the browsing context of the script that invoked the method 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 SYNTAX_ERR 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.

Otherwise

Navigate the browsing context to the the document's current address with replacement enabled. The source browsing context must be the browsing context being navigated.

When a user requests that the current page be reloaded through a user interface element, the user agent should navigate the browsing context to the same resource as 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.

The Location interface also has the complement of URL decomposition IDL attributes, protocol, host, port, hostname, pathname, search, and hash. These must follow the rules given for URL decomposition IDL attributes, with the input being the current address of the associated Document object, as an absolute URL (same as the href attribute), and the common setter action being the same as setting the href attribute to the new output value.


The resolveURL(url) method must resolve its url argument, relative to the first script's base URL, and if that succeeds, return the resulting absolute URL. If it fails, it must throw a SYNTAX_ERR exception instead.

6.10.4.1 Security

User agents must raise a SECURITY_ERR exception whenever any of the members of a Location object are accessed by scripts whose effective script origin is not the same as the Location object's associated Document's effective script origin, with the following exceptions:

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

6.11 Browsing the Web

Certain actions cause the browsing context to navigate to a new resource. Navigation always involves source browsing context, which is the browsing context which was responsible for starting the navigation.

For example, following a hyperlink, form submission, and the window.open() and location.assign() methods can all cause a browsing context to navigate.

A user agent may provide various ways for the user to explicitly cause a browsing context to navigate, in addition to those defined in this specification.

When a browsing context is navigated to a new resource, the user agent must run the following steps:

  1. If there is a preexisting attempt to navigate the browsing context, and the source browsing context is the same as the browsing context being navigated, and that attempt is currently running the unload a document algorithm, and the origin of the URL of the resource being loaded in that navigation is not the same origin as the origin of the URL of the resource being loaded in this navigation, then abort these steps without affecting the preexisting attempt to navigate the browsing context.

  2. If there is a preexisting attempt to navigate the browsing context, and either that attempt has not yet matured (i.e. it has not passed the point of making its Document the active document), or that navigation's resource is not to be fetched using HTTP GET or equivalent, or its resource's absolute URL differs from this attempt's by more than the presence, absence, or value of the <fragment> component, then cancel that preexisting attempt to navigate the browsing context.

  3. Cancel any preexisting attempt to navigate the browsing context.

  4. If the new resource is to be handled using a mechanism that does not affect the browsing context, e.g. ignoring the navigation request altogether because the specified scheme is not one of the supported protocols, then abort these steps and proceed with that mechanism instead.

  5. Prompt to unload the Document object. If the user refused to allow the document to be unloaded, then these steps must be aborted.

  6. If the new resource is to be handled by displaying some sort of inline content, e.g. an error message because the specified scheme is not one of the supported protocols, or an inline prompt to allow the user to select a registered handler for the given scheme, then display the inline content and abort these steps.

    In the case of a registered handler being used, the algorithm will be reinvoked with a new URL to handle the request.

  7. If the new resource is to be fetched using HTTP GET or equivalent, then check if there are any relevant application caches that are identified by a URL with the same origin as the URL in question, and that have this URL as one of their entries, excluding entries marked as foreign. If so, then the user agent must then get the resource from the most appropriate application cache of those that match.

    For example, imagine an HTML page with an associated application cache displaying an image and a form, where the image is also used by several other application caches. If the user right-clicks on the image and chooses "View Image", then the user agent could decide to show the image from any of those caches, but it is likely that the most useful cache for the user would be the one that was used for the aforementioned HTML page. On the other hand, if the user submits the form, and the form does a POST submission, then the user agent will not use an application cache at all; the submission will be made to the network.

    Otherwise, fetch the new resource, if it has not already been obtained.

    If the resource is being fetched using a method other than one equivalent to HTTP's GET, or, if the navigation algorithm was invoked as a result of the form submission algorithm, then the fetching algorithm must be invoked from the origin of the active document of the source browsing context, if any.

    If the browsing context being navigated is a child browsing context for an iframe or object element, then the fetching algorithm must be invoked from the iframe or object element's browsing context scope origin, if it has one.

  8. If fetching the resource is synchronous (i.e. for about:blank), then this must be synchronous, but if fetching the resource depends on external resources, as it usually does for URLs that use HTTP or other networking protocols, then at this point the user agents must yield to whatever script invoked the navigation steps, if they were invoked by script.

  9. If fetching the resource results in a redirect, return to the step labeled "fragment identifiers" with the new resource.

  10. Wait for one or more bytes to be available or for the user agent to establish that the resource in question is empty. During this time, the user agent may allow the user to cancel this navigation attempt or start other navigation attempts.

  11. If the resource was not fetched from an application cache, and was to be fetched using HTTP GET or equivalent, and its URL matches the fallback namespace of one or more relevant application caches, and the user didn't cancel the navigation attempt during the previous step, and the navigation attempt failed (e.g. the server returned a 4xx or 5xx status code or equivalent, or there was a DNS error), then:

    Let candidate be the fallback resource specified for the fallback namespace in question. If multiple application caches match, the user agent must use the fallback of the most appropriate application cache of those that match.

    If candidate is not marked as foreign, then the user agent must discard the failed load and instead continue along these steps using candidate as the resource. The document's address, if appropriate, will still be the originally requested URL, not the fallback URL, but the user agent may indicate to the user that the original page load failed, that the page used was a fallback resource, and what the URL of the fallback resource actually is.

  12. If the document's out-of-band metadata (e.g. HTTP headers), not counting any type information (such as the Content-Type HTTP header), requires some sort of processing that will not affect the browsing context, then perform that processing and abort these steps.

    Such processing might be triggered by, amongst other things, the following:

    • HTTP status codes (e.g. 204 No Content or 205 Reset Content)
    • HTTP Content-Disposition headers
    • Network errors

    HTTP 401 responses that do not include a challenge recognized by the user agent must be processed as if they had no challenge, e.g. rendering the entity body as if the response had been 200 OK.

    User agents may show the entity body of an HTTP 401 response even when the response do include a recognized challenge, with the option to login being included in a non-modal fashion, to enable the information provided by the server to be used by the user before authenticating. Similarly, user agents should allow the user to authenticate (in a non-modal fashion) against authentication challenges included in other responses such as HTTP 200 OK responses, effectively allowing resources to present HTTP login forms without requiring their use.

  13. Let type be the sniffed type of the resource.

  14. If the user agent has been configured to process resources of the given type using some mechanism other than rendering the content in a browsing context, then skip this step. Otherwise, if the type is one of the following types, jump to the appropriate entry in the following list, and process the resource as described there:

    "text/html"
    Follow the steps given in the HTML document section, and abort these steps.
    Any type ending in "+xml"
    "application/xml"
    "text/xml"
    Follow the steps given in the XML document section. If that section determines that the content is not to be displayed as a generic XML document, then proceed to the next step in this overall set of steps. Otherwise, abort these steps.
    "text/plain"
    Follow the steps given in the plain text file section, and abort these steps.
    A supported image type
    Follow the steps given in the image section, and abort these steps.
    A type that will use an external application to render the content in the browsing context
    Follow the steps given in the plugin section, and abort these steps.

    Setting the document's address: If there is no override URL, then any Document created by these steps must have its address set to the URL that was originally to be fetched, ignoring any other data that was used to obtain the resource (e.g. the entity body in the case of a POST submission is not part of the document's address, nor is the URL of the fallback resource in the case of the original load having failed and that URL having been found to match a fallback namespace). However, if there is an override URL, then any Document created by these steps must have its address set to that URL instead.

    An override URL is set when dereferencing a javascript: URL.

    Creating a new Document object: When a Document is created as part of the above steps, a new set of views along with the associated Window object must be created and associated with the Document, with one exception: if the browsing context's only entry in its session history is the about:blank Document that was added when the browsing context was created, and navigation is occurring with replacement enabled, and that Document has the same origin as the new Document, then the Window object and associated views of that Document must be used instead, and the document attribute of the AbstractView objects of those views must be changed to point to the new Document instead.

  15. Otherwise, the document's type is such that the resource will not affect the browsing context, e.g. because the resource is to be handed to an external application. Process the resource appropriately.


Some of the sections below, to which the above algorithm defers in certain cases, require the user agent to update the session history with the new page. When a user agent is required to do this, it must queue a task to run the following steps:

  1. Unload the Document object of the current entry, with the recycle parameter set to false.

  2. If the navigation was initiated for entry update of an entry
    1. Replace the entry being updated with a new entry representing the new resource and its Document object and related state. The user agent may propagate state from the old entry to the new entry (e.g. scroll position).

    2. Traverse the history to the new entry.

    Otherwise
    1. Remove all the entries after the current entry in the browsing context's Document object's History object.

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

    2. Append a new entry at the end of the History object representing the new resource and its Document object and related state.

    3. Traverse the history to the new entry. If the navigation was initiated with replacement enabled, then the traversal must itself be initiated with replacement enabled.

  3. The navigation algorithm has now matured.

  4. Fragment identifier loop: Wait for a user-agent-defined amount of time, as desired by the user agent implementor. (This is intended to allow the user agent to optimize the user experience in the face of performance concerns.)

  5. If the Document object has no parser, or its parser has stopped parsing, or the user agent has reason to believe the user is no longer interested in scrolling to the fragment identifier, then abort these steps.

  6. Scroll to the fragment identifier given in the document's current address. If this fails to find an indicated part of the document, then return to the first step of these substeps.

The task source for this task is the networking task source.

6.11.2 Page load processing model for HTML files

When an HTML document is to be loaded in a browsing context, the user agent must create a Document object, mark it as being an HTML document, create an HTML parser, associate it with the document, and begin to use the bytes provided for the document as the input stream for that parser.

The input stream converts bytes into characters for use in the tokenizer. This process relies, in part, on character encoding information found in the real Content-Type metadata of the resource; the "sniffed type" is not used for this purpose.

When no more bytes are available, an EOF character is implied, which eventually causes a load event to be fired.

After creating the Document object, but before any script execution, certainly before the parser stops, the user agent must update the session history with the new page.

Application cache selection happens in the HTML parser.

6.11.3 Page load processing model for XML files

When faced with displaying an XML file inline, user agents must first create a Document object, following the requirements of the XML and Namespaces in XML recommendations, RFC 3023, DOM3 Core, and other relevant specifications. [XML] [XMLNS] [RFC3023] [DOMCORE]

The actual HTTP headers and other metadata, not the headers as mutated or implied by the algorithms given in this specification, are the ones that must be used when determining the character encoding according to the rules given in the above specifications. Once the character encoding is established, the document's character encoding must be set to that character encoding.

If the root element, as parsed according to the XML specifications cited above, is found to be an html element with an attribute manifest, then, as soon as the element is inserted into the document, the user agent must resolve the value of that attribute relative to that element, and if that is successful, must run the application cache selection algorithm with the resulting absolute URL with any <fragment> component removed as the manifest URL, and passing in the newly-created Document. Otherwise, if the attribute is absent or resolving it fails, then as soon as the root element is inserted into the document, the user agent must run the application cache selection algorithm with no manifest, and passing in the Document.

Because the processing of the manifest attribute happens only once the root element is parsed, any URLs referenced by processing instructions before the root element (such as <?xml-stylesheet?> and <?xbl?> PIs) will be fetched from the network and cannot be cached.

User agents may examine the namespace of the root Element node of this Document object to perform namespace-based dispatch to alternative processing tools, e.g. determining that the content is actually a syndication feed and passing it to a feed handler. If such processing is to take place, abort the steps in this section, and jump to the next step (labeled "non-document content") in the navigate steps above.

Otherwise, then, with the newly created Document, the user agents must update the session history with the new page. User agents may do this before the complete document has been parsed (thus achieving incremental rendering), and must do this before any scripts are to be executed.

Error messages from the parse process (e.g. XML namespace well-formedness errors) may be reported inline by mutating the Document.

6.11.4 Page load processing model for text files

When a plain text document is to be loaded in a browsing context, the user agent should create a Document object, mark it as being an HTML document, create an HTML parser, associate it with the document, act as if the tokenizer had emitted a start tag token with the tag name "pre", switch the HTML parser's tokenizer to the PLAINTEXT state, and begin to pass the stream of characters in the plain text document to that tokenizer.

The rules for how to convert the bytes of the plain text document into actual characters are defined in RFC 2046, RFC 2646, and subsequent versions thereof. [RFC2046] [RFC2646]

The document's character encoding must be set to the character encoding used to decode the document.

Upon creation of the Document object, the user agent must run the application cache selection algorithm with no manifest, and passing in the newly-created Document.

When no more characters are available, an EOF character is implied, which eventually causes a load event to be fired.

After creating the Document object, but potentially before the page has finished parsing, the user agent must update the session history with the new page.

User agents may add content to the head element of the Document, e.g. linking to a style sheet or an XBL binding, providing script, giving the document a title, etc.

6.11.5 Page load processing model for images

When an image resource is to be loaded in a browsing context, the user agent should create a Document object, mark it as being an HTML document, append an html element to the Document, append a head element and a body element to the html element, append an img to the body element, and set the src attribute of the img element to the address of the image.

Then, the user agent must act as if it had stopped parsing.

Upon creation of the Document object, the user agent must run the application cache selection algorithm with no manifest, and passing in the newly-created Document.

After creating the Document object, but potentially before the page has finished fully loading, the user agent must update the session history with the new page.

User agents may add content to the head element of the Document, or attributes to the img element, e.g. to link to a style sheet or an XBL binding, to provide a script, to give the document a title, etc.

6.11.6 Page load processing model for content that uses plugins

When a resource that requires an external resource to be rendered is to be loaded in a browsing context, the user agent should create a Document object, mark it as being an HTML document, append an html element to the Document, append a head element and a body element to the html element, append an embed to the body element, and set the src attribute of the embed element to the address of the resource.

Then, the user agent must act as if it had stopped parsing.

Upon creation of the Document object, the user agent must run the application cache selection algorithm with no manifest, and passing in the newly-created Document.

After creating the Document object, but potentially before the page has finished fully loading, the user agent must update the session history with the new page.

User agents may add content to the head element of the Document, or attributes to the embed element, e.g. to link to a style sheet or an XBL binding, or to give the document a title.

If the sandboxed plugins browsing context flag is set on the browsing context, the synthesized embed element will fail to render the content.

6.11.7 Page load processing model for inline content that doesn't have a DOM

When the user agent is to display a user agent page inline in a browsing context, the user agent should create a Document object, mark it as being an HTML document, and then either associate that Document with a custom rendering that is not rendered using the normal Document rendering rules, or mutate that Document until it represents the content the user agent wants to render.

Once the page has been set up, the user agent must act as if it had stopped parsing.

Upon creation of the Document object, the user agent must run the application cache selection algorithm with no manifest, passing in the newly-created Document.

After creating the Document object, but potentially before the page has been completely set up, the user agent must update the session history with the new page.

6.11.8 Navigating to a fragment identifier

When a user agent is supposed to navigate to a fragment identifier, then the user agent must queue a task to run the following steps:

  1. Remove all the entries after the current entry in the browsing context's Document object's History object.

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

  2. Append a new entry at the end of the History object representing the new resource and its Document object and related state, and set its URL to the address to which the user agent was navigating. (This will be the same as the document's address, but with a new fragment identifier.)

  3. Traverse the history to the new entry. This will scroll to the fragment identifier given in the document's current address.

If the scrolling fails because the relevant ID has not yet been parsed, then the original navigation algorithm will take care of the scrolling instead, as the last few steps of its update the session history with the new page algorithm.


When the user agent is required to scroll to the fragment identifier, it must change the scrolling position of the document, or perform some other action, such that the indicated part of the document is brought to the user's attention. If there is no indicated part, then the user agent must not scroll anywhere.

The indicated part of the document is the one that the fragment identifier, if any, identifies. The semantics of the fragment identifier in terms of mapping it to a specific DOM Node is defined by the specification that defines the MIME type used by the Document (for example, the processing of fragment identifiers for XML MIME types is the responsibility of RFC3023).

For HTML documents (and the text/html MIME type), the following processing model must be followed to determine what the indicated part of the document is.

  1. Parse the URL, and let fragid be the <fragment> component of the URL.

  2. If fragid is the empty string, then the indicated part of the document is the top of the document.

  3. Let decoded fragid be the result of expanding any sequences of percent-encoded octets in fragid that are valid UTF-8 sequences into Unicode characters as defined by UTF-8. If any percent-encoded octets in that string are not valid UTF-8 sequences, then skip this step and the next one.

  4. If this step was not skipped and there is an element in the DOM that has an ID exactly equal to decoded fragid, then the first such element in tree order is the indicated part of the document; stop the algorithm here.

  5. If there is an a element in the DOM that has a name attribute whose value is exactly equal to fragid (not decoded fragid), then the first such element in tree order is the indicated part of the document; stop the algorithm here.

  6. Otherwise, there is no indicated part of the document.

For the purposes of the interaction of HTML with Selectors' :target pseudo-class, the target element is the indicated part of the document, if that is an element; otherwise there is no target element. [SELECTORS]

6.11.9 History traversal

When a user agent is required to traverse the history to a specified entry, optionally with replacement enabled, the user agent must act as follows:

  1. If there is no longer a Document object for the entry in question, the user agent must navigate the browsing context to the location for that entry to perform an entry update of that entry, and abort these steps. The "navigate" algorithm reinvokes this "traverse" algorithm to complete the traversal, at which point there is a Document object and so this step gets skipped. The navigation must be done using the same source browsing context as was used the first time this entry was created. (This can never happen with replacement enabled.)

  2. If appropriate, update the current entry in the browsing context's Document object's History object to reflect any state that the user agent wishes to persist. The entry is then said to be an entry with persisted user state.

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

  3. If the specified entry has a different Document object than the current entry then the user agent must run the following substeps:

    1. If the browsing context is a top-level browsing context (and not an auxiliary browsing context), and the origin of the Document of the specified entry is not the same as the origin of the Document of the current entry, then the following sub-sub-steps must be run:
      1. The current browsing context name must be stored with all the entries in the history that are associated with Document objects with the same origin as the active document and that are contiguous with the current entry.
      2. The browsing context's browsing context name must be unset.
    2. The user agent must make the specified entry's Document object the active document of the browsing context.
    3. If the specified entry has a browsing context name stored with it, then the following sub-sub-steps must be run:
      1. The browsing context's browsing context name must be set to the name stored with the specified entry.
      2. Any browsing context name stored with the entries in the history that are associated with Document objects with the same origin as the new active document, and that are contiguous with the specified entry, must be cleared.
    4. If the specified entry's Document has any input elements whose resulting autocompletion state is off, invoke the reset algorithm of each of those elements.

    5. If the the current document readiness of the specified entry's Document is "complete", queue a task to fire a simple event named pageshow at that Document's Window object.

  4. Set the document's current address to the URL of the specified entry.

  5. If the specified entry has a URL that differs from the current entry's only by its fragment identifier, and the two share the same Document object, then let hash changed be true. Otherwise, let hash changed be false.

  6. If the traversal was initiated with replacement enabled, remove the entry immediately before the specified entry in the session history.

  7. If hash changed is true, then, if the new URL has a fragment identifier, scroll to the fragment identifier.

  8. If the entry is an entry with persisted user state, the user agent may update aspects of the document view, for instance the scroll position or values of form fields, that it had previously recorded.

  9. If the specified entry is a state object or the first entry for a Document, the user agent must activate that entry.

  10. If hash changed is true, then synchronously fire a simple event with the name hashchange at the browsing context's Window object.

  11. The current entry is now the specified entry.

6.11.10 Unloading documents

A Document has a salvageable state, which is initially true.


When a user agent is to prompt to unload a document, it must run the following steps.

  1. Let event be a new BeforeUnloadEvent event object with the name beforeunload, which does not bubble but is cancelable.

  2. Dispatch event at the Document's Window object.

  3. If any event listeners were triggered by the previous step, then set the Document's salvageable state to false.

  4. If the returnValue attribute of the event object is not the empty string, or if the event was canceled, then the user agent should ask the user to confirm that they wish to unload the document.

    The prompt shown by the user agent may include the string of the returnValue attribute, or some leading subset thereof. (A user agent may want to truncate the string to 1024 characters for display, for instance.)

    The user agent must pause while waiting for the user's response.

    If the user did not confirm the page navigation, then the user agent refused to allow the document to be unloaded.


When a user agent is to unload a document, it must run the following steps. These steps are passed an argument, recycle, which is either true or false, indicating whether the Document object is going to be re-used. (This is set by the document.open() method.)

  1. Fire a simple event named pagehide at the Document's Window object.

  2. Fire a simple event named unload at the Document's Window object.

  3. If any event listeners were triggered by the previous step, then set the Document object's salvageable state to false.

  4. If there are any outstanding transactions that have callbacks that involve scripts whose global object is the Document's Window object, roll them back (without invoking any of the callbacks) and set salvageable to false.

  5. Empty the Document's Window's list of active timeouts and its list of active intervals.

  6. If salvageable and recycle are both false, discard the Document.

6.11.10.1 Event definition
interface BeforeUnloadEvent : Event {
           attribute DOMString returnValue;
};
event . returnValue [ = value ]

Returns the current return value of the event (the message to show the user).

Can be set, to update the message.

There are no BeforeUnloadEvent-specific initialization methods.

The returnValue attribute represents the message to show the user. When the event is created, the attribute must be set to the empty string. On getting, it must return the last value it was set to. On setting, the attribute must be set to the new value.

6.11.11 Aborting a document load

If the user cancels any instance of the fetching algorithm in the context of a Document in a browsing context, then, if that Document is an active document, the user agent must fire a simple event named abort at that Document's Window object.