The sequence of Document
s 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.
When state object entries are added, a URL can be provided. This
URL is used to replace the state object entry if the
Document
is evicted.
History
interfaceinterface History { readonly attribute long length; void go([Optional] in long delta); void back(); void forward(); void pushState(in any data, in DOMString title, [Optional] in DOMString url); void clearState(); };
The length
attribute of the History
interface must return the
number of entries in this session history.
The actual entries are not accessible from script.
The go(delta)
method causes the UA to move the
number of steps specified by delta in the
session history.
If the delta is zero, or if the argument is
omitted, then the user agent must act as if the location.reload()
method was
called instead.
Otherwise, if the index of the current entry plus delta is less than zero or greater than or equal to the number of items in the session history, then the user agent must do nothing.
Otherwise, the user agent must cause the current browsing context to traverse the history to the specified entry. The specified entry is the one whose index equals the index of the current entry plus delta.
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.
When this method is invoked, the user agent must run the following steps:
Let clone data be a structured clone of the specified data. If this throws an exception, then rethrow that exception and abort these steps.
If a third argument is specified, run these substeps:
SECURITY_ERR
exception and
abort the pushState()
steps.SECURITY_ERR
exception and abort the pushState()
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>.
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.
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.
Update the current entry to be the this newly added 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.)
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.
When an entry in the session history is activated (which happens during session traversal, as described above), the user agent must run the following steps:
If the entry is a state object entry, let state be a structured clone of that state object. Otherwise, let state be null.
Run the appropriate according to the conditions described:
Queue a task to fire a popstate
event in no
namespace 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. The task
source for this task is the DOM manipulation task
source.
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); void initPopStateEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any stateArg); };
The initPopStateEvent()
and initPopStateEventNS()
methods must initialize the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The state
attribute represents the context information for the event, or null,
if the state represented is the initial state of the
Document
.
Location
interfaceEach Document
object in a browsing
context's session history is associated with a unique
instance of a Location
object.
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 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 {
readonly attribute DOMString href;
void assign(in DOMString url);
void replace(in DOMString url);
void reload();
// URL decomposition 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);
};
The href
attribute must return the
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.
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
the assign()
and replace()
methods is not
successful, then the user agent must instead throw a
SYNTAX_ERR
exception.
The Location
interface also has the complement of
URL decomposition attributes, protocol
, host
, port
, hostname
, pathname
, search
, and hash
. These must follow
the rules given for URL decomposition attributes, with the input being the 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.
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:
href
setter, if the
script is running in a browsing context that is
allowed to navigate the browsing context with which
the Location
object is associated
User agents must not allow scripts to override the href
attribute's setter.
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 iframe
s has a history
object distinct from the
iframe
s' 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 handlers that do not represent 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:
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 source browsing context has its sandboxed navigation browsing context flag set, then abort these steps. The user agent may 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.
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, 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.
Cancel any preexisting attempt to navigate 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.
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 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 HTTP, and the method
is not GET, then the user
agent must include an XXX-Origin
header whose value is determined as follows:
null
".If fetching the resource is synchronous (i.e. for javascript:
URLs and 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.
If fetching the resource results in a redirect, return to the step labeled "fragment identifiers" with the new resource.
Cross-origin redirects cause the XXX-Origin
header to become "null
" on subsequent requests in the chain.
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.
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.
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 401 responses that do not include a challenge recognised 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 recognised 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:
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.
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 follows the set of steps given below that is appropriate for the situation at hand. From the point of view of any script, these steps must occur atomically.
pause for scripts -- but don't use the "pause" definition since that involves not running script!
Unload the
Document
object of the current entry,
with the recycle parameter set to
false.
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).
Traverse the history to the new entry.
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.
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, remove the entry immediately before the new current entry in the session history.
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 tokeniser. 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 potentially
before the page has finished parsing, the user agent must
update the session history with the new page.
Application cache selection happens in the HTML parser.
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] [DOM3CORE]
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 document-is-markup
flag set to true, the resulting absolute URL 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 the document-is-markup
flag set to true, 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-styleesheet?>
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).
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 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 tokeniser had emitted a start tag
token with the tag name "pre", set the tokenization
stage's content model flag to PLAINTEXT, and
begin to pass the stream of characters in the plain text document to
that tokeniser.
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 the document-is-markup flag set to false, no manifest,
and passing in the newly-created Document
.
When no more character 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 stylesheet or an XBL
binding, providing script, giving the document a title
,
etc.
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 the document-is-markup flag set to false, 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 stylesheet or an XBL binding, to provide a
script, to give the document a title
, 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, 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 the document-is-markup flag set to false, 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 stylesheet 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, 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 the document-is-markup flag set to false, 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 update the session
history with the new page, where "the new page" has the same
Document
as before but with the URL having the newly
specified fragment identifier.
Part of that algorithm involves the user agent having to scroll to the fragment identifier, which is the important part for this step.
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 MIME type specification of the document's MIME Type (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.
Parse the URL, and let fragid be the <fragment> component of the URL.
If fragid is the empty string, then the indicated part of the document is the top of the document.
If there is an element in the DOM that has an ID exactly equal to fragid, then the first such element in tree order is the indicated part of the document; stop the algorithm here.
If there is an a
element in the DOM that has a
name
attribute whose value is
exactly equal to fragid, then the first such element in tree
order is the indicated part 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]
When a user agent is required to traverse the history to a specified entry, the user agent must act as follows:
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.
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.
For example, some user agents might want to persist the scroll position, or the values of form controls.
If the specified entry has a different
Document
object than the current entry
then the user agent must run the following substeps:
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:
Document
objects with the same
origin as the active document and
that are contiguous with the current entry.Document
object the
active document of the browsing
context.Document
objects with the same origin
as the new active document, and that are
contiguous with the specified entry, must be cleared.If the specified entry is a state object or the
first entry for a Document
, the user agent must activate that
entry.
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
first, if the Document
's current document
readiness is the string "complete", then fire a simple
event with the name hashchange
at the browsing
context's Window
object; and second, if the new
URL has a fragment identifier, scroll to the fragment
identifier.
User agents may also update other aspects of the document view when the location changes in this way, for instance the scroll position, values of form fields, etc.
The current entry is now the specified entry.
how does the changing of the global attributes affect .watch() when seen from other Windows?
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.)
Set salvageable to true.
Let event be a new
BeforeUnloadEvent
event object with the name beforeunload
, with no namespace,
which does not bubble but is cancelable.
Dispatch event at the
Document
's Window
object.
If any event listeners were triggered by the previous step, then set salvageable 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 refused to allow the document to be unloaded then these steps must be aborted.
Fire a simple event called unload
at the Document
's
Window
object.
If any event listeners were triggered by the previous step, then set salvageable to false.
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.
If salvageable and recycle are both false, discard the Document
.
interface BeforeUnloadEvent : Event { attribute DOMString returnValue; };
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.