This section describes features that apply most directly to Web browsers. Having said that, except where specified otherwise, the requirements defined in this section do apply to all user agents, whether they are Web browsers or not.
A browsing context is an environment in which
Document
objects are presented to the user.
A tab or window in a Web browser typically contains
a browsing context, as does an iframe
or frame
s in a
frameset
.
Each browsing context has a corresponding
WindowProxy
object.
A browsing context has a session
history, which lists the Document
objects that
that browsing context has presented, is presenting, or
will present. At any time, one Document
in each
browsing context is designated the active
document. A Document
's browsing
context is that browsing context whose
session history contains the Document
, if
any. (A Document
created using an API such as createDocument()
has no browsing context.)
Each Document
is associated with a
Window
object. A browsing context's
WindowProxy
object forwards everything to the
browsing context's active document's
Window
object.
In general, there is a 1-to-1 mapping from the
Window
object to the Document
object.
There are two exceptions. First, a Window
can be reused
for the presentation of a second Document
in the same
browsing context, such that the mapping is then 1-to-2.
This occurs when a browsing context is navigated from the initial
about:blank
Document
to another, with
replacement enabled. Second, a Document
can end up being reused for several Window
objects when
the document.open()
method is
used, such that the mapping is then many-to-1.
A Document
does not necessarily have a
browsing context associated with it. In particular,
data mining tools are likely to never instantiate browsing
contexts.
A browsing context can have a creator browsing context, the browsing context that was responsible for its creation. If a browsing context has a parent browsing context, then that is its creator browsing context. Otherwise, if the browsing context has an opener browsing context, then that is its creator browsing context. Otherwise, the browsing context has no creator browsing context.
If a browsing context A has a
creator browsing context, then the
Document
that was the active document of
that creator browsing context at the time A was created is the creator
Document
.
When a browsing context is first created, it must be created with a single
Document
in its session history, whose address is about:blank
, which is marked as being an HTML document, whose character
encoding is UTF-8, and which is both ready for post-load tasks and
completely loaded immediately. The Document
must have a single child
html
node, which itself has a single child body
node. As soon as this
Document
is created, the user agent must implement the sandboxing for
it.
If the browsing context is created specifically to be immediately navigated, then that initial navigation will have replacement enabled.
The origin and
effective script origin of the about:blank
Document
are set when the Document
is
created. If the new browsing context has a
creator browsing context, then the origin
of the about:blank
Document
is an alias to the origin
of the creator Document
and the
effective script origin of the about:blank
Document
is initially an alias to the effective
script origin of the creator
Document
. Otherwise, the origin of
the about:blank
Document
is a globally
unique identifier assigned when the new browsing
context is created and the effective script
origin of the about:blank
Document
is initially an alias to
its origin.
Certain elements (for example, iframe
elements) can
instantiate further browsing
contexts. These are called nested browsing contexts. If a browsing context P has a Document
D
with an element E that nests another browsing
context C inside it, then C
is said to be nested
through D, and E is
said to be the browsing context container of C. If the browsing context container
element E is in the Document
D,
then P is said to be the parent browsing
context of C and C is
said to be a child browsing context of P. Otherwise, the nested browsing
context C has no parent browsing
context.
A browsing context A is said to be an ancestor of a browsing context B if there exists a browsing context A' that is a child browsing context of A and that is itself an ancestor of B, or if there is a browsing context P that is a child browsing context of A and that is the parent browsing context of B.
A browsing context that is not a nested browsing context has no parent browsing context, and is the top-level browsing context of all the browsing contexts for which it is an ancestor browsing context.
The transitive closure of parent browsing contexts for a nested browsing context gives the list of ancestor browsing contexts.
The list of the descendant browsing contexts of a
Document
d is the (ordered) list
returned by the following algorithm:
Let list be an empty list.
For each child browsing context of d that is nested through an element that is in the Document
d, in the tree order of the elements
nesting those browsing
contexts, run these substeps:
Append that child browsing context to the list list.
Append the list of the descendant browsing contexts of the active document of that child browsing context to the list list.
Return the constructed list.
A Document
is said to be fully active
when it is the active document of its browsing
context, and either its browsing context is a top-level
browsing context, or it has a parent browsing
context and the Document
through which it is nested is itself fully
active.
Because they are nested through an element, child browsing contexts are always tied to
a specific Document
in their parent browsing
context. User agents must not allow the user to interact with
child browsing contexts
of elements that are in Document
s that are not
themselves fully active.
A nested browsing context can have a seamless
browsing context flag set, if it is embedded through an
iframe
element with a seamless
attribute.
A nested browsing context can in some
cases be taken out of its parent browsing context (e.g.
if an iframe
element is removed from its
Document
). In such a situation, the nested
browsing context has no parent browsing context,
but it still has the same browsing context container
and is still nested
through that element's Document
. Such a
nested browsing context is not a
top-level browsing context, and cannot contain
Document
s that are fully active.
Furthermore, if a browsing context container (such as
an iframe
) is moved to another Document
,
then the parent browsing context of its nested
browsing context will change.
The document family of a browsing context
consists of the union of all the Document
objects in
that browsing context's session history
and the document families of
all those Document
objects. The document
family of a Document
object consists of the
union of all the document
families of the browsing
contexts that are nested through the Document
object.
top
Returns the WindowProxy
for the top-level browsing context.
parent
Returns the WindowProxy
for the parent browsing context.
frameElement
Returns the Element
for the browsing context container.
Returns null if there isn't one.
Throws a SecurityError
exception in cross-origin situations.
The top
IDL attribute on
the Window
object of a Document
in a
browsing context b must return the
WindowProxy
object of its top-level browsing
context (which would be its own WindowProxy
object if it was a top-level browsing context itself),
if it has one, or its own WindowProxy
object otherwise
(e.g. if it was a detached nested browsing
context).
The parent
IDL
attribute on the Window
object of a
Document
in a browsing context b must return the WindowProxy
object of
the parent browsing context, if there is one (i.e. if
b is a child browsing context), or
the WindowProxy
object of the browsing
context b itself, otherwise (i.e. if it
is a top-level browsing context or a detached
nested browsing context).
The frameElement
IDL attribute on the Window
object of a
Document
d, on getting, must run
the following algorithm:
If d is not a Document
in a
nested browsing context, return null and abort these
steps.
If the browsing context container's
Document
does not have the same effective script origin as the
entry script, then throw a SecurityError
exception.
Otherwise, return the browsing context container for b.
It is possible to create new browsing contexts that are related to a top-level browsing context without being nested through an element. Such browsing contexts are called auxiliary browsing contexts. Auxiliary browsing contexts are always top-level browsing contexts.
An auxiliary browsing context has an opener browsing context, which is the browsing context from which the auxiliary browsing context was created.
The opener
IDL
attribute on the Window
object, on getting, must return
the WindowProxy
object of the browsing
context from which the current browsing context
was created (its opener browsing context), if there is
one, if it is still available, and if the current browsing
context has not disowned its opener; otherwise, it
must return null. On setting, if the new value is null then the
current browsing context must disown its opener; if the new value is anything else
then the user agent must ignore the new value.
User agents may support secondary browsing contexts, which are browsing contexts that form part of the user agent's interface, apart from the main content area.
A browsing context A is allowed to navigate a second browsing context B if one of the following conditions is true:
An element has a browsing context scope origin if its
Document
's browsing context is a
top-level browsing context or if all of its
Document
's ancestor browsing contexts all have active documents whose
origin are the same origin as the
element's Document
's origin. If an element
has a browsing context scope origin, then its value is
the origin of the element's Document
.
Each browsing context is defined as having a list of one or more directly reachable browsing contexts. These are:
The transitive closure of all the browsing contexts that are directly reachable browsing contexts forms a unit of related browsing contexts.
Each unit of related browsing contexts is then
further divided into the smallest number of groups such that every
member of each group has an active document with an
effective script origin that, through appropriate
manipulation of the document.domain
attribute, could
be made to be the same as other members of the group, but could not
be made the same as members of any other group. Each such group is a
unit of related similar-origin browsing contexts.
There is also at most one event loop per unit of related similar-origin browsing contexts (though several units of related similar-origin browsing contexts can have a shared event loop).
Browsing contexts can have a browsing context name. By default, a browsing context has no name (its name is not set).
A valid browsing context name is any string with at least one character that does not start with a U+005F LOW LINE character. (Names starting with an underscore are reserved for special keywords.)
A valid browsing context name or keyword is any string
that is either a valid browsing context name or that is
an ASCII case-insensitive match for one of: _blank
, _self
, _parent
, or _top
.
These values have different meanings based on whether the page is
sandboxed or not, as summarized in the following (non-normative)
table. In this table, "current" means the browsing
context that the link or script is in, "parent" means the
parent browsing context of the one the link or script
is in, "master" means the nearest ancestor browsing
context of the one the link or script is in that is not
itself in a seamless
iframe, "top" means the top-level browsing
context of the one the link or script is in, "new" means a
new top-level browsing context or auxiliary
browsing context is to be created, subject to various user
preferences and user agent policies, "none" means that nothing will
happen, and "maybe new" means the same as "new" if the "allow-popups
"
keyword is also specified on the sandbox
attribute (or if the user
overrode the sandboxing), and the same as "none" otherwise.
Keyword | Ordinary effect | Effect in an iframe with...
| ||||
---|---|---|---|---|---|---|
seamless=""
| sandbox=""
| sandbox="" seamless=""
| sandbox="allow-top-navigation"
| sandbox="allow-top-navigation" seamless=""
| ||
none specified, for links and form submissions | current | master | current | master | current | master |
none specified, for window.open()
| new | new | maybe new† | maybe new† | maybe new† | maybe new† |
empty string | current | master | current | master | current | master |
_blank
| new | new | maybe new | maybe new | maybe new | maybe new |
_self
| current | current | current | current | current | current |
_parent if there isn't a parent
| current | current | current | current | current | current |
_parent if parent is also top
| parent/top | parent/top | none | none | parent/top | parent/top |
_parent if there is one and it's not top
| parent | parent | none | none | none | none |
_top if top is current
| current | current | current | current | current | current |
_top if top is not current
| top | top | none | none | top | top |
name that doesn't exist | new | new | maybe new | maybe new | maybe new | maybe new |
name that exists and is a descendant | specified descendant | specified descendant | specified descendant | specified descendant | specified descendant | specified descendant |
name that exists and is current | current | current | current | current | current | current |
name that exists and is an ancestor that is top | specified ancestor | specified ancestor | none | none | specified ancestor/top | specified ancestor/top |
name that exists and is an ancestor that is not top | specified ancestor | specified ancestor | none | none | none | none |
† This case is only possible if the sandbox
attribute also allows
scripts.
An algorithm is allowed to show a pop-up if, in the task in which the algorithm is running, either:
click
event was
trusted, orclick
event is being handled.The rules for choosing a browsing context given a browsing context name are as follows. The rules assume that they are being applied in the context of a browsing context.
If the given browsing context name is the empty string or _self
, then the chosen browsing context must be
the current one.
If the given browsing context name is _self
, then this is an explicit
self-navigation override, which overrides the behavior of
the seamless browsing context flag set by the seamless
attribute on
iframe
elements.
If the given browsing context name is _parent
, then the chosen browsing context must be
the parent browsing context of the current
one, unless there isn't one, in which case the chosen browsing
context must be the current browsing context.
If the given browsing context name is _top
, then the chosen browsing context must be the
top-level browsing context of the current one, if
there is one, or else the current browsing context.
If the given browsing context name is not _blank
and there exists a browsing context whose
name is the same as the
given browsing context name, and the current browsing context is
allowed to navigate that browsing context, and the
user agent determines that the two browsing contexts are related
enough that it is ok if they reach each other, then that browsing
context must be the chosen one. If there are multiple matching
browsing contexts, the user agent should select one in some
arbitrary consistent manner, such as the most recently opened,
most recently focused, or more closely related.
If the browsing context is chosen by this step to be the current browsing context, then this is also an explicit self-navigation override.
Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and/or abilities — it is determined by the rules given for the first applicable option from the following list:
Typically, there is no chosen browsing context.
The user agent may offer to create a new top-level browsing context or reuse an existing top-level browsing context. If the user picks one of those options, then the designated browsing context must be the chosen one (the browsing context's name isn't set to the given browsing context name). The default behaviour (if the user agent doesn't offer the option to the user, or if the user declines to allow a browsing context to be used) must be that there must not be a chosen browsing context.
If this case occurs, it means that an author has explicitly sandboxed the document that is trying to open a link.
noreferrer
keywordA new top-level browsing context must be
created. If the given browsing context name is not _blank
, then the new top-level browsing context's
name must be the given browsing context name (otherwise, it has
no name). The chosen browsing context must be this new browsing
context. The creation of such a browsing context is
a new start for session storage.
If it is immediately navigated, then the navigation will be done with replacement enabled.
noreferrer
keyword doesn't
applyA new auxiliary browsing context must be
created, with the opener browsing context being the
current one. If the given browsing context name is not _blank
, then the new auxiliary browsing context's
name must be the given browsing context name (otherwise, it has
no name). The chosen browsing context must be this new browsing
context.
If it is immediately navigated, then the navigation will be done with replacement enabled.
The chosen browsing context is the current browsing context.
There must not be a chosen browsing context.
User agent implementors are encouraged to provide a way for users to configure the user agent to always reuse the current browsing context.
If the current browsing context's active document's active sandboxing flag set has the sandboxed navigation browsing context flag set and chosen browsing context picked above, if any, is a new browsing context (whether top-level or auxiliary), then all the flags that are set in the current browsing context's active document's active sandboxing flag set when the new browsing context is created must be set in the new browsing context's popup sandboxing flag set, and the current browsing context must be set as the new browsing context's one permitted sandboxed navigator.
Window
object[NamedPropertiesObject] interface Window : EventTarget { // the current browsing context [Unforgeable] readonly attribute WindowProxy window; [Replaceable] readonly attribute WindowProxy self; [Unforgeable] readonly attribute Document document; attribute DOMString name; [PutForwards=href, Unforgeable] readonly attribute Location location; readonly attribute History history; [Replaceable] readonly attribute BarProp locationbar; [Replaceable] readonly attribute BarProp menubar; [Replaceable] readonly attribute BarProp personalbar; [Replaceable] readonly attribute BarProp scrollbars; [Replaceable] readonly attribute BarProp statusbar; [Replaceable] readonly attribute BarProp toolbar; attribute DOMString status; void close(); void stop(); void focus(); void blur(); // other browsing contexts [Replaceable] readonly attribute WindowProxy frames; [Replaceable] readonly attribute unsigned long length; [Unforgeable] readonly attribute WindowProxy top; attribute WindowProxy? opener; readonly attribute WindowProxy parent; readonly attribute Element? frameElement; WindowProxy open(optional DOMString url, optional DOMString target, optional DOMString features, optional boolean replace); getter WindowProxy (unsigned long index); getter object (DOMString name); // the user agent readonly attribute Navigator navigator; readonly attribute External external; readonly attribute ApplicationCache applicationCache; // user prompts void alert(DOMString message); boolean confirm(DOMString message); DOMString? prompt(DOMString message, optional DOMString default); void print(); any showModalDialog(DOMString url, optional any argument); // event handler IDL attributes attribute EventHandler onabort; attribute EventHandler onafterprint; attribute EventHandler onbeforeprint; attribute EventHandler onbeforeunload; attribute EventHandler onblur; attribute EventHandler oncancel; attribute EventHandler oncanplay; attribute EventHandler oncanplaythrough; attribute EventHandler onchange; attribute EventHandler onclick; attribute EventHandler onclose; attribute EventHandler oncontextmenu; attribute EventHandler oncuechange; attribute EventHandler ondblclick; attribute EventHandler ondrag; attribute EventHandler ondragend; attribute EventHandler ondragenter; attribute EventHandler ondragleave; attribute EventHandler ondragover; attribute EventHandler ondragstart; attribute EventHandler ondrop; attribute EventHandler ondurationchange; attribute EventHandler onemptied; attribute EventHandler onended; attribute OnErrorEventHandler onerror; attribute EventHandler onfocus; attribute EventHandler onhashchange; attribute EventHandler oninput; attribute EventHandler oninvalid; attribute EventHandler onkeydown; attribute EventHandler onkeypress; attribute EventHandler onkeyup; attribute EventHandler onload; attribute EventHandler onloadeddata; attribute EventHandler onloadedmetadata; attribute EventHandler onloadstart; attribute EventHandler onmessage; attribute EventHandler onmousedown; attribute EventHandler onmousemove; attribute EventHandler onmouseout; attribute EventHandler onmouseover; attribute EventHandler onmouseup; attribute EventHandler onmousewheel; attribute EventHandler onoffline; attribute EventHandler ononline; attribute EventHandler onpause; attribute EventHandler onplay; attribute EventHandler onplaying; attribute EventHandler onpagehide; attribute EventHandler onpageshow; attribute EventHandler onpopstate; attribute EventHandler onprogress; attribute EventHandler onratechange; attribute EventHandler onreset; attribute EventHandler onresize; attribute EventHandler onscroll; attribute EventHandler onseeked; attribute EventHandler onseeking; attribute EventHandler onselect; attribute EventHandler onshow; attribute EventHandler onstalled; attribute EventHandler onstorage; attribute EventHandler onsubmit; attribute EventHandler onsuspend; attribute EventHandler ontimeupdate; attribute EventHandler onunload; attribute EventHandler onvolumechange; attribute EventHandler onwaiting; };
window
frames
self
These attributes all return window.
document
Returns the active document.
defaultView
Returns the Window
object of the active document.
The Window
interface must only be exposed if the JavaScript global
environment is a document environment.
The window
, frames
, and self
IDL attributes must all
return the Window
object's browsing
context's WindowProxy
object.
The document
IDL
attribute must return the Document
object of the
Window
object's Document
's browsing
context's active document.
The defaultView
IDL
attribute of the Document
interface must return the
Document
's browsing context's
WindowProxy
object, if there is one, or null
otherwise.
For historical reasons, Window
objects must also
have a writable, configurable, non-enumerable property named
HTMLDocument
whose value is the
Document
interface object.
User agents must throw a
SecurityError
exception whenever any properties of a
Window
object are accessed by scripts whose
effective script origin is not the same as the
Window
object's Document
's effective
script origin, with the following exceptions:
location
attribute
postMessage()
method
frames
attribute
When a script whose effective script origin is not
the same as the Window
object's Document
's
effective script origin attempts to access that
Window
object's methods or attributes, the user agent
must act as if any changes to the Window
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 as the Window
object's Document
's
effective script origin must be provided with a
separate set of objects. These objects must have the prototype chain
appropriate for the script for which the objects are created (not
those that would be appropriate for scripts whose script's
global object is the Window
object in
question).
open
( [ url [, target [, features [, replace ] ] ] ] )Opens a window to show url (defaults to
about:blank
), and returns it. The target argument gives the name of the new
window. If a window exists with that name already, it is
reused. The replace attribute, if true, means
that whatever page is currently open in that window will be
removed from the window's session history. The features argument is ignored.
name
[ = value ]Returns the name of the window.
Can be set, to change the name.
close
()Closes the window.
stop
()Cancels the document load.
The open()
method on
Window
objects provides a mechanism for navigating an existing browsing
context or opening and navigating an auxiliary browsing
context.
The method has four arguments, though they are all optional.
The first argument, url, must be a
valid non-empty URL for a page to load in the browsing
context. If no arguments are provided, or if the first argument is
the empty string, then the url argument defaults
to "about:blank
". The argument must be resolved to an absolute
URL (or an error), relative to the entry
script's base URL,
when the method is invoked.
The second argument, target, specifies the
name of the browsing
context that is to be navigated. It must be a valid browsing
context name or keyword. If fewer than two arguments are
provided, then the target argument defaults to the
value "_blank
".
The third argument, features, has no defined effect and is mentioned for historical reasons only. User agents may interpret this argument as instructions to set the size and position of the browsing context, but are encouraged to instead ignore the argument entirely.
The fourth argument, replace, specifies whether or not the new page will replace the page currently loaded in the browsing context, when target identifies an existing browsing context (as opposed to leaving the current page in the browsing context's session history). When three or fewer arguments are provided, replace defaults to false.
When the method is invoked, the user agent must first select a browsing context to navigate by applying the rules for choosing a browsing context given a browsing context name using the target argument as the name and the browsing context of the script as the context in which the algorithm is executed, unless the user has indicated a preference, in which case the browsing context to navigate may instead be the one indicated by the user.
For example, suppose there is a user agent that
supports control-clicking a link to open it in a new tab. If a user
clicks in that user agent on an element whose onclick
handler uses the window.open()
API to open a page in an
iframe, but, while doing so, holds the control key down, the user
agent could override the selection of the target browsing context to
instead target a new tab.
If the method is not allowed to show a pop-up and
applying the rules for choosing a browsing context given a
browsing context name using the target
argument, would result in there not being a chosen browsing context,
then throw an InvalidAccessError
exception and abort
these steps.
Otherwise, if url is not
"about:blank
", the user agent must
navigate the selected
browsing context to the absolute URL
obtained from resolving url earlier. If the replace is
true or if the browsing context was just created as
part of the rules for choosing a browsing context given a
browsing context name, then replacement must be enabled. The navigation must be
done with the browsing
context of the entry script as the source
browsing context. If the resolve a URL algorithm
failed, then the user agent may either instead navigate
to an inline error page, using the same replacement behavior and
source browsing context behavior as described earlier in this
paragraph; or treat the url as
"about:blank
", acting as described in the next
paragraph.
If url is
"about:blank
", the user agent must instead queue
a task to fire a simple event named load
at the selected browsing
context's Window
object, but with its target
set to the selected
browsing context's Window
object's
Document
object (and the currentTarget
set to the
Window
object).
The method must return the WindowProxy
object of the
browsing context that was navigated, or null if no
browsing context was navigated.
The name
attribute of
the Window
object must, on getting, return the current
name of the
browsing context, and, on setting, set the name of the browsing
context to the new value.
The name gets reset when the browsing context is navigated to another domain.
The close()
method on Window
objects should, if the corresponding
browsing context A is
script-closable and the browsing context of the script that invokes the method is
allowed to navigate the browsing context
A, close the browsing context A.
A browsing context is script-closable if
it is an auxiliary browsing context that was created by
a script (as opposed to by an action of the user), or if it is a
browsing context whose session history
contains only one Document
.
The stop()
method
on Window
objects should, if there is an existing
attempt to navigate the browsing context
and that attempt is not currently running the unload a
document algorithm, cancel that navigation; then, it must abort the active document of the
browsing context of the Window
object on
which it was invoked.
length
Returns the number of child browsing contexts.
Returns the indicated child browsing context.
The length
IDL
attribute on the Window
interface must return the
number of child browsing
contexts that are nested through elements that are in the Document
that is the
active document of that Window
object, if
that Window
's browsing context shares the
same event loop as the script's browsing
context of the entry script accessing the IDL
attribute; otherwise, it must return zero.
The supported property indices on the
Window
object at any instant are the numbers in the
range 0 .. n-1, where n is the number returned by the length
IDL attribute. If n is zero then there are no supported property
indices.
To determine the value of an indexed
property index of a Window
object, the user agent must return the WindowProxy
object of the indexth child browsing
context of the Document
that is nested through
an element that is in the
Document
, sorted in the tree order
of the elements nesting those browsing contexts.
These properties are the dynamic nested browsing context properties.
Window
objectReturns the indicated element or collection of elements.
The Window
interface supports named properties. The supported
property names at any moment consist of:
name
content attribute
for all a
, applet
, area
,
embed
, form
, frameset
,
img
, and object
elements in the
active document that have a name
content attribute, andid
content
attribute of any HTML element in
the active document with an id
content attribute.To determine the value of a named property name when the
Window
object is indexed for property retrieval,
the user agent must return the value obtained using the following
steps:
Let objects be the list of named objects with the name name in the active document.
There will be at least one such object, by definition.
If objects contains a nested browsing
context, then return the WindowProxy
object of
the nested browsing context corresponding to the
first browsing context container in tree
order whose browsing context is in objects, and abort these steps.
Otherwise, if elements has only one element, return that element and abort these steps.
Otherwise return an HTMLCollection
rooted at the
Document
node, whose filter matches only named objects with the
name name. (By definition, these will all be
elements.)
Named objects with the name name, for the purposes of the above algorithm, are those that are either:
a
, applet
, area
,
embed
, form
, frameset
,
img
, or object
elements that have a name
content attribute whose value is name, orid
content attribute whose value is name.A browsing context has a strong reference to each of
its Document
s and its WindowProxy
object,
and the user agent itself has a strong reference to its top-level browsing
contexts.
A Document
has a strong reference to its
Window
object.
A Window
object has a strong reference to its
Document
object through its document
attribute. Thus, references
from other scripts to either of those objects will keep both
alive. Similarly, both Document
and Window
objects have implied strong
references to the WindowProxy
object.
Each script has a strong reference to its browsing context and its document.
When a browsing context is to discard a
Document
, the user agent must run the following
steps:
Set the Document
's salvageable state to
false.
Run any unloading document cleanup steps for
the Document
that are defined by this specification
and other applicable specifications.
Remove any tasks
associated with the Document
in any task
source, without running those tasks.
Discard
all the child browsing
contexts of the Document
.
Lose the strong reference from the Document
's
browsing context to the
Document
.
Whenever a Document
object is discarded, it is also removed from
the list of the worker's Document
s of each
worker whose list contains that Document
.
When a browsing context is
discarded, the strong reference from the user agent itself to
the browsing context must be severed, and all the
Document
objects for all the entries in the
browsing context's session history must be discarded as well.
User agents may discard top-level browsing contexts at any time (typically,
in response to user requests, e.g. when a user force-closes a window
containing one or more top-level browsing contexts). Other browsing contexts must be discarded
once their WindowProxy
object is eligible for garbage
collection.
When the user agent is required to close a browsing context, it must run the following steps:
Let specified browsing context be the browsing context being closed.
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.
Remove the specified browsing context from the user interface (e.g. close or hide its tab in a tabbed browser).
Discard the specified browsing context.
User agents should offer users the ability to arbitrarily close any top-level browsing context.
To allow Web pages to integrate with Web browsers, certain Web browser interface elements are exposed in a limited way to scripts in Web pages.
Each interface element is represented by a BarProp
object:
interface BarProp { attribute boolean visible; };
locationbar
. visible
Returns true if the location bar is visible; otherwise, returns false.
menubar
. visible
Returns true if the menu bar is visible; otherwise, returns false.
personalbar
. visible
Returns true if the personal bar is visible; otherwise, returns false.
scrollbars
. visible
Returns true if the scroll bars are visible; otherwise, returns false.
statusbar
. visible
Returns true if the status bar is visible; otherwise, returns false.
toolbar
. visible
Returns true if the toolbar is visible; otherwise, returns false.
The visible attribute, on getting, must return either true or a value determined by the user agent to most accurately represent the visibility state of the user interface element that the object represents, as described below. On setting, the new value must be discarded.
The following BarProp
objects exist for each
Document
object in a browsing
context. Some of the user interface elements represented by
these objects might have no equivalent in some user agents; for
those user agents, except when otherwise specified, the object must
act as if it was present and visible (i.e. its visible
attribute must return
true).
BarProp
objectBarProp
objectBarProp
objectBarProp
objectBarProp
objectvisible
attribute may return false).BarProp
objectvisible
attribute may return false).The locationbar
attribute must return the location bar BarProp
object.
The menubar
attribute must return the menu bar BarProp
object.
The personalbar
attribute must return the personal bar BarProp
object.
The scrollbars
attribute must return the scrollbar BarProp
object.
The statusbar
attribute
must return the status bar BarProp
object.
The toolbar
attribute must return the toolbar BarProp
object.
For historical reasons, the status
attribute on the
Window
object must return an empty string on getting,
and do nothing on setting.
WindowProxy
objectAs mentioned earlier, each browsing context has a
WindowProxy
object. This object is unusual
in that all operations that would be performed on it must be
performed on the Window
object of the browsing
context's active document instead. It is thus
indistinguishable from that Window
object in every way
until the browsing context is navigated.
There is no WindowProxy
interface object.
The WindowProxy
object allows scripts
to act as if each browsing context had a single
Window
object, while still keeping separate
Window
objects for each Document
.
In the following example, the variable x is
set to the WindowProxy
object returned by the window
accessor on the global object. All
of the expressions following the assignment return true, because in
every respect, the WindowProxy
object acts like the
underlying Window
object.
var x = window; x instanceof Window; // true x === this; // true
The origin of a resource and the effective script origin of a resource are both either opaque identifiers or tuples consisting of a scheme component, a host component, a port component, and optionally extra data.
The extra data could include the certificate of the site when using encrypted connections, to ensure that if the site's secure certificate changes, the origin is considered to change as well.
An origin or effective script origin can be defined as an alias to another origin or effective script origin. The value of the origin or effective script origin is then the value of the origin or effective script origin to which it is an alias.
These characteristics are defined as follows:
The origin and effective script origin of the URL are the origin defined in The Web Origin Concept. [ORIGIN]
Document
objectsDocument
's active
sandboxing flag set has its sandboxed origin
browsing context flag setThe origin is a globally unique identifier
assigned when the Document
is created.
The effective script origin is initially an
alias to the
origin of the Document
.
Document
was generated from a javascript:
URLThe origin is an alias to the
origin of the script of that javascript:
URL.
The effective script origin is initially an
alias to the
origin of the Document
.
Document
was served over the network and
has an address that uses a URL scheme with a server-based naming
authorityThe origin is an alias to the
origin of the Document
's
address.
The effective script origin is initially an
alias to the
origin of the Document
.
Document
was generated from a data:
URL that
was returned as the location of an HTTP redirect (or equivalent in
other protocols)The origin is an alias to the
origin of the URL that redirected to
the data:
URL.
The effective script origin is initially an
alias to the
origin of the Document
.
Document
was generated from a data:
URL
found in another Document
or in a scriptThe origin is an alias to the
origin of the Document
or script that
initiated the navigation to that
URL.
The effective script origin is initially an
alias to the
effective script origin of the
Document
or script that initiated the navigation to that URL.
Document
has the address
"about:blank
"The origin and effective script
origin of the Document
are those it was assigned when its
browsing context was created.
Document
is an iframe
srcdoc
documentThe origin of the Document
is an
alias to the
origin of the Document
's
browsing context's browsing context
container's Document
.
The effective script origin is initially an
alias to the
effective script origin of the
Document
's browsing context's
browsing context container's
Document
.
Document
was obtained in some other manner
(e.g. a data:
URL typed in by the user, a Document
created
using the createDocument()
API, etc)The origin is a globally unique identifier
assigned when the Document
is created.
The effective script origin is initially an
alias to the
origin of the Document
.
The effective script origin of a
Document
can be manipulated using the document.domain
IDL
attribute.
img
element and
its image data is CORS-cross-originimg
element and
its image data is CORS-same-originimg
element's
Document
.Images do not have an effective script origin.
audio
and video
elementsDocument
.Media elements do not have an effective script origin.
The origin of a downloadable Web font is an alias to the origin of the absolute URL used to obtain the font (after any redirects). [CSSFONTS]
The origin of a locally installed system font is
an alias to the
origin of the Document
in which that
font is being used.
Fonts do not have an effective script origin.
The origin and effective script origin of a script are determined from another resource, called the owner:
script
elementDocument
to which the
script
element belongs.Document
to which the
attribute node belongs.javascript:
URL that was returned as the
location of an HTTP redirect (or equivalent in
other protocols)javascript:
URL.javascript:
URL in an attributeDocument
of the element on
which the attribute is found.javascript:
URL in a style sheetjavascript:
URL to which a browsing
context is being navigated,
the URL having been provided by the user (e.g. by using a
bookmarklet)Document
of the browsing
context's active document.javascript:
URL to which a browsing
context is being navigated,
the URL having been declared in markupDocument
of the element
(e.g. an a
or area
element) that
declared the URL.javascript:
URL to which a browsing
context is being navigated,
the URL having been provided by scriptThe origin of the script is then an alias to the origin of the owner, and the effective script origin of the script is an alias to the effective script origin of the owner.
Other specifications can override the above definitions by
themselves specifying the origin of a particular URL,
Document
, image, media element, font, or
script.
The Unicode serialization of an origin is the string obtained by applying the following algorithm to the given origin:
If the origin in question is not a
scheme/host/port tuple, then return the literal string "null
" and abort these steps.
Otherwise, let result be the scheme part of the origin tuple.
Append the string "://
" to result.
Apply the IDNA ToUnicode algorithm to each component of the host part of the origin tuple, and append the results — each component, in the same order, separated by "." (U+002E) characters — to result. [RFC3490]
If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a ":" (U+003A) character and the given port, in base ten, to result.
Return result.
The ASCII serialization of an origin is the string obtained by applying the following algorithm to the given origin:
If the origin in question is not a
scheme/host/port tuple, then return the literal string "null
" and abort these steps.
Otherwise, let result be the scheme part of the origin tuple.
Append the string "://
" to result.
Apply the IDNA ToASCII algorithm the host part of the origin tuple, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, and append the results result.
If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then return the empty string and abort these steps. [RFC3490]
If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a ":" (U+003A) character and the given port, in base ten, to result.
Return result.
Two origins are said to be the same origin if the following algorithm returns true:
Let A be the first origin being compared, and B be the second origin being compared.
If A and B are both opaque identifiers, and their value is equal, then return true.
Otherwise, if either A or B or both are opaque identifiers, return false.
If A and B have scheme components that are not identical, return false.
If A and B have host components that are not identical, return false.
If A and B have port components that are not identical, return false.
If either A or B have additional data, but that data is not identical for both, return false.
Return true.
domain
[ = domain ]Returns the current domain used for security checks.
Can be set to a value that removes subdomains, to change the effective script origin to allow pages on other subdomains of the same domain (if they do the same thing) to access each other.
The domain
attribute on Document
objects must be initialized to
the document's domain, if it has one, and the empty
string otherwise. If the value is an IPv6 address, then the square
brackets from the host portion of the <host> component must be omitted from
the attribute's value.
On getting, the attribute must return its current value, unless
the Document
has no browsing context, in
which case it must return the empty string.
On setting, the user agent must run the following algorithm:
If the Document
has no browsing
context, throw a SecurityError
exception and
abort these steps.
If the new value is an IP address, let new value be the new value. Otherwise, apply the IDNA ToASCII algorithm to the new value, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, and let new value be the result of the ToASCII algorithm.
If ToASCII fails to convert one of the components of the
string, e.g. because it is too long or because it contains invalid
characters, then throw a SecurityError
exception and abort
these steps. [RFC3490]
If new value is not exactly equal to the
current value of the document.domain
attribute, then
run these substeps:
If the current value is an IP address, throw a
SecurityError
exception and abort these steps.
If new value, prefixed by a "." (U+002E), does not exactly match the end of the current value,
throw a SecurityError
exception and abort these
steps.
If new value matches a suffix in the
Public Suffix List, or, if new value,
prefixed by a "." (U+002E), matches the end of a
suffix in the Public Suffix List, then throw a
SecurityError
exception and abort these steps. [PSL]
Suffixes must be compared after applying the IDNA ToASCII algorithm to them, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, in an ASCII case-insensitive manner. [RFC3490]
Release the storage mutex.
Set the attribute's value to new value.
If the effective script origin of the
Document
is an alias, set it to the value of
the effective script origin (essentially de-aliasing
the effective script origin).
If new value is not the empty string, then run these substeps:
Set the host part of the effective script origin
tuple of the Document
to new
value.
Set the port part of the effective script origin
tuple of the Document
to "manual override" (a value
that, for the purposes of comparing
origins, is identical to "manual override" but not
identical to any other value).
The domain of a
Document
is the host part of the document's
origin, if the value of that origin is a
scheme/host/port tuple. If it isn't, then the document does not have
a domain.
The domain
attribute is used to enable pages on different hosts of a domain to
access each others' DOMs.
Do not use the document.domain
attribute when
using shared hosting. If an untrusted third party is able to host an
HTTP server at the same IP address but on a different port, then the
same-origin protection that normally protects two different sites on
the same host will fail, as the ports are ignored when comparing
origins after the document.domain
attribute has
been used.
A sandboxing flag set is a set of zero or more of the following flags, which are used to restrict the abilities that potentially untrusted resources have:
This flag prevents content from navigating browsing contexts other than the sandboxed browsing context itself (or browsing contexts further nested inside it), auxiliary browsing contexts (which are protected by the sandboxed auxiliary navigation browsing context flag defined next), and the top-level browsing context (which is protected by the sandboxed top-level navigation browsing context flag defined below).
If the sandboxed auxiliary navigation browsing context flag is not set, then in certain cases the restrictions nonetheless allow popups (new top-level browsing contexts) to be opened. These browsing contexts always have one permitted sandboxed navigator, set when the browsing context is created, which allows the browsing context that created them to actually navigate them. (Otherwise, the sandboxed navigation browsing context flag would prevent them from being navigated even if they were opened.)
This flag prevents content from
creating new auxiliary browsing contexts, e.g. using the target
attribute, the window.open()
method, or the showModalDialog()
method.
This flag prevents content from navigating their top-level browsing context.
When the allow-top-navigation
is set, content can navigate its top-level browsing
context, but other browsing
contexts are still protected by the sandboxed
navigation browsing context flag and possibly the
sandboxed auxiliary navigation browsing context
flag.
This flag prevents content from instantiating plugins, whether using the embed
element, the object
element,
the applet
element, or through navigation of a nested
browsing context, unless those plugins can be secured.
This flag prevents content from using the seamless
attribute on
descendant iframe
elements.
This prevents a page inserted using the allow-same-origin
keyword from using a CSS-selector-based method of probing the DOM
of other pages on the same site (in particular, pages that contain
user-sensitive information).
This flag forces content into a unique origin, thus preventing it from accessing other content from the same origin.
This flag also prevents script from
reading from or writing to the document.cookie
IDL
attribute, and blocks access to localStorage
.
[WEBSTORAGE]
This flag blocks form submission.
This flag blocks script execution.
This flag blocks features that trigger automatically, such as automatically playing a video or automatically focusing a form control.
When the user agent is to parse a sandboxing directive, given a string input and a sandboxing flag set output, it must run the following steps:
Split input on spaces, to obtain tokens.
Let output be empty.
Add the following flags to output:
The sandboxed auxiliary navigation browsing context
flag, unless tokens contains the allow-popups
keyword
The sandboxed top-level navigation browsing context
flag, unless tokens contains the allow-top-navigation
keyword
The sandboxed origin browsing context flag,
unless the tokens contains the allow-same-origin
keyword
The allow-same-origin
keyword is intended for two cases.
First, it can be used to allow content from the same site to be sandboxed to disable scripting, while still allowing access to the DOM of the sandboxed content.
Second, it can be used to embed content from a third-party site, sandboxed to prevent that site from opening popup windows, etc, without preventing the embedded page from communicating back to its originating site, using the database APIs to store data, etc.
The sandboxed forms browsing context flag,
unless tokens contains the allow-forms
keyword
The sandboxed scripts browsing context flag,
unless tokens contains the allow-scripts
keyword
The sandboxed automatic features browsing context
flag, unless tokens contains the
allow-scripts
keyword (defined above)
This flag is relaxed by the same keyword as scripts, because when scripts are enabled these features are trivially possible anyway, and it would be unfortunate to force authors to use script to do them when sandboxed rather than allowing them to use the declarative features.
Every top-level browsing context has a popup sandboxing flag set, which is a sandboxing flag set. When a browsing context is created, its popup sandboxing flag set must be empty. It is populated by the rules for choosing a browsing context given a browsing context name.
Every nested browsing context has an
iframe
sandboxing flag set, which is a
sandboxing flag set. Which flags in a nested
browsing context's iframe
sandboxing flag
set are set at any particular time is determined by the
iframe
element's sandbox
attribute.
Every Document
has an active sandboxing flag
set, which is a sandboxing flag set. When the
Document
is created, its active sandboxing flag
set must be empty. It is populated by the navigation algorithm.
Every resource that is obtained by the navigation algorithm has a forced sandboxing flag set, which is a sandboxing flag set. A resource by default has no flags set in its forced sandboxing flag set, but other specifications can define that certain flags are set.
In particular, the forced sandboxing flag set is used by the Content Security Policy specification. [CSP]
When a user agent is to implement the sandboxing for a Document
, it
must populate Document
's active sandboxing flag set with the union of
the flags that are present in the following sandboxing flag
sets at the time the Document
object is created:
If the Document
's browsing context is a top-level browsing
context, then: the flags set on the browsing context's popup sandboxing
flag set.
If the Document
's browsing context is a nested browsing
context, then: the flags set on the browsing context's
iframe
sandboxing flag set.
If the Document
's browsing context is a nested browsing
context, then: the flags set on the browsing context's parent browsing
context's active document's active sandboxing flag set.
The flags set on the Document
's resource's forced sandboxing flag
set, if it has one.
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 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 popup 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 location 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); void replaceState(any data, DOMString title, optional DOMString? url); };
history
. length
Returns the number of entries in the joint session history.
history
. state
Returns 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, 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, 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 a third argument is specified and 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 URLs are both hierarchical URLs.
If a third argument is not specified, or 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 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 { stringifier attribute DOMString href; void assign(DOMString url); void replace(DOMString url); void reload(); // URL decomposition IDL attributes attribute DOMString protocol; attribute DOMString host; attribute DOMString hostname; attribute DOMString port; attribute DOMString pathname; attribute DOMString search; attribute DOMString hash; };
href
[ = value ]Returns the current page's location.
Can be set, to navigate to another page.
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 href
attribute must return the
address of the associated Document
object, as an
absolute URL.
On setting, if the Location
object's associated
Document
object has completely loaded,
then the user agent must act as if the assign()
method had been called
with the new value as its argument. Otherwise, the user agent must
act as if the replace()
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 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 script that invoked the method as the
source browsing context.
If the resolving step of the
assign()
and replace()
methods is not
successful, then the user agent must instead throw a
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 current page of a browsing
context be reloaded through a user interface element, the
user agent should navigate the
browsing context to the same resource as
Document
, with replacement enabled. In the
case of non-idempotent methods (e.g. HTTP POST), the user agent
should prompt the user to confirm the operation first, since
otherwise transactions (e.g. purchases or database modifications)
could be repeated. User agents may allow the user to explicitly
override any caches when reloading. 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 has the complement of
URL decomposition IDL attributes, protocol
, host
, port
, hostname
, pathname
, search
, and hash
. These must follow the rules given for URL
decomposition IDL attributes, with the input being the 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.
User agents must throw a
SecurityError
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
replace()
method,
if the script is running in a browsing context that is
allowed to navigate the browsing context with which
the Location
object is associated
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 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.
Cancel any preexisting 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. (Previous navigation attempts whose fetch
requests have finished are unaffected, however.)
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.
Prompt to
unload the Document
object. If the user
refused to allow the document to be unloaded, then
abort these steps.
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 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, 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.
The fetch algorithm must delay the load event of the browsing context.
At this point, unless this step has already been reached once before in the execution of this instance of the algorithm, the user agents must return to whatever algorithm invoked the navigation steps and must continue these steps asynchronously.
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.
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.
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:
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.
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
.
Implement the sandboxing for the Document
.
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.
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.
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 Core, and other relevant specifications. [XML] [XMLNS] [RFC3023] [DOMCORE]
The actual HTTP headers and other metadata, not the headers as mutated or implied by the algorithms given in this specification, are the ones that must be used when determining the character encoding according to the rules given in the above specifications. Once the character encoding is established, the document's character encoding must be set to that character encoding.
If the root element, as parsed according to the XML
specifications cited above, is found to be an html
element with an attribute manifest
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 run the application cache
selection algorithm with the resulting absolute
URL with any <fragment> component removed as
the manifest URL, and passing in the newly-created
Document
. Otherwise, if the attribute is absent, 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 agents must update the session history with the new
page. User agents may do this before the complete document
has been parsed (thus achieving incremental rendering), and
must do this before any scripts are to be executed. If the Document
contains any element in the HTML namespace, the SVG namespace,
or in the MathML namespace then the user agent must render the
Document
according to the rendering section.
If not, then a native representation of the Document, e.g. a tree view of the corresponding
source, may be produced. In that case, abort the steps in this section, and jump to the next step in the navigate steps
above.
Error messages from the parse process (e.g. XML namespace
well-formedness errors) may be reported inline by mutating the
Document
.
Many existing user agents support the 'text/xsl
' (or
'application/xslt+xml
') style sheet type, with XSLT
[XSLT10] as the relevant supported styling
language. When the browsing context has a style sheet of that type,
such agents transform the current XML document using the XSLT stylesheet
retrieved from the style sheet location (typically supplied via an xml-stylesheet
processing instruction) and rendering (or otherwise processing) the
document that results from that transformation. The precise details
of this process are not defined yet.
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
"LF" (U+000A) 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, 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.
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 queue a task to 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. 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, it must either change the scrolling position of the document using the scroll an element into view algorithm defined in the CSSOM View specification, with the align to top flag set, 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 not scroll anywhere. [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.
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; stop the algorithm here.
Let decoded fragid be the result of expanding any sequences of percent-encoded octets in fragid that are valid UTF-8 sequences into Unicode characters as defined by UTF-8. If any percent-encoded octets in that string are not valid UTF-8 sequences (e.g. they expand to surrogate code points), then skip this step and the next one.
If this step was not skipped and there is an element in the DOM that has an ID exactly equal to decoded fragid, then the first such element in tree order is the indicated part of the document; stop the algorithm here.
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, 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 the following substeps:
If the browsing context is a top-level browsing
context, but not an auxiliary browsing
context, and the origin of the
Document
of the specified entry
is not the same as the
origin of the Document
of the
current entry, then 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.
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 input
elements whose resulting autocompletion state 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 pageshow
event 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 state changed is true, fire a popstate
event 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
hashchange
event 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; };
state
Returns 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; };
oldURL
Returns the URL of the session history entry that was previously current.
newURL
Returns 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; };
persisted
Returns 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 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
even and don't rerun the
unloading document visibility change steps).
Set the Document
's page showing
flag to false.
Fire a pagehide
event 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 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 salvageable and recycle are both 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.
[WEBSOCKET]
If this affected any WebSocket
objects, the 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.
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 the Document
has an active
parser, then abort that
parser.
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.
This section is non-normative.
In order to enable users to continue interacting with Web applications and documents even when their network connection is unavailable — for instance, because they are traveling outside of their ISP's coverage area — authors can provide a manifest which lists the files that are needed for the Web application to work offline and which causes the user's browser to keep a copy of the files for use offline.
To illustrate this, consider a simple clock applet consisting of
an HTML page "clock.html
", a CSS style sheet
"clock.css
", and a JavaScript script "clock.js
".
Before adding the manifest, these three files might look like this:
EXAMPLE offline/clock/clock1.html
EXAMPLE offline/clock/clock1.css
EXAMPLE offline/clock/clock1.js
If the user tries to open the "clock.html
"
page while offline, though, the user agent (unless it happens to
have it still in the local cache) will fail with an error.
The author can instead provide a manifest of the three files, say
"clock.appcache
":
EXAMPLE offline/clock/clock2.appcache
With a small change to the HTML file, the manifest (served as
text/cache-manifest
) is linked to the application:
EXAMPLE offline/clock/clock2.html
Now, if the user goes to the page, the browser will cache the files and make them available even when the user is offline.
Authors are encouraged to include the main page in the manifest also, but in practice the page that referenced the manifest is automatically cached even if it isn't explicitly mentioned.
With the exception of "no-store" directive, HTTP
cache headers and restrictions on caching pages served over TLS
(encrypted, using https:
) are overridden by
manifests. Thus, pages will not expire from an application cache
before the user agent has updated it, and even applications served
over TLS can be made to work offline.
This section is non-normative.
The application cache feature works best if the application logic is separate from the
application and user data, with the logic (markup, scripts, style sheets, images, etc) listed in
the manifest and stored in the application cache, with a finite number of static HTML pages for
the application, and with the application and user data stored in Web Storage or a client-side
Indexed Database, updated dynamically using Web Sockets, XMLHttpRequest
, server-sent
events, or some other similar mechanism.
This model results in a fast experience for the user: the application immediately loads, and fresh data is obtained as fast as the network will allow it (possibly while stale data shows).
Legacy applications, however, tend to be designed so that the user data and the logic are mixed together in the HTML, with each operation resulting in a new HTML page from the server.
For example, consider a news application. The typical architecture of such an application, when not using the application cache feature, is that the user fetches the main page, and the server returns a dynamically-generated page with the current headlines and the user interface logic mixed together.
A news application designed for the application cache feature, however, would instead have the
main page just consist of the logic, and would then have the main page fetch the data separately
from the server, e.g. using XMLHttpRequest
.
The mixed-content model does not work well with the application cache feature: since the content is cached, it would result in the user always seeing the stale data from the previous time the cache was updated.
While there is no way to make the legacy model work as fast as the separated model, it
can at least be retrofitted for offline use using the prefer-online application cache mode. To do so, list all the static
resources used by the HTML page you want to have work offline in an application cache manifest, use the manifest
attribute to select that manifest from the HTML file,
and then add the following line at the bottom of the manifest:
SETTINGS: prefer-online NETWORK: *
This causes the application cache to only be used for master entries when the user is offline, and causes the application cache to be used as an atomic HTTP cache (essentially pinning resources listed in the manifest), while allowing all resources not listed in the manifest to be accessed normally when the user is online.
This section is non-normative.
When the user visits a page that declares a manifest, the browser will try to update the cache. It does this by fetching a copy of the manifest and, if the manifest has changed since the user agent last saw it, redownloading all the resources it mentions and caching them anew.
As this is going on, a number of events get fired on the
ApplicationCache
object to keep the script updated as
to the state of the cache update, so that the user can be notified
appropriately. The events are as follows:
Event name | Interface | Fired when... | Next events |
---|---|---|---|
checking
| Event
| The user agent is checking for an update, or attempting to download the manifest for the first time. This is always the first event in the sequence. | noupdate , downloading , obsolete , error
|
noupdate
| Event
| The manifest hadn't changed. | Last event in sequence. |
downloading
| Event
| The user agent has found an update and is fetching it, or is downloading the resources listed by the manifest for the first time. | progress , error , cached , updateready
|
progress
| ProgressEvent
| The user agent is downloading resources listed by the manifest.
The event object's total attribute returns the total number of files to be downloaded.
The event object's loaded attribute returns the number of files processed so far.
| progress , error , cached , updateready
|
cached
| Event
| The resources listed in the manifest have been downloaded, and the application is now cached. | Last event in sequence. |
updateready
| Event
| The resources listed in the manifest have been newly redownloaded, and the script can use swapCache() to switch to the new cache.
| Last event in sequence. |
obsolete
| Event
| The manifest was found to have become a 404 or 410 page, so the application cache is being deleted. | Last event in sequence. |
error
| Event
| The manifest was a 404 or 410 page, so the attempt to cache the application has been aborted. | Last event in sequence. |
The manifest hadn't changed, but the page referencing the manifest failed to download properly. | |||
A fatal error occurred while fetching the resources listed in the manifest. | |||
The manifest changed while the update was being run. | The user agent will try fetching the files again momentarily. |
These events are cancelable; their default action is for the user agent to show download progress information. If the page shows its own update UI, canceling the events will prevent the user agent from showing redundant progress information.
An application cache is a set of cached resources consisting of:
One or more resources (including their out-of-band metadata, such as HTTP headers, if any), identified by URLs, each falling into one (or more) of the following categories:
These are documents that were added to the
cache because a browsing context was navigated to that document and the
document indicated that this was its cache, using the manifest
attribute.
This is the resource corresponding to the URL
that was given in a master entry's html
element's
manifest
attribute. The
manifest is fetched and processed during the application
cache download process. All the master entries have the
same origin as the manifest.
These are the resources that were listed in the cache's manifest in an explicit section.
These are the resources that were listed in the cache's manifest in a fallback section.
Explicit entries
and Fallback
entries can be marked as foreign, which means that
they have a manifest
attribute but that it doesn't point at this cache's manifest.
A URL in the list can be flagged with multiple different types, and thus an entry can end up being categorized as multiple entries. For example, an entry can be a manifest entry and an explicit entry at the same time, if the manifest is listed within the manifest.
Zero or more fallback namespaces, each of which is mapped to a fallback entry.
These are URLs used as prefix match patterns for resources that are to be fetched from the network if possible, or to be replaced by the corresponding fallback entry if not. Each namespace URL has the same origin as the manifest.
Zero or more URLs that form the online whitelist namespaces.
These are used as prefix match patterns, and declare URLs for which the user agent will ignore the application cache, instead fetching them normally (i.e. from the network or local HTTP cache as appropriate).
An online whitelist wildcard flag, which is either open or blocking.
The open state indicates that any URL not listed as cached is to be implicitly treated as being in the online whitelist namespaces; the blocking state indicates that URLs not listed explicitly in the manifest are to be treated as unavailable.
A cache mode flag, which is in the fast state.
Each application cache has a completeness flag, which is either complete or incomplete.
An application cache group is a group of application caches, identified by the absolute URL of a resource manifest which is used to populate the caches in the group.
An application cache is newer than another if it was created after the other (in other words, application caches in an application cache group have a chronological order).
Only the newest application cache in an application cache group can have its completeness flag set to incomplete; the others are always all complete.
Each application cache group has an update status, which is one of the following: idle, checking, downloading.
A relevant application cache is an application cache that is the newest in its group to be complete.
Each application cache group has a list of pending master
entries. Each entry in this list consists of a resource and a
corresponding Document
object. It is used during the
application cache download process to ensure that new
master entries are cached even if the application cache
download process was already running for their
application cache group when they were loaded.
An application cache group can be marked as obsolete, meaning that it must be ignored when looking at what application cache groups exist.
A cache host is a Document
or a
SharedWorkerGlobalScope
object. A cache
host can be associated with an application
cache.
[WEBWORKERS]
A Document
initially is not associated with an
application cache, but can become associated with one
early during the page load process, when steps in the parser and in the navigation sections cause cache selection to occur.
A SharedWorkerGlobalScope
can be associated with an
application cache when it is created.
[WEBWORKERS]
Each cache host has an associated
ApplicationCache
object.
Multiple application caches in different application cache groups can contain the same resource, e.g. if the manifests all reference that resource. If the user agent is to select an application cache from a list of relevant application caches that contain a resource, the user agent must use the application cache that the user most likely wants to see the resource from, taking into account the following:
A URL matches a fallback namespace if there exists a relevant application cache whose manifest's URL has the same origin as the URL in question, and that has a fallback namespace that is a prefix match for the URL being examined. If multiple fallback namespaces match the same URL, the longest one is the one that matches. A URL looking for a fallback namespace can match more than one application cache at a time, but only matches one namespace in each cache.
If a manifest http://example.com/app1/manifest
declares that
http://example.com/resources/images
is a
fallback namespace, and the user navigates to HTTP://EXAMPLE.COM:80/resources/images/cat.png
,
then the user agent will decide that the application cache
identified by http://example.com/app1/manifest
contains a
namespace with a match for that URL.
This section is non-normative.
This example manifest requires two images and a style sheet to be cached and whitelists a CGI script.
CACHE MANIFEST # the above line is required # this is a comment # there can be as many of these anywhere in the file # they are all ignored # comments can have spaces before them # but must be alone on the line # blank lines are ignored too # these are files that need to be cached they can either be listed # first, or a "CACHE:" header could be put before them, as is done # lower down. images/sound-icon.png images/background.png # note that each file has to be put on its own line # here is a file for the online whitelist -- it isn't cached, and # references to this file will bypass the cache, always hitting the # network (or trying to, if the user is offline). NETWORK: comm.cgi # here is another set of files to cache, this time just the CSS file. CACHE: style/default.css
It could equally well be written as follows:
CACHE MANIFEST NETWORK: comm.cgi CACHE: style/default.css images/sound-icon.png images/background.png
Offline application cache manifests can use absolute paths or even absolute URLs:
CACHE MANIFEST /main/home /main/app.js /settings/home /settings/app.js http://img.example.com/logo.png http://img.example.com/check.png http://img.example.com/cross.png
The following manifest defines a catch-all error page that is displayed for any page on the site while the user is offline. It also specifies that the online whitelist wildcard flag is open, meaning that accesses to resources on other sites will not be blocked. (Resources on the same site are already not blocked because of the catch-all fallback namespace.)
So long as all pages on the site reference this manifest, they will get cached locally as they are fetched, so that subsequent hits to the same page will load the page immediately from the cache. Until the manifest is changed, those pages will not be fetched from the server again. When the manifest changes, then all the files will be redownloaded.
Subresources, such as style sheets, images, etc, would only be cached using the regular HTTP caching semantics, however.
CACHE MANIFEST FALLBACK: / /offline.html NETWORK: *
Manifests must be served using the
text/cache-manifest
MIME type. All
resources served using the text/cache-manifest
MIME type must follow the syntax of application cache
manifests, as described in this section.
An application cache manifest is a text file, whose text is encoded using UTF-8. Data in application cache manifests is line-based. Newlines must be represented by "LF" (U+000A) characters, "CR" (U+000D) characters, or "CR" (U+000D) "LF" (U+000A) pairs. [RFC3629]
This is a willful violation of RFC
2046, which requires all text/*
types to only
allow CRLF line breaks. This requirement, however, is outdated; the
use of CR, LF, and CRLF line breaks is commonly supported and indeed
sometimes CRLF is not supported by text editors. [RFC2046]
The first line of an application cache manifest must consist of the string "CACHE", a single U+0020 SPACE character, the string "MANIFEST", and either a U+0020 SPACE character, a "tab" (U+0009) character, a "LF" (U+000A) character, or a "CR" (U+000D) character. The first line may optionally be preceded by a "BOM" (U+FEFF) character. If any other text is found on the first line, it is ignored.
Subsequent lines, if any, must all be one of the following:
Blank lines must consist of zero or more U+0020 SPACE and "tab" (U+0009) characters only.
Comment lines must consist of zero or more U+0020 SPACE and "tab" (U+0009) characters, followed by a single "#" (U+0023) character, followed by zero or more characters other than "LF" (U+000A) and "CR" (U+000D) characters.
Comments must be on a line on their own. If they were to be included on a line with a URL, the "#" would be mistaken for part of a fragment identifier.
Section headers change the current section. There are four possible section headers:
CACHE:
FALLBACK:
NETWORK:
Section header lines must consist of zero or more U+0020 SPACE and "tab" (U+0009) characters, followed by one of the names above (including the ":)" (U+003A) character followed by zero or more U+0020 SPACE and "tab" (U+0009) characters.
Ironically, by default, the current section is the explicit section.
The format that data lines must take depends on the current section.
When the current section is the explicit section, data lines must consist of zero or more U+0020 SPACE and "tab" (U+0009) characters, a valid URL identifying a resource other than the manifest itself, and then zero or more U+0020 SPACE and "tab" (U+0009) characters.
When the current section is the fallback section, data lines must consist of zero or more U+0020 SPACE and "tab" (U+0009) characters, a valid URL identifying a resource other than the manifest itself, one or more U+0020 SPACE and "tab" (U+0009) characters, another valid URL identifying a resource other than the manifest itself, and then zero or more U+0020 SPACE and "tab" (U+0009) characters.
When the current section is the online whitelist section, data lines must consist of zero or more U+0020 SPACE and "tab" (U+0009) characters, either a single "*" (U+002A) character or a valid URL identifying a resource other than the manifest itself, and then zero or more U+0020 SPACE and "tab" (U+0009) characters.
Manifests may contain sections more than once. Sections may be empty.
URLs that are to be fallback pages associated with fallback namespaces, and those namespaces themselves, must be given in fallback sections, with the namespace being the first URL of the data line, and the corresponding fallback page being the second URL. All the other pages to be cached must be listed in explicit sections.
Fallback namespaces and fallback entries must have the same origin as the manifest itself.
A fallback namespace must not be listed more than once.
Namespaces that the user agent is to put into the online whitelist must all be specified in online whitelist sections. (This is needed for any URL that the page is intending to use to communicate back to the server.) To specify that all URLs are automatically whitelisted in this way, a "*" (U+002A) character may be specified as one of the URLs.
Authors should not include namespaces in the online whitelist for which another namespace in the online whitelist is a prefix match.
Relative URLs must be given relative to the manifest's own URL. All URLs in the manifest must have the same <scheme> as the manifest itself (either explicitly or implicitly, through the use of relative URLs).
URLs in manifests must not have fragment identifiers (i.e. the U+0023 NUMBER SIGN character isn't allowed in URLs in manifests).
Fallback namespaces and namespaces in the online whitelist are matched by prefix match.
When a user agent is to parse a manifest, it means that the user agent must run the following steps:
The user agent must decode the byte stream corresponding with the manifest to be parsed as UTF-8, with error handling.
Let base URL be the absolute URL representing the manifest.
Let explicit URLs be an initially empty list of absolute URLs for explicit entries.
Let fallback URLs be an initially empty mapping of fallback namespaces to absolute URLs for fallback entries.
Let online whitelist namespaces be an initially empty list of absolute URLs for an online whitelist.
Let online whitelist wildcard flag be blocking.
Let cache mode flag be fast.
Let input be the decoded text of the manifest's byte stream.
Let position be a pointer into input, initially pointing at the first character.
If position is pointing at a "BOM" (U+FEFF) character, then advance position to the next character.
If the characters starting from position are "CACHE", followed by a U+0020 SPACE character, followed by "MANIFEST", then advance position to the next character after those. Otherwise, this isn't a cache manifest; abort this algorithm with a failure while checking for the magic signature.
If the character at position is neither a U+0020 SPACE character, a "tab" (U+0009) character, "LF" (U+000A) character, nor a "CR" (U+000D) character, then this isn't a cache manifest; abort this algorithm with a failure while checking for the magic signature.
This is a cache manifest. The algorithm cannot fail beyond this point (though bogus lines can get ignored).
Collect a sequence of characters that are not "LF" (U+000A) or "CR" (U+000D) characters, and ignore those characters. (Extra text on the first line, after the signature, is ignored.)
Let mode be "explicit".
Start of line: If position is past the end of input, then jump to the last step. Otherwise, collect a sequence of characters that are "LF" (U+000A), "CR" (U+000D), U+0020 SPACE, or "tab" (U+0009) characters.
Now, collect a sequence of characters that are not "LF" (U+000A) or "CR" (U+000D) characters, and let the result be line.
Drop any trailing U+0020 SPACE and "tab" (U+0009) characters at the end of line.
If line is the empty string, then jump back to the step labeled "start of line".
If the first character in line is a "#" (U+0023) character, then jump back to the step labeled "start of line".
If line equals "CACHE:" (the word "CACHE" followed by a ":)" (U+003A) character, then set mode to "explicit" and jump back to the step labeled "start of line".
If line equals "FALLBACK:" (the word "FALLBACK" followed by a ":)" (U+003A) character, then set mode to "fallback" and jump back to the step labeled "start of line".
If line equals "NETWORK:" (the word "NETWORK" followed by a ":)" (U+003A) character, then set mode to "online whitelist" and jump back to the step labeled "start of line".
If line ends with a ":" (U+003A) character, then set mode to "unknown" and jump back to the step labeled "start of line".
This is either a data line or it is syntactically incorrect.
Let position be a pointer into line, initially pointing at the start of the string.
Let tokens be a list of strings, initially empty.
While position doesn't point past the end of line:
Let current token be an empty string.
While position doesn't point past the end of line and the character at position is neither a U+0020 SPACE nor a "tab" (U+0009) character, add the character at position to current token and advance position to the next character in input.
Add current token to the tokens list.
While position doesn't point past the end of line and the character at position is either a U+0020 SPACE or a "tab" (U+0009) character, advance position to the next character in input.
Process tokens as follows:
Resolve the first item in tokens, relative to base URL; ignore the rest.
If this fails, then jump back to the step labeled "start of line".
If the resulting absolute URL has a different <scheme> component than the manifest's URL (compared in an ASCII case-insensitive manner), then jump back to the step labeled "start of line".
Drop the <fragment> component of the resulting absolute URL, if it has one.
Add the resulting absolute URL to the explicit URLs.
Let part one be the first token in tokens, and let part two be the second token in tokens.
Resolve part one and part two, relative to base URL.
If either fails, then jump back to the step labeled "start of line".
If the absolute URL corresponding to either part one or part two does not have the same origin as the manifest's URL, then jump back to the step labeled "start of line".
Drop any <fragment> components of the resulting absolute URLs.
If the absolute URL corresponding to part one is already in the fallback URLs mapping as a fallback namespace, then jump back to the step labeled "start of line".
Otherwise, add the absolute URL corresponding to part one to the fallback URLs mapping as a fallback namespace, mapped to the absolute URL corresponding to part two as the fallback entry.
If the first item in tokens is a "*" (U+002A) character, then set online whitelist wildcard flag to open and jump back to the step labeled "start of line".
Otherwise, resolve the first item in tokens, relative to base URL; ignore the rest.
If this fails, then jump back to the step labeled "start of line".
If the resulting absolute URL has a different <scheme> component than the manifest's URL (compared in an ASCII case-insensitive manner), then jump back to the step labeled "start of line".
Drop the <fragment> component of the resulting absolute URL, if it has one.
Add the resulting absolute URL to the online whitelist namespaces.
Do nothing. The line is ignored.
Jump back to the step labeled "start of line". (That step jumps to the next, and last, step when the end of the file is reached.)
Return the explicit URLs list, the fallback URLs mapping, the online whitelist namespaces, the online whitelist wildcard flag, and the cache mode flag.
The resource that declares the manifest (with the manifest
attribute) will always
get taken from the cache, whether it is listed in the cache or not,
even if it is listed in an online whitelist
namespace.
If a resource is listed in the explicit section or as a fallback entry in the fallback section, the resource will always be taken from the cache, regardless of any other matching entries in the fallback namespaces or online whitelist namespaces.
When a fallback namespace and an online whitelist namespace overlap, the online whitelist namespace has priority.
The online whitelist wildcard flag is applied last, only for URLs that match neither the online whitelist namespace nor the fallback namespace and that are not listed in the explicit section.
When the user agent is required (by other parts of this specification) to start the application cache download process for an absolute URL purported to identify a manifest, or for an application cache group, potentially given a particular cache host, and potentially given a master resource, the user agent must run the steps below. These steps are always run asynchronously, in parallel with the event loop tasks.
Some of these steps have requirements that only apply if the user agent shows caching progress. Support for this is optional. Caching progress UI could consist of a progress bar or message panel in the user agent's interface, or an overlay, or something else. Certain events fired during the application cache download process allow the script to override the display of such an interface. The goal of this is to allow Web applications to provide more seamless update mechanisms, hiding from the user the mechanics of the application cache mechanism. User agents may display user interfaces independent of this, but are encouraged to not show prominent update progress notifications for applications that cancel the relevant events.
These events are delayed until after the load
event has fired.
The application cache download process steps are as follows:
Optionally, wait until the permission to start the application cache download process has been obtained from the user and until the user agent is confident that the network is available. This could include doing nothing until the user explicitly opts-in to caching the site, or could involve prompting the user for permission. The algorithm might never get past this point. (This step is particularly intended to be used by user agents running on severely space-constrained devices or in highly privacy-sensitive environments).
Atomically, so as to avoid race conditions, perform the following substeps:
Pick the appropriate substeps:
Let manifest URL be that absolute URL.
If there is no application cache group identified by manifest URL, then create a new application cache group identified by manifest URL. Initially, it has no application caches. One will be created later in this algorithm.
Let manifest URL be the absolute URL of the manifest used to identify the application cache group to be updated.
If that application cache group is obsolete, then abort this instance of the application cache download process. This can happen if another instance of this algorithm found the manifest to be 404 or 410 while this algorithm was waiting in the first step above.
Let cache group be the application cache group identified by manifest URL.
If these steps were invoked with a master resource, then add
the resource, along with the resource's Document
, to
cache group's list of pending master
entries.
If these steps were invoked with a cache
host, and the status of cache group is checking or
downloading, then queue a post-load task to
fire a simple event named checking
that is
cancelable at the ApplicationCache
singleton of that
cache host. The default action of this event must
be, if the user agent shows caching progress, the
display of some sort of user interface indicating to the user
that the user agent is checking to see if it can download the
application.
If these steps were invoked with a cache
host, and the status of cache group is downloading, then also
queue a post-load task to fire a simple
event named downloading
that is
cancelable at the ApplicationCache
singleton of that
cache host. The default action of this event must
be, if the user agent shows caching progress, the
display of some sort of user interface indicating to the user the
application is being downloaded.
If the status of the cache group is either checking or downloading, then abort this instance of the application cache download process, as an update is already in progress.
Set the status of cache group to checking.
For each cache host associated with an
application cache in cache
group, queue a post-load task to fire a
simple event that is cancelable named checking
at the
ApplicationCache
singleton of the cache
host. The default action of these events must be, if the
user agent shows caching progress, the display of
some sort of user interface indicating to the user that the user
agent is checking for the availability of updates.
The remainder of the steps run asynchronously.
If cache group already has an application cache in it, then this is an upgrade attempt. Otherwise, this is a cache attempt.
If this is a cache
attempt, then this algorithm was invoked with a cache
host; queue a post-load task to fire a
simple event named checking
that is cancelable
at the ApplicationCache
singleton of that cache
host. The default action of this event must be, if the user
agent shows caching progress, the display of some sort
of user interface indicating to the user that the user agent is
checking for the availability of updates.
Fetching the manifest: Fetch the resource from manifest URL with the synchronous flag set, and let manifest be that resource. HTTP caching semantics should be honored for this request.
Parse manifest according to the rules for parsing manifests, obtaining a list of explicit entries, fallback entries and the fallback namespaces that map to them, entries for the online whitelist, and values for the online whitelist wildcard flag and the cache mode flag.
The MIME type of the resource is
ignored — it is assumed to be
text/cache-manifest
. In the future, if new manifest
formats are supported, the different types will probably be
distinguished on the basis of the file signatures (for the current
format, that is the "CACHE MANIFEST
"
string at the top of the file).
If fetching the manifest fails due to a 404 or 410 response or equivalent, then run these substeps:
Mark cache group as obsolete. This cache group no longer exists for any purpose other
than the processing of Document
objects already
associated with an application cache in the cache group.
Let task list be an empty list of tasks.
For each cache host associated with an
application cache in cache
group, create a task to
fire a simple event named obsolete
that is
cancelable at the ApplicationCache
singleton of the
cache host, and append it to task
list. The default action of these events must be, if the
user agent shows caching progress, the display of
some sort of user interface indicating to the user that the
application is no longer available for offline use.
For each entry in cache group's list of pending master
entries, create a task
to fire a simple event that is cancelable named
error
(not obsolete
!) at the
ApplicationCache
singleton of the
Document
for this entry, if there still is one, and
append it to task list. The default action of
this event must be, if the user agent shows caching
progress, the display of some sort of user interface
indicating to the user that the user agent failed to save the
application for offline use.
If cache group has an application cache whose completeness flag is incomplete, then discard that application cache.
If appropriate, remove any user interface indicating that an update for this cache is in progress.
Let the status of cache group be idle.
For each task in task list, queue that task as a post-load task.
Abort the application cache download process.
Otherwise, if fetching the manifest fails in some other way (e.g. the server returns another 4xx or 5xx response or equivalent, or there is a DNS error, or the connection times out, or the user cancels the download, or the parser for manifests fails when checking the magic signature), or if the server returned a redirect, then run the cache failure steps. [HTTP]
If this is an upgrade attempt and the newly downloaded manifest is byte-for-byte identical to the manifest found in the newest application cache in cache group, or the server reported it as "304 Not Modified" or equivalent, then run these substeps:
Let cache be the newest application cache in cache group.
Let task list be an empty list of tasks.
For each entry in cache group's list of pending master entries, wait for the resource for this entry to have either completely downloaded or failed.
If the download failed (e.g. the server returns a 4xx or 5xx
response or
equivalent, or there is a DNS error, the connection times
out, or the user cancels the download), or if the resource is
labeled with the "no-store" cache directive, then create a task to fire a simple
event that is cancelable named error
at the
ApplicationCache
singleton of the
Document
for this entry, if there still is one, and
append it to task list. The default action
of this event must be, if the user agent shows caching
progress, the display of some sort of user interface
indicating to the user that the user agent failed to save the
application for offline use.
Otherwise, associate the Document
for this entry
with cache; store the resource for this
entry in cache, if it isn't already there,
and categorize its entry as a master entry. If the
resource's URL has a <fragment> component, it must
be removed from the entry in cache
(application caches never include fragment identifiers).
For each cache host associated with an
application cache in cache
group, create a task to
fire a simple event that is cancelable named noupdate
at the
ApplicationCache
singleton of the cache
host, and append it to task list. The
default action of these events must be, if the user agent
shows caching progress, the display of some sort of
user interface indicating to the user that the application is up
to date.
Empty cache group's list of pending master entries.
If appropriate, remove any user interface indicating that an update for this cache is in progress.
Let the status of cache group be idle.
For each task in task list, queue that task as a post-load task.
Abort the application cache download process.
Let new cache be a newly created application cache in cache group. Set its completeness flag to incomplete.
For each entry in cache group's list of pending master
entries, associate the Document
for this entry
with new cache.
Set the status of cache group to downloading.
For each cache host associated with an
application cache in cache group,
queue a post-load task to fire a simple
event that is cancelable named downloading
at the
ApplicationCache
singleton of the cache
host. The default action of these events must be, if the
user agent shows caching progress, the display of some
sort of user interface indicating to the user that a new version is
being downloaded.
Let file list be an empty list of URLs with flags.
Add all the URLs in the list of explicit entries obtained by parsing manifest to file list, each flagged with "explicit entry".
Add all the URLs in the list of fallback entries obtained by parsing manifest to file list, each flagged with "fallback entry".
If this is an upgrade attempt, then add all the URLs of master entries in the newest application cache in cache group whose completeness flag is complete to file list, each flagged with "master entry".
If any URL is in file list more than once, then merge the entries into one entry for that URL, that entry having all the flags that the original entries had.
For each URL in file list, run the
following steps. These steps may be run in parallel for two or
more of the URLs at a time. If, while running these steps, the
ApplicationCache
object's abort()
method sends a signal to this instance of the
application cache download process algorithm, then
run the cache failure steps instead.
If the resource URL being processed was flagged as neither an "explicit entry" nor or a "fallback entry", then the user agent may skip this URL.
This is intended to allow user agents to expire resources not listed in the manifest from the cache. Generally, implementors are urged to use an approach that expires lesser-used resources first.
For each cache host associated with an
application cache in cache
group, queue a post-load task to fire an event
with the name progress
, which does not
bubble, which is cancelable, and which uses the
ProgressEvent
interface, at the
ApplicationCache
singleton of the cache
host. The lengthComputable
attribute must be set to true, the total
attribute must be
set to the number of files in file list, and
the loaded
attribute must be set to the number of files in file list that have been either downloaded or
skipped so far. The default action of these events must be, if
the user agent shows caching progress, the display
of some sort of user interface indicating to the user that a file
is being downloaded in preparation for updating the application.
[PROGRESS]
Fetch the resource, from the origin of the URL manifest URL, with the synchronous flag set and the manual redirect flag set. If this is an upgrade attempt, then use the newest application cache in cache group as an HTTP cache, and honor HTTP caching semantics (such as expiration, ETags, and so forth) with respect to that cache. User agents may also have other caches in place that are also honored.
If the resource in question is already being downloaded for other reasons then the existing download process can sometimes be used for the purposes of this step, as defined by the fetching algorithm.
An example of a resource that might already
be being downloaded is a large image on a Web page that is being
seen for the first time. The image would get downloaded to
satisfy the img
element on the page, as well as
being listed in the cache manifest. According to the rules for
fetching that image only need be
downloaded once, and it can be used both for the cache and for
the rendered Web page.
If the previous step fails (e.g. the server returns a 4xx or 5xx response or equivalent, or there is a DNS error, or the connection times out, or the user cancels the download), or if the server returned a redirect, or if the resource is labeled with the "no-store" cache directive, then run the first appropriate step from the following list: [HTTP]
If these steps are being run in parallel for any other URLs in file list, then abort these steps for those other URLs. Run the cache failure steps.
Redirects are fatal because they are either indicative of a network problem (e.g. a captive portal); or would allow resources to be added to the cache under URLs that differ from any URL that the networking model will allow access to, leaving orphan entries; or would allow resources to be stored under URLs different than their true URLs. All of these situations are bad.
Skip this resource. It is dropped from the cache.
Copy the resource and its metadata from the newest application cache in cache group whose completeness flag is complete, and act as if that was the fetched resource, ignoring the resource obtained from the network.
User agents may warn the user of these errors as an aid to development.
These rules make errors for resources listed in the manifest fatal, while making it possible for other resources to be removed from caches when they are removed from the server, without errors, and making non-manifest resources survive server-side errors.
Except for the "no-store" directive, HTTP caching rules that would cause a file to be expired or otherwise not cached are ignored for the purposes of the application cache download process.
Otherwise, the fetching succeeded. Store the resource in the new cache.
If the user agent is not able to store the resource (e.g. because of quota restrictions), the user agent may prompt the user or try to resolve the problem in some other manner (e.g. automatically pruning content in other caches). If the problem cannot be resolved, the user agent must run the cache failure steps.
If the URL being processed was flagged as an "explicit entry" in file list, then categorize the entry as an explicit entry.
If the URL being processed was flagged as a "fallback entry" in file list, then categorize the entry as a fallback entry.
If the URL being processed was flagged as an "master entry" in file list, then categorize the entry as a master entry.
As an optimization, if the resource is an HTML or XML file
whose root element is an html
element with a manifest
attribute whose value
doesn't match the manifest URL of the application cache being
processed, then the user agent should mark the entry as being
foreign.
For each cache host associated with an
application cache in cache group,
queue a post-load task to fire an event with the name
progress
, which does
not bubble, which is cancelable, and which uses the
ProgressEvent
interface, at the
ApplicationCache
singleton of the cache
host. The lengthComputable
attribute must be set to true, the total
and the loaded
attributes must be
set to the number of files in file list. The
default action of these events must be, if the user agent
shows caching progress, the display of some sort of
user interface indicating to the user that all the files have been
downloaded. [PROGRESS]
Store the list of fallback namespaces, and the URLs of the fallback entries that they map to, in new cache.
Store the URLs that form the new online whitelist in new cache.
Store the value of the new online whitelist wildcard flag in new cache.
Store the value of the new cache mode flag in new cache.
For each entry in cache group's list of pending master entries, wait for the resource for this entry to have either completely downloaded or failed.
If the download failed (e.g. the server returns a 4xx or 5xx response or equivalent, or there is a DNS error, the connection times out, or the user cancels the download), or if the resource is labeled with the "no-store" cache directive, then run these substeps:
Unassociate the Document
for this entry from
new cache.
Queue a post-load task to fire a simple
event that is cancelable named error
at the
ApplicationCache
singleton of the
Document
for this entry, if there still is one. The
default action of this event must be, if the user agent
shows caching progress, the display of some sort of
user interface indicating to the user that the user agent failed
to save the application for offline use.
If this is a cache attempt and this entry is the last entry in cache group's list of pending master entries, then run these further substeps:
Discard cache group and its only application cache, new cache.
If appropriate, remove any user interface indicating that an update for this cache is in progress.
Abort the application cache download process.
Otherwise, remove this entry from cache group's list of pending master entries.
Otherwise, store the resource for this entry in new cache, if it isn't already there, and categorize its entry as a master entry.
Fetch the resource from manifest URL again, with the synchronous flag set, and let second manifest be that resource. HTTP caching semantics should again be honored for this request.
Since caching can be honored, authors are encouraged to avoid setting the cache headers on the manifest in such a way that the user agent would simply not contact the network for this second request; otherwise, the user agent would not notice if the cache had changed during the cache update process.
If the previous step failed for any reason, or if the fetching attempt involved a redirect, or if second manifest and manifest are not byte-for-byte identical, then schedule a rerun of the entire algorithm with the same parameters after a short delay, and run the cache failure steps.
Otherwise, store manifest in new cache, if it's not there already, and categorize its entry as the manifest.
Set the completeness flag of new cache to complete.
Let task list be an empty list of tasks.
If this is a cache
attempt, then for each cache host associated
with an application cache in cache
group, create a task to
fire a simple event that is cancelable named cached
at the
ApplicationCache
singleton of the cache
host, and append it to task list. The
default action of these events must be, if the user agent
shows caching progress, the display of some sort of
user interface indicating to the user that the application has
been cached and that they can now use it offline.
Otherwise, it is an upgrade attempt. For each
cache host associated with an application
cache in cache group, create a task to fire a simple
event that is cancelable named updateready
at the
ApplicationCache
singleton of the cache
host, and append it to task list. The
default action of these events must be, if the user agent
shows caching progress, the display of some sort of
user interface indicating to the user that a new version is
available and that they can activate it by reloading the page.
If appropriate, remove any user interface indicating that an update for this cache is in progress.
Set the update status of cache group to idle.
For each task in task list, queue that task as a post-load task.
The cache failure steps are as follows:
Let task list be an empty list of tasks.
For each entry in cache group's list of pending master entries, run the following further substeps. These steps may be run in parallel for two or more entries at a time.
Wait for the resource for this entry to have either completely downloaded or failed.
Unassociate the Document
for this entry from
its application cache, if it has one.
Create a task to
fire a simple event that is cancelable named error
at the
ApplicationCache
singleton of the
Document
for this entry, if there still is one, and
append it to task list. The default action of
these events must be, if the user agent shows caching
progress, the display of some sort of user interface
indicating to the user that the user agent failed to save the
application for offline use.
For each cache host still associated with an
application cache in cache group,
create a task to fire a
simple event that is cancelable named error
at the
ApplicationCache
singleton of the cache
host, and append it to task list. The
default action of these events must be, if the user agent
shows caching progress, the display of some sort of
user interface indicating to the user that the user agent failed to
save the application for offline use.
Empty cache group's list of pending master entries.
If cache group has an application cache whose completeness flag is incomplete, then discard that application cache.
If appropriate, remove any user interface indicating that an update for this cache is in progress.
Let the status of cache group be idle.
If this was a cache attempt, discard cache group altogether.
For each task in task list, queue that task as a post-load task.
Abort the application cache download process.
Attempts to fetch resources as part of the application cache download process may be done with cache-defeating semantics, to avoid problems with stale or inconsistent intermediary caches.
User agents may invoke the application cache download process, in the background, for any application cache group, at any time (with no cache host). This allows user agents to keep caches primed and to update caches even before the user visits a site.
Each Document
has a list of pending application
cache download process tasks that is used to delay events
fired by the algorithm above until the document's load
event has fired. When the
Document
is created, the list must be empty.
When the steps above say to queue a post-load task
task, where task is a task that dispatches an event on a
target ApplicationCache
object target, the user agent must run the appropriate steps
from the following list:
Document
is
ready for post-load tasksQueue the task task.
Add task to target's
Document
's list of pending application cache
download process tasks.
The task source for these tasks is the networking task source.
When the application cache
selection algorithm algorithm is invoked with a
Document
document and optionally a
manifest URL manifest URL, the user
agent must run the first applicable set of steps from the following
list:
Mark the entry for the resource from which document was taken in the application cache from which it was loaded as foreign.
Restart the current navigation from the top of the navigation algorithm, undoing any changes that were made as part of the initial load (changes can be avoided by ensuring that the step to update the session history with the new page is only ever completed after this application cache selection algorithm is run, though this is not required).
The navigation will not result in the same resource being loaded, because "foreign" entries are never picked during navigation.
User agents may notify the user of the inconsistency between the cache manifest and the document's own metadata, to aid in application development.
Associate document with the application cache from which it was loaded. Invoke, in the background, the application cache download process for that application cache's application cache group, with document as the cache host.
Invoke, in the background, the application cache download process for manifest URL, with document as the cache host and with the resource from which document was parsed as the master resource.
If there are relevant application caches that are identified by a URL with the same origin as the URL of document, and that have this URL as one of their entries, excluding entries marked as foreign, then the user agent should use the most appropriate application cache of those that match as an HTTP cache for any subresource loads. User agents may also have other caches in place that are also honored.
The Document
is not associated with any
application cache.
If there was a manifest URL, the user agent may report to the user that it was ignored, to aid in application development.
When a cache host is associated with an application cache whose completeness flag is complete, any and all loads for resources related to that cache host other than those for child browsing contexts must go through the following steps instead of immediately invoking the mechanisms appropriate to that resource's scheme:
If the resource is not to be fetched using the HTTP GET mechanism or equivalent, or if its URL has a different <scheme> component than the application cache's manifest, then fetch the resource normally and abort these steps.
If the resource's URL is a master entry, the manifest, an explicit entry, or a fallback entry in the application cache, then get the resource from the cache (instead of fetching it), and abort these steps.
If there is an entry in the application cache's online whitelist that has the same origin as the resource's URL and that is a prefix match for the resource's URL, then fetch the resource normally and abort these steps.
If the resource's URL has the same origin as the manifest's URL, and there is a fallback namespace f in the application cache that is a prefix match for the resource's URL, then:
Fetch the resource normally. If this results in a redirect to a resource with another origin (indicative of a captive portal), or a 4xx or 5xx status code or equivalent, or if there were network errors (but not if the user canceled the download), then instead get, from the cache, the resource of the fallback entry corresponding to the fallback namespace f. Abort these steps.
If the application cache's online whitelist wildcard flag is open, then fetch the resource normally and abort these steps.
Fail the resource load as if there had been a generic network error.
The above algorithm ensures that so long as the online whitelist wildcard flag is blocking, resources that are not present in the manifest will always fail to load (at least, after the application cache has been primed the first time), making the testing of offline applications simpler.
As a general rule, user agents should not expire application caches, except on request from the user, or after having been left unused for an extended period of time.
Application caches and cookies have similar implications with respect to privacy (e.g. if the site can identify the user when providing the cache, it can store data in the cache that can be used for cookie resurrection). Implementors are therefore encouraged to expose application caches in a manner related to HTTP cookies, allowing caches to be expunged together with cookies and other origin-specific data.
For example, a user agent could have a "delete site-specific data" feature that clears all cookies, application caches, local storage, databases, etc, from an origin all at once.
User agents should consider applying constraints on disk usage of application caches, and care should be taken to ensure that the restrictions cannot be easily worked around using subdomains.
User agents should allow users to see how much space each domain is using, and may offer the user the ability to delete specific application caches.
How quotas are presented to the user is not defined by this specification. User agents are encouraged to provide features such as allowing a user to indicate that certain sites are trusted to use more than the default quota, e.g. by asynchronously presenting a user interface while a cache is being updated, or by having an explicit whitelist in the user agent's configuration interface.
interface ApplicationCache : EventTarget { // update status const unsigned short UNCACHED = 0; const unsigned short IDLE = 1; const unsigned short CHECKING = 2; const unsigned short DOWNLOADING = 3; const unsigned short UPDATEREADY = 4; const unsigned short OBSOLETE = 5; readonly attribute unsigned short status; // updates void update(); void abort(); void swapCache(); // events attribute EventHandler onchecking; attribute EventHandler onerror; attribute EventHandler onnoupdate; attribute EventHandler ondownloading; attribute EventHandler onprogress; attribute EventHandler onupdateready; attribute EventHandler oncached; attribute EventHandler onobsolete; };
applicationCache
(In a window.) Returns the ApplicationCache
object that applies to the active document of that Window
.
applicationCache
(In a shared worker.) Returns the ApplicationCache
object that applies to the current shared worker.
[WEBWORKERS]
status
Returns the current status of the application cache, as given by the constants defined below.
update
()Invokes the application cache download process.
Throws an InvalidStateError
exception if there is no application cache to update.
Calling this method is not usually necessary, as user agents will generally take care of updating application caches automatically.
The method can be useful in situations such as long-lived applications. For example, a Web mail application might stay open in a browser tab for weeks at a time. Such an application could want to test for updates each day.
abort
()Cancels the application cache download process.
This method is intended to be used by Web application showing their own caching progress UI, in case the user wants to stop the update (e.g. because bandwidth is limited).
swapCache
()Switches to the most recent application cache, if there is a
newer one. If there isn't, throws an
InvalidStateError
exception.
This does not cause previously-loaded resources to be reloaded; for example, images do not suddenly get reloaded and style sheets and scripts do not get reparsed or reevaluated. The only change is that subsequent requests for cached resources will obtain the newer copies.
The updateready
event will fire before this method can be called. Once it fires,
the Web application can, at its leisure, call this method to
switch the underlying cache to the one with the more recent
updates. To make proper use of this, applications have to be able
to bring the new features into play; for example, reloading
scripts to enable new features.
An easier alternative to swapCache()
is just to
reload the entire page at a time suitable for the user, using
location.reload()
.
There is a one-to-one mapping from cache
hosts to ApplicationCache
objects. The applicationCache
attribute on Window
objects must return the
ApplicationCache
object associated with the
Window
object's active document. The applicationCache
attribute on SharedWorkerGlobalScope
objects must
return the ApplicationCache
object associated with the
worker.
[WEBWORKERS]
A Window
or
SharedWorkerGlobalScope
object has an associated
ApplicationCache
object even if that cache
host has no actual application cache.
The status
attribute, on getting, must return the current state of the
application cache that the
ApplicationCache
object's cache host is
associated with, if any. This must be the appropriate value from the
following list:
UNCACHED
(numeric value 0)The ApplicationCache
object's cache
host is not associated with an application
cache at this time.
IDLE
(numeric value 1)The ApplicationCache
object's cache
host is associated with an application cache
whose application cache group's update status is
idle, and that application cache is the newest cache in its
application cache group, and the application
cache group is not marked as obsolete.
CHECKING
(numeric value 2)The ApplicationCache
object's cache
host is associated with an application cache
whose application cache group's update status is
checking.
DOWNLOADING
(numeric value 3)The ApplicationCache
object's cache
host is associated with an application cache
whose application cache group's update status is
downloading.
UPDATEREADY
(numeric value 4)The ApplicationCache
object's cache
host is associated with an application cache
whose application cache group's update status is
idle, and whose application cache group is not
marked as obsolete,
but that application cache is not the newest cache in its
group.
OBSOLETE
(numeric value 5)The ApplicationCache
object's cache
host is associated with an application cache
whose application cache group is marked as obsolete.
If the update()
method is
invoked, the user agent must invoke the application cache
download process, in the background, for the
application cache group of the application
cache with which the ApplicationCache
object's
cache host is associated, but without giving that
cache host to the algorithm. If there is no such
application cache, or if its application cache
group is marked as obsolete, then the method
must throw an InvalidStateError
exception instead.
If the abort()
method is invoked, the user agent must send a signal to
the current application cache download process for the
application cache group of the application
cache with which the ApplicationCache
object's
cache host is associated, if any. If there is no such
application cache, or it does not have a current
application cache download process, then do
nothing.
If the swapCache()
method
is invoked, the user agent must run the following steps:
Check that ApplicationCache
object's
cache host is associated with an application
cache. If it is not, then throw an
InvalidStateError
exception and abort these
steps.
Let cache be the application
cache with which the ApplicationCache
object's
cache host is associated. (By definition, this is the
same as the one that was found in the previous step.)
If cache's application cache
group is marked as obsolete, then unassociate
the ApplicationCache
object's cache host
from cache and abort these steps. (Resources
will now load from the network instead of the cache.)
Check that there is an application cache in the same
application cache group as cache
whose completeness
flag is complete and that is newer than cache. If there is not, then throw an
InvalidStateError
exception and abort these
steps.
Let new cache be the newest application cache in the same application cache group as cache whose completeness flag is complete.
Unassociate the ApplicationCache
object's
cache host from cache and instead
associate it with new cache.
The following are the event handlers (and their
corresponding event handler
event types) that must be supported, as IDL attributes, by
all objects implementing the ApplicationCache
interface:
Event handler | Event handler event type |
---|---|
onchecking | checking
|
onerror | error
|
onnoupdate | noupdate
|
ondownloading | downloading
|
onprogress | progress
|
onupdateready | updateready
|
oncached | cached
|
onobsolete | obsolete
|
[NoInterfaceObject] interface NavigatorOnLine { readonly attribute boolean onLine; };
navigator
. onLine
Returns false if the user agent is definitely offline (disconnected from the network). Returns true if the user agent might be online.
The events online
and offline
are fired when the value of
this attribute changes.
The navigator.onLine
attribute must return false if the user agent will not contact the
network when the user follows links or when a script requests a
remote page (or knows that such an attempt would fail), and must
return true otherwise.
When the value that would be returned by the navigator.onLine
attribute of a
Window
or WorkerGlobalScope
changes from
true to false, the user agent must queue a task to
fire a simple event named offline
at the
Window
or WorkerGlobalScope
object.
On the other hand, when the value that would be returned by the
navigator.onLine
attribute
of a Window
or WorkerGlobalScope
changes
from false to true, the user agent must queue a task to
fire a simple event named online
at the
Window
or WorkerGlobalScope
object.
The task source for these tasks is the networking task source.
This attribute is inherently unreliable. A computer can be connected to a network without having Internet access.
In this example, an indicator is updated as the browser goes online and offline.
<!DOCTYPE HTML> <html> <head> <title>Online status</title> <script> function updateIndicator() { document.getElementById('indicator').textContent = navigator.onLine ? 'online' : 'offline'; } </script> </head> <body onload="updateIndicator()" ononline="updateIndicator()" onoffline="updateIndicator()"> <p>The network is: <span id="indicator">(state unknown)</span> </body> </html>