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.
Each unit of related similar-origin browsing contexts can have an entry script which is used to obtain, amongst other things, the script's base URL to resolve relative URLs used in scripts running in that unit of related similar-origin browsing contexts. Initially, there is no entry script. It is changed by the jump to a code entry-point algorithm.
Each unit of related similar-origin browsing
contexts also has a running mutation observers
flag, which must initially be false. It is used to prevent reentrant
invocation of the algorithm to invoke MutationObserver
objects. For the purposes of MutationObserver
objects, each unit of related similar-origin browsing
contexts is a distinct scripting environment.
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.