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 contexts, 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 a URL and
optionally a state object, 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.
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.
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.
State objects are intended to
be used for two main purposes: first, storing a preparsed
description of the state in the URL so that in the
simple case an author doesn't have to do the parsing (though one
would still need the parsing for handling URLs passed around by users, so it's only a minor
optimization), and second, so that the author can store state that
one wouldn't store in the URL because it only applies to the current
Document instance and it would have to be reconstructed
if a new Document were opened.
An example of the latter would be something like keeping track of
the precise coordinate from which a pop-up div was made
to animate, so that if the user goes back, it can be made to animate
to the same location. Or alternatively, it could be used to keep a
pointer into a cache of data that would be fetched from the server
based on the information in the URL, so that when going
back and forward, the information doesn't have to be fetched
again.
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 or that
Document that was most the recently traversed to. 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.
History interfaceinterface 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);
};
history . lengthReturns the number of entries in the joint session history.
history . stateReturns the current state object.
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.
history . back()Goes back one step in the joint session history.
If there is no previous page, does nothing.
history . forward()Goes forward one step in the joint session history.
If there is no next page, does nothing.
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.
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 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 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 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.
To traverse the history by a delta delta, the user agent must queue a task to run the following steps. The task source for the queued task is the history traversal task source.
Let delta be the argument to the method.
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.
If the Document's unload a document algorithm is currently
running, abort these steps.
If there is an ongoing attempt to navigate the 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.
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.
Let specified browsing context be the browsing context of the specified entry.
If the specified browsing context's active document is not
the same Document as the Document of the specified
entry, then run these substeps:
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.
Unload the active document of the specified browsing context with the recycle parameter set to false.
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:
Let cloned data be a structured clone of the specified data. If this throws an exception, then rethrow that exception and abort these steps.
If the third argument is not null, run these substeps:
SecurityError exception and abort these steps.SecurityError exception and abort these steps.SecurityError exception
and abort these steps. (This prevents sandboxed content from spoofing other pages on the same
origin.)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.
If the third argument is null, then let new URL be the URL of the current entry.
If the method invoked was the pushState()
method:
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.
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.
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.
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.
Update the current entry to be this newly added entry.
Otherwise, if the method invoked was the replaceState() method:
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.
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).
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.
Set history.state to a structured clone
of cloned data.
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.)
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); 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>
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.
Applications might not use the same title for a session history entry as the
value of the document's title element at that time. For example, here is a simple
page that shows a block in the title element. Clearly, when navigating backwards to
a previous state the user does not go back in time, and therefore it would be inappropriate to
put the time in the session history title.
<!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>
Location interfaceEach Document object in a browsing context's session history is
associated with a unique instance of a Location object.
location [ = value ]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();
};
Location implements URLUtils;
assign(url)Navigates to the given page.
replace(url)Removes the current page from the session history and navigates to the given page.
reload()Reloads the current page.
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 entry 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 entry 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 incumbent script 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:
resize event in response to the user resizing the browsing
contextRepaint the browsing context and abort these steps.
iframe srcdoc documentReprocess the iframe
attributes of the browsing context's browsing context
container.
Perform an overridden reload.
Navigate the browsing context to the document's address with replacement enabled. The source browsing context must be the browsing context being navigated.
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.
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 element's URLUtils interface's set the
input algorithm with the address of the
relevant Document as the given value.
The element's URLUtils interface's get the
base algorithm must return the entry script's base URL, if there is one, or null otherwise.
The element's URLUtils interface's query
encoding is the document's character encoding.
When the element's URLUtils interface invokes its update steps with the string value, the user
agent must run the following steps:
If any of the following conditions are met, let mode be normal navigation; otherwise, let it be replace navigation:
Location object's relevant Document has
completely loaded, orclick event was trusted,
orclick event is being handled.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.
User agents must throw a SecurityError exception whenever any
properties of a Location object are accessed when the entry script's
effective script origin is not the same as the
Location object's associated Document's browsing context's
active document's effective script origin, with the following
exceptions:
href setter, if the entry script's
script's browsing context is allowed to navigate the browsing
context with which the Location object is associated
replace() method, if the entry
script's script's browsing context is allowed to navigate the
browsing context with which the Location object is associated
Location object or indirectly via
one of those properties (e.g. toString(), which is defined via the stringifier keyword), if the entry script's effective script
origin is the same origin as the Location object's associated
Document's effective script origin
When the entry script's effective script origin is not the same
origin as the Location object's associated Document's
effective script origin, attempts to access that Location object's
methods or attributes must cause the user agent to act as if any changes to the
Location object's properties, getters, setters, etc, were not present.
For members that return objects (including function objects), each distinct effective
script origin that is not the same origin as the Location 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 script's global
object is the Location object's Document's Window
object).
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.
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:
Release the storage mutex.
If the source browsing context is not the same as the browsing context being navigated, and the source browsing context is not one of the ancestor browsing contexts of the browsing context being navigated, and the browsing context being navigated is not a top-level browsing context, and the source browsing context's active document's active sandboxing flag set has its sandboxed navigation browsing context flag set, then abort these steps.
Otherwise, if the browsing context being navigated is a top-level browsing
context, and is one of the ancestor browsing
contexts of the source browsing context, and the source browsing
context's Document's active sandboxing flag set has its
sandboxed top-level navigation browsing context flag set, then abort these
steps.
Otherwise, if the browsing context being navigated is a top-level browsing
context, and is not one of the ancestor browsing
contexts of the source browsing context, and the source browsing
context's Document's active sandboxing flag set has its
sandboxed navigation browsing context flag set, and the source browsing
context is not the one permitted sandboxed navigator of the browsing
context being navigated, then abort these steps.
In all of these cases, the user agent may additionally offer to open the new resource in a new top-level browsing context or in the top-level browsing context of the source browsing context, at the user's option, in which case the user agent must navigate that designated top-level browsing context to the new resource as if the user had requested it independently.
Doing so, however, can be dangerous, as it means that the user is overriding the author's explicit request to sandbox the content.
If the source browsing context is the same as the browsing context being navigated, and this browsing context has its seamless browsing context flag set, and the browsing context being navigated was not chosen using an explicit self-navigation override, then find the nearest ancestor browsing context that does not have its seamless browsing context flag set, and continue these steps as if that browsing context was the one that was going to be navigated instead.
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.
If a task queued by the traverse the history by a delta algorithm is running the unload a document algorithm for the active document of the browsing context being navigated, then abort these steps without affecting the unload a document algorithm or the aforementioned history traversal task.
If the prompt to unload a document algorithm is being run for the active document of the browsing context being navigated, then abort these steps without affecting the prompt to unload a document algorithm.
Let gone async be false.
If gone async is false, cancel any preexisting but not yet mature attempt to navigate the browsing
context, including canceling any instances of the fetch algorithm started by
those attempts. If one of those attempts has already created a new Document object, abort that Document also. (Navigation attempts that have matured already have session history entries, and are
therefore handled during the update the session history with the new page algorithm,
later.)
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.
If gone async is false, prompt
to unload the Document object. If the user refused to allow the
document to be unloaded, then abort these steps.
If this instance of the navigation algorithm gets canceled while this step is running, the prompt to unload a document algorithm must nonetheless be run to completion.
If gone async is false, abort the active document of the browsing context.
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.
If the resource has already been obtained (e.g. because it is being used to populate an
object element's new child browsing context), then skip this step.
Otherwise:
If the new resource is to be fetched using HTTP GET or equivalent, and there are 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, and whose mode is fast, and the user agent is not in a mode where it will avoid using application caches then fetch 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, with the manual redirect flag set.
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.
If the browsing context is a nested browsing context, then in the
time between the fetch algorithm being started by this step, and either the
creation of a Document object or the canceling of the fetch or navigation algorithms, the browsing context must be put in
the delaying load events mode.
If gone async is false, return to whatever algorithm invoked the navigation steps and continue running these steps asynchronously.
Let gone async be true.
If fetching the resource results in a redirect, and either the URL of the target of the redirect has the same origin as the original resource, or the resource is being obtained using the POST method or a safe method (in HTTP terms), return to the step labeled fragment identifiers with the new resource, except that if the URL of the target of the redirect does not have a fragment identifier and the URL of the resource that led to the redirect does, then the fragment identifier of the resource that led to the redirect must be propagated to the URL of the target of the redirect.
So for instance, if the original URL was "http://example.com/#!sample" and "http://example.com/" is
found to redirect to "https://example.com/", the URL of the new resource
will be "https://example.com/#!sample".
Otherwise, if fetching the resource results in a redirect but the URL of the target of the redirect does not have the same origin as the original resource and the resource is being obtained using a method that is neither the POST method nor a safe method (in HTTP terms), then abort these steps. The user agent may indicate to the user that the navigation has been aborted for security reasons.
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.
Fallback in prefer-online mode: If the resource was not fetched from an application cache, and was to be fetched using HTTP GET or equivalent, and there are 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, and whose mode is prefer-online, and the user didn't cancel the navigation attempt during the earlier 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 resource identified by the URL in question from 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 user agent may indicate to the user that the original page load failed, and that the page used was a previously cached resource.
This does not affect the address of the resource from which Request-URIs are obtained, as used to set the document's referrer in the create a Document object steps below; they still use the value as computed by the original fetch algorithm.
Fallback for fallback entries: 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 most appropriate application cache of those that match does not have an entry in its online whitelist that has the same origin as the resource's URL and that is a prefix match for the resource's URL, 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.
This does not affect the address of the resource from which Request-URIs are obtained, as used to set the document's referrer in the create a Document object steps below; they still use the value as computed by the original fetch algorithm.
Resource handling: If the resource'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:
Responses with HTTP Content-Disposition headers
specifying the attachment disposition type must be handled as a
download.
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 does 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.
Let type be the sniffed type of the resource.
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"application/xml"text/xml"image/svg+xml"application/xhtml+xml"+xml" that is not an explicitly supported XML typetext/plain"multipart/x-mixed-replace"An explicitly supported XML type is one for which the user agent is configured to
use an external application to render the content (either a plugin rendering
directly in the browsing context, or a separate application), or one for which the
user agent has dedicated processing rules (e.g. a Web browser with a built-in Atom feed viewer
would be said to explicitly support the application/atom+xml MIME type), or one for
which the user agent has a dedicated handler (e.g. one registered using registerContentHandler()).
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 and when performing
an overridden reload.
Creating a new Document object: when
a Document is created as part of the above steps, the user agent must additionally
run the following algorithm as part of creating the new object:
Create a new Window object, and associate it 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 use the Window object of that
Document instead, and change the document
attribute of the Window object to point to the new Document.
Set the document's referrer to the address of the resource from which Request-URIs are obtained as determined when the fetch algorithm obtained the resource, if that algorithm was used and determined such a value; otherwise, set it to the empty string.
Implement the sandboxing for the Document.
If the active sandboxing flag set of the Document's
browsing context or any of its ancestor
browsing contexts (if any) have the sandboxed fullscreen browsing context
flag set, then skip this step.
If the Document's browsing context has a browsing context
container and either it is not an iframe element, or it does not have the
allowfullscreen attribute specified, or its
Document does not have the fullscreen enabled flag set, then also
skip this step.
Otherwise, set the Document's fullscreen enabled flag.
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 or because it is an unknown type that will be processed as a download. 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 (associated with the Document
object of the current entry, not the new one) to run the following steps:
Unload the Document object of the
current entry, with the recycle parameter set to false.
If this instance of the navigation algorithm is canceled while this step is running the unload a document algorithm, then the unload a document algorithm must be allowed to run to completion, but this instance of the navigation algorithm must not run beyond this step. (In particular, for instance, the cancelation of this algorithm does not abort any event dispatch or script execution occurring as part of unloading the document or its descendants.)
Replace the Document of the entry being updated, and any other entries
that referenced the same document as that entry, with the new Document.
Traverse the history to the new entry.
This can only happen if the entry being updated is not the current
entry, and can never happen with replacement enabled. (It happens when the
user tried to traverse to a session history entry that no longer had a Document
object.)
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.
Append a new entry at the end of the History object representing the new
resource and its Document object and related state.
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.
The navigation algorithm has now matured.
Fragment identifier loop: Spin the event loop 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.)
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.
Scroll to the fragment identifier given in the document's address. If this fails to find an indicated part of the document, then return to the fragment identifier loop step.
The task source for this task is the networking task source.
When an HTML document is to be loaded in a browsing context, the user agent must
queue a task to create a Document object, mark it as being
an HTML document, set its content type to "text/html",
create an HTML parser, and associate it with the document. Each task that the networking task source places on the
task queue while the fetching algorithm runs must then
fill the parser's input byte stream with the fetched bytes and cause the HTML
parser to perform the appropriate processing of the input stream.
The input byte 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, the user agent must queue a task for the parser
to process the implied EOF character, 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.
The task source for the two tasks mentioned in this section must be the networking task source.
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, DOM, and other relevant specifications. [XML] [XMLNS] [RFC3023] [DOM]
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
whose value is not the empty string, 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 apply the URL serializer algorithm to the resulting
parsed URL with the exclude fragment flag set to obtain manifest
URL, and then run the application cache selection
algorithm with manifest URL as the manifest URL, passing in the
newly-created Document. Otherwise, if the attribute is absent, its value is the empty
string, or resolving its value 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 agent 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.
When a plain text document is to be loaded in a browsing context, the user agent
must queue a task to create a Document object, mark it as
being an HTML document, set its content type to "text/plain",
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" followed by a single U+000A LINE FEED (LF)
character, and switch the HTML parser's tokenizer to the PLAINTEXT
state. Each task that the networking task
source places on the task queue while the fetching
algorithm runs must then fill the parser's input byte stream with the fetched
bytes and cause the HTML parser to perform the appropriate processing of the input
stream.
The rules for how to convert the bytes of the plain text document into actual characters, and the rules for actually rendering the text to the user, are defined in RFC 2046, RFC 3676, and subsequent versions thereof. [RFC2046] [RFC3676]
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 bytes are available, the user agent must queue a task for the parser
to process the implied EOF character, 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.
In particular, if the user agent supports the Format=Flowed
feature of RFC 3676 then the user agent would need to apply extra styling to cause the text to
wrap correctly and to handle the quoting feature. This could be performed using, e.g., an XBL
binding or a CSS extension.
The task source for the two tasks mentioned in this section must be the networking task source.
multipart/x-mixed-replace resourcesWhen a resource with the type multipart/x-mixed-replace is to be loaded in a
browsing context, the user agent must parse the resource using the rules for
multipart types. [RFC2046]
For each body part obtained from the resource, the user agent must run a new instance of the
navigate algorithm, starting from the resource handling step, using the new
body part as the resource being navigated, with replacement enabled if a previous
body part from the same resource resulted in a Document object being created, and otherwise using the same setup as the
navigate attempt that caused this section to be invoked in the first place.
For the purposes of algorithms processing these body parts as if they were complete stand-alone resources, the user agent must act as if there were no more bytes for those resources whenever the boundary following the body part is reached.
Thus, load events (and for that matter unload events) do fire for each body part loaded.
When an image, video, or audio resource is to be loaded in a browsing context, the
user agent should create a Document object, mark it as being an HTML document, set its content type to the sniffed MIME type of the resource
(type in the navigate algorithm), append an html
element to the Document, append a head element and a body
element to the html element, append an element host element for
the media, as described below, to the body element, and set the appropriate attribute
of the element host element, as described below, to the address of the image,
video, or audio resource.
The element host element to create for the media is the element given in the table below in the second cell of the row whose first cell describes the media. The appropriate attribute to set is the one given by the third cell in that same row.
| Type of media | Element for the media | Appropriate attribute |
|---|---|---|
| Image | img
| src
|
| Video | video
| src
|
| Audio | audio
| src
|
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 element host element, e.g. to link to a style sheet or an
XBL binding, to provide a script, to give the document a title, to make the media
autoplay, etc.
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 and mark it
as being a plugin document, set its content
type to the sniffed MIME type of the resource (type in the
navigate algorithm), 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.
The term plugin document is used by the Content Security Policy
specification as part of the mechanism that ensures iframes can't be used to evade
plugin-types directives. [CSP]
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.
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, set its content type to "text/html",
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.
When a user agent is supposed to navigate to a fragment identifier, then the user agent must run the following steps:
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.
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.
Append a new entry at the end of the History object representing the new
resource and its Document object and related state. Its URL must be set
to the address to which the user agent was navigating. The title
must be left unset.
Traverse the history to the new entry, with the asynchronous events flag set. This will scroll to the fragment identifier given in what is now the document's 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 and the indicated part of the document, if any, is being rendered, the user agent must either change the scrolling position of the document using the following algorithm, 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, or if the indicated part is not being rendered, then the user agent must do nothing. The aforementioned algorithm is as follows:
Let target be the indicated part of the document, as defined below.
If target is the top of the document, then scroll to the
beginning of the document for the Document. [CSSOMVIEW]
Otherwise, use the scroll an element into view algorithm to scroll target into view, with the align to top flag set. [CSSOMVIEW]
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). [RFC3023]
For HTML documents (and HTML MIME types), the following processing model must be followed to determine what the indicated part of the document is.
Apply the URL parser algorithm to the URL, and let fragid be the fragment component of the resulting parsed URL.
If fragid is the empty string, then the indicated part of the document is the top of the document; stop the algorithm here.
Let fragid bytes be the result of percent-decoding fragid.
Let decoded fragid be the result of applying the UTF-8 decoder algorithm to fragid bytes. If the UTF-8 decoder emits a decoder error, abort the decoder and instead jump to the step labeled no decoded fragid.
If 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.
No decoded fragid: 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.
If fragid is an ASCII case-insensitive match for the
string top, then the indicated part of the document is the top
of the document; stop the algorithm here.
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]
The task source for the task mentioned in this section must be the DOM manipulation task source.
When a user agent is required to traverse the history to a specified entry, optionally with replacement enabled, and optionally with the asynchronous events flag set, the user agent must act as follows.
This algorithm is not just invoked when explicitly going back or forwards in the session history — it is also invoked in other situations, for example when navigating a browsing context, as part of updating the session history with the new page.
If there is no longer a Document object for the entry in question,
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.)
If the current entry's title was not set by the pushState() or replaceState() methods, then set its title to the value
returned by the document.title IDL attribute.
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.
If the specified entry has a different Document object
than the current entry, then run the following substeps:
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.
If the origin of the Document of the specified
entry is not the same as the origin of the
Document of the current entry, then run the following
sub-sub-steps:
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.
If the browsing context is a top-level browsing context, but not an auxiliary browsing context, then the browsing context's browsing context name must be unset.
Make the specified entry's
Document object the active document of the browsing
context.
If the specified entry has a browsing context name stored with it, then run the following sub-sub-steps:
Set the browsing context's browsing context name to the name stored with the specified entry.
Clear any browsing context names stored
with all 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.
If the specified entry's
Document has any form controls whose autofill field name is "off", invoke the reset algorithm of each of those elements.
If the current document readiness of the specified entry's
Document is "complete", queue a task to run
the following sub-sub-steps:
If the Document's page showing flag is true, then abort this
task (i.e. don't fire the event below).
Set the Document's page showing flag to true.
Fire a trusted event with the name pageshow at the Window object of that
Document, but with its target set to the
Document object (and the currentTarget set to the Window object),
using the PageTransitionEvent interface, with the persisted attribute initialized to true.
This event must not bubble, must not be cancelable, and has no default action.
Set the document's address to the URL of the specified entry.
If the specified entry has a URL whose fragment identifier differs
from that of the current entry's when compared in a case-sensitive
manner, and the two share the same Document object, then let hash
changed be true, and let old URL be the URL of the current
entry and new URL be the URL of the specified
entry. Otherwise, let hash changed be false.
If the traversal was initiated with replacement enabled, remove the entry immediately before the specified entry in the session history.
If the specified entry is not an entry with persisted user state, but its URL has a fragment identifier, scroll to the fragment identifier.
If the entry is an entry with persisted user state, the user agent may update aspects of the document and its rendering, for instance the scroll position or values of form fields, that it had previously recorded.
This can even include updating the dir attribute
of textarea elements or input elements whose type attribute is in either the Text state or the Search state, if the persisted state includes the
directionality of user input in such controls.
If the entry is a state object entry, let state be a structured clone of that state object. Otherwise, let state be null.
Set history.state to state.
Let state changed be true if the Document of the specified entry has a latest entry, and that entry is not the specified entry; otherwise let it be false.
Let the latest entry of the Document of the specified entry be the specified entry.
If the asynchronous events flag is not set, then run the following steps synchronously. Otherwise, the asynchronous events flag is set; queue a task to run the following substeps.
If state changed is true, fire
a trusted event with the name popstate at the Window object of the
Document, using the PopStateEvent interface, with the state attribute initialized to the value of state. This event must bubble but not be cancelable and has no default
action.
If hash changed is true, then fire a trusted
event with the name hashchange at the browsing
context's Window object, using the HashChangeEvent interface,
with the oldURL attribute initialized to old URL and the newURL attribute
initialized to new URL. This event must bubble but not be cancelable and has
no default action.
The current entry is now the specified entry.
The task source for the tasks mentioned above is the DOM manipulation task source.
The popstate event
is fired in certain cases when navigating to a session history
entry.
[Constructor(DOMString type, optional PopStateEventInit eventInitDict)]
interface PopStateEvent : Event {
readonly attribute any state;
};
dictionary PopStateEventInit : EventInit {
any state;
};
stateReturns a copy of the information that was provided to pushState() or replaceState().
The state attribute must return the
value it was initialized to. When the object is created, this attribute must be initialized to
null. It represents the context information for the event, or null, if the state represented is
the initial state of the Document.
The hashchange event is fired when navigating
to a session history entry whose URL differs from that of the previous
one only in the fragment identifier.
[Constructor(DOMString type, optional HashChangeEventInit eventInitDict)]
interface HashChangeEvent : Event {
readonly attribute DOMString oldURL;
readonly attribute DOMString newURL;
};
dictionary HashChangeEventInit : EventInit {
DOMString oldURL;
DOMString newURL;
};
oldURLReturns the URL of the session history entry that was previously current.
newURLReturns the URL of the session history entry that is now current.
The oldURL attribute must return the
value it was initialized to. When the object is created, this attribute must be initialized to
null. It represents context information for the event, specifically the URL of the session
history entry that was traversed from.
The newURL attribute must return the
value it was initialized to. When the object is created, this attribute must be initialized to
null. It represents context information for the event, specifically the URL of the session
history entry that was traversed to.
The pageshow event is fired when traversing
to a session history entry. The pagehide event is fired when traversing from a
session history entry. The specification uses the page showing flag to
ensure that scripts receive these events in a consistent manner (e.g. that they never receive two
pagehide events in a row without an intervening pageshow, or vice versa).
[Constructor(DOMString type, optional PageTransitionEventInit eventInitDict)]
interface PageTransitionEvent : Event {
readonly attribute boolean persisted;
};
dictionary PageTransitionEventInit : EventInit {
boolean persisted;
};
persistedReturns false if the page is newly being loaded (and the load
event will fire). Otherwise, returns true.
The persisted attribute must
return the value it was initialized to. When the object is created, this attribute must be
initialized to false. It represents the context information for the event.
A Document has a salvageable state, which must initially be
true, a fired unload flag, which must initially be false, and a page showing
flag, which must initially be false.
Event loops have a termination nesting level counter, which must initially be zero.
When a user agent is to prompt to unload a document, it must run the following steps.
Increase the event loop's termination nesting level by one.
Increase the Document's ignore-opens-during-unload counter by
one.
Let event be a new trusted
BeforeUnloadEvent event object with the name beforeunload, which does not bubble but is cancelable.
Decrease the event loop's termination nesting level by one.
Release the storage mutex.
If any event listeners were triggered by the earlier dispatch step, then set the
Document's salvageable state to
false.
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.
If this algorithm was invoked by another instance of the "prompt to unload a document" algorithm (i.e. through the steps below that invoke this algorithm for all descendant browsing contexts), then jump to the step labeled end.
Let descendants be the list of the descendant browsing
contexts of the Document.
If descendants is not an empty list, then for each browsing context b in descendants run the following substeps:
Prompt to unload the active document of the browsing context b. If the user refused to allow the document to be unloaded, then the user implicitly also refused to allow this document to be unloaded; jump to the step labeled end.
If the salvageable state of the active document of the browsing context b is false, then set the salvageable state of this document to false also.
End: Decrease the Document's ignore-opens-during-unload
counter by one.
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.)
Increase the event loop's termination nesting level by one.
Increase the Document's ignore-opens-during-unload counter by
one.
If the Document's page showing flag is false, then jump to the
step labeled unload event below (i.e. skip firing the pagehide event and don't rerun the unloading document
visibility change steps).
Set the Document's page showing flag to false.
Fire a trusted event with the name pagehide at the Window object of the
Document, but with its target set to the
Document object (and the currentTarget
set to the Window object), using the PageTransitionEvent interface,
with the persisted attribute initialized
to true. This event must not bubble, must not be cancelable, and has no default action.
Run any unloading document visibility change steps for Document that
are defined by other applicable specifications.
This is specifically intended for use by the Page Visibility specification. [PAGEVIS]
Unload event: If the Document's fired unload flag is
false, fire a simple event named unload at the
Document's Window object.
Decrease the event loop's termination nesting level by one.
Release the storage mutex.
If any event listeners were triggered by the earlier unload event step, then set
the Document object's salvageable
state to false and set the Document's fired unload flag to
true.
Run any unloading document cleanup steps for Document that are
defined by this specification and other applicable specifications.
If this algorithm was invoked by another instance of the "unload a document" algorithm (i.e. by the steps below that invoke this algorithm for all descendant browsing contexts), then jump to the step labeled end.
Let descendants be the list of the descendant browsing
contexts of the Document.
If descendants is not an empty list, then for each browsing context b in descendants run the following substeps:
Unload the active document of the browsing context b with the recycle parameter set to false.
If the salvageable state of the active document of the browsing context b is false, then set the salvageable state of this document to false also.
If both the Document's salvageable state and recycle are false, then the Document's browsing
context must discard the
Document.
End: Decrease the Document's ignore-opens-during-unload
counter by one.
This specification defines the following unloading document cleanup steps. Other specifications can define more.
Make disappear any WebSocket objects that were created by the WebSocket() constructor whose global object is the
Document's Window object.
If this affected any WebSocket objects, then set Document's salvageable state to false.
If the Document's salvageable
state is false, forcibly close any
EventSource objects that whose constructor was invoked from the
Document's Window object.
If the Document's salvageable
state is false, empty the Document's Window's list of active
timers.
interface BeforeUnloadEvent : Event {
attribute DOMString returnValue;
};
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.
If a Document is aborted, the user agent must run the following
steps:
Abort the active
documents of every child browsing context. If this results in any of those
Document objects having their salvageable state set to false, then set this
Document's salvageable state to
false also.
Cancel any instances of the fetch algorithm in the context of
this Document, discarding any tasks queued for them, and discarding any further data received from the
network for them. If this resulted in any instances of the fetch
algorithm being canceled or any queued tasks or any network data getting discarded, then set the
Document's salvageable state to
false.
If the Document has an active parser, then abort that parser and set the Document's salvageable state to false.
User agents may allow users to explicitly invoke the abort a document algorithm for a
Document. If the user does so, then, if that
Document is an active document, the user
agent should queue a task to fire a simple
event named abort at that
Document's Window object before invoking
the abort algorithm.