Copyright ©2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines the Window
object, which provides the global namespace for web
scripting languages, access to other documents in a compound
document by reference, navigation to other locations, and
timers. The Window object is a
longstanding de facto standard for HTML user agents. However, it
should not be assumed based on this or the name "Window" that it
is limited to HTML or to visual user agents.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is produced by the Web API WG (part of the Rich Web Clients Activity). This document has no formal standing within the W3C. Please send comments to public-webapi@w3.org, the public email list for issues related to Web APIs.
The patent policy for this document is the 5 February 2004 W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Web API Working Group's patent disclosure page. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This section is not normative.
The Window Object 1.0 specification defines a
subset of the features of the Window
object, a widely implemented part of HTML User Agents,
with parts also found in non-HTML UAs that offer scripting and
DOM access. This specification is intended to be suitable for
all implementations that present any sort of DOM document
[DOM3Core] to the user.
This specification defines four features of the window object. It describes the use of the Window object as a browsing context: a container that displays a document, or a series of documents in sequence. It describes interfaces for navigation, the ability to go to a new document in the same browsing context. It describes interfaces for embedding, a feature also known as compound document by reference, where one document includes another separate document by external reference. And it specifies methods for using timers.
In addition, for some languages, such as ECMAScript
[ECMAScript], the Window interface is
implemented by the object that provides the global namespace for
script execution. The details of how this works for ECMAScript
are specified in ECMAScript
Language Binding Appendix.
This section is not normative.
This section is not normative.
This specification does not include the following features, which are also found on the Window object in some implementations. It is possible they will defined by other specifications or found in a future version of this specification.
This section is not normative.
This specification distinctively marks terms being defined, and references to definitions. Uses of terms are hyperlinks to the point of definition. An example of a definition:
An example of use:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].
Sometimes, for readability, conformance requirements are phrased as requirements on elements, attributes, methods, interfaces, properties or functions. In all cases these are conformance requirements on implementations.
This specification defines three classes of conformance:
A browsing context is a collection of one or more
views that present a Document or a
sequence of Documents to the user,
using one or more views. Only one
Document of this sequence is presented
at a time. A browsing context is said to
navigate when it changes from presenting one
document to another or one fragment within the same document to
another, for example by following a hyperlink. More is specified
about navigation behavior in the Navigation section.
The most familiar example of a browsing context is a web browser window. Browsers, or more generally visual user agents, typically present a document by rendering it to a display. However, even non-visual agents could have a browsing context. For example, a voice browser also presents documents to the user. This also establishes a browsing context.
For purposes of this specification, a Document is
an object that implements the DOM Document interface [DOM3Core].
A Document that is presented in a
browsing context MUST also implement the
DocumentWindow interface.
The main view of Document presented in
a browsing context is distinguished as the
default view. The default view is
typically the primary mode of presentation to the user, and in
interactive user agents, the primary means of interaction for
the user. The default view MUST be represented by an object
that implements the Window interface.
An object that implements the Window
interface is referred to as a Window
object. Note: despite the name, a
Window object does not necessarily
represent an onscreen overlapping window, even in visual user
agents.
A document presented in a browsing context may have elements that embed additional documents, forming a Compound Document by Reference. Each such element creates a nested browsing context. This mechanism is described in Embedding: Compound Documents by Reference.
Window Interface, Basic AttributesThe Window interface is fully
specified in IDL in the IDL Definitions
Appendix. To better organize this specification, it is
described in prose in multiple IDL fragments.
The Window interface inherits from
the AbstractView interface [DOM2Views].
In implementations that support Document Object Model CSS
from DOM Level 2 Views [DOM2Views], every
Window object MUST also implement the
ViewCSS interface.
In implementations that support DOM Events [DOM3EV], every
Window object MUST also implement the
EventTarget interface.
interface Window : views::AbstractView {
// ...
// self-references
readonly attribute Window window;
readonly attribute Window self;
// ...
};
The value of the document property inherited by
Window objects from the AbstractView interface
MUST be the Document for which the Window is a
view. As a result, in addition to the DocumentView interface,
it implements the Document and DocumentWindow
interfaces.
Window objects MUST have the following
attributes:
window attributewindow attribute MUST be the
same Window object that has the attribute: the attribute
is a self-reference.
self attributeself attribute MUST be the
same Window object that has the attribute: the attribute
is a self-reference. Consequently, the value of the self
attribute MUST be the same object as the window
attribute.
The Window object also has a special role as the
global scope for scripts in the document in languages such as
ECMAScript [ECMAScript]. Such use is specified by individual
language bindings. For ECMAScript it is specified in the ECMAScript Language Binding
Appendix.
DocumentWindow Interface, Basic AttributesTo better organize this specification, the
DocumentWindow interface is presented in mulitple
IDL fragments. The full normative IDL interface is presented in
the IDL Definitions Appendix. This fragment
defines only the most basic methods and attributes of the
Window interface.
interface DocumentWindow : views::DocumentView {
// ...
Window parentWindow;
// ...
};
The value of the defaultView attribute inherited
by objects that implement the DocumentWindow
interface from the AbstractView interface
MUST be the default view for the browsing context presenting
the Document, if any. If a document is
not being presented in a browsing context but nonetheless
implements the DocumentWindow interface, the value of the
defaultView attribute MUST be
null.
Window objects MUST have the following
attributes:
parentWindowparentWindow
attribute MUST be the default view for the
browsing context presenting the
Document, if any. If a document is
not being presented in a browsing context but
nonetheless implements the DocumentWindow interface, the
value of the defaultView attribute MUST be
null. Note: the defaultView and
parentWindow attributes refer to
the same object, but the former gives the
AbstractView interface while the latter gives
the Window interface.
In implementations that support DOM Events [DOM3EV],
Window objects provide the default
view for their contained Documents. In
such implementations, Window objects
are also an event target and participate in the DOM event flow
[DOM3EV].
When an event implementing the UIEvent interface
[DOM3EV] that originates in the default view of a
Document presented in a browsing
context, the value of the view attribute of
the event is be the Window object where the user
originated the event. This is required by DOM Level 2 Views
[DOM2Views].
As an extension to the DOM event flow [DOM3EV] for
conforming implementations, the
Window object is added to the DOM
event flow. For all events that target the
Document or any of its descendant DOM
nodes, except "load" events in the null namespace,
conforming implementations MUST do both of the following:
Window
object before dispatching to the
Document in the capture or target
phase.Window object after dispatching to the
Document in the bubble or target
phase.
However, conforming implementations MUST NOT
dispatch "load" events in the null namespace that target the
Document or any of its descendant DOM
nodes to the Window object, in either
the capture or bubble phases. The reason for this exception is
historical. This was not done in some implementations, leading
to content that depends on "load" events on various DOM elements
not triggering "load" event listeners on the
Window object. For compatibility, this
limitation is retained. Note: this does not affect "load" events that
dispatch directly on the Window object.
A browsing context has a session history: a sequence of absolute URI references [RFC2396]. It also has a current history position, an integer index into the session history that identifies the absolute URI reference for the document currently being presented. The absolute URI reference at the current history position is called the current location. The session history models the back/forward system of navigation familiar to browser users.
When a browsing context changes from one current location to another, it is said to perform a navigation to a target location, as specified by an absolute URI reference.
A navigation can be triggered in many different situations. For example, a user action, such as typing a URI in a location field or selecting a bookmark MAY have this effect. Markup languages and APIs also specify particular situations that trigger a navigation, such as activating a hyperlink or submitting a form. This specification defines some API operations that result in a navigation, using the algorithms described below.
When a browsing context performs a navigation that is not specifically intended to be a history navigation, reload, or replacement, it MUST remove any entries in the session history after the current history position, append the target location, and update the current history position to point to it. These values MUST be updated at the moment the browsing context starts presenting the new document. In particular, they MUST NOT be updated while still presenting the last document (if different from the new one), and MUST be updated when presenting even a partially loaded portion of the new document.
When a navigation is performed to a target location that differs only in fragment identifier [RFC2396] from the current location, the browsing context MUST continue to present the same document, but MAY adjust its presentation of the document based on the fragment identifier. Individual markup languages SHOULD define the proper way to interpret fragment identifiers when displaying a document using that language.
Conforming implementations MAY also offer user interfaces, APIs, markup language features or other mechanisms that result in a reload, replacement or history navigation, behaving as described below in the algorithms section or otherwise. Nothing in this section should be taken to require a linear user interface to session history, even though the processing model depends on a linear list. Conforming implementations may use a tree or any other method of organizing what is presented to the user.
In addition to the Window object
itself, navigation involves a number of other
objects. In addition to the Window
object and the document, there are two other
objects that participate in navigation, the
Location object and the
History object.
These objects are, like the Window
object, associated with a specific browsing
context.
All requirements for performing algorithms are "as if" requirements - all observable behavior must be as if the conforming implementation had performed the required steps, but this specification makes no requirements on how this effect is achieved.
The following algorithms are applied when parsing absolute URI references into components. Absolute URI references are parsed according to Uniform Resource Identifiers (URI): Generic Syntax [RFC2396], but the strings of interest when dealing with browsing context navigation are often somewhat different than the RFC standard pieces.
A conforming implementation MUST store several items of internal state for each browsing context:
The following algorithms are used to perform navigations. Many of the surprisingly detailed definitions are required for interoperability.
When a browsing context is REQUIRED to actuate the pending navigation, it MUST perform the following steps:
When a browsing context is REQUIRED to navigate at the next opportunity to an absolute URI reference new-uri, it MUST perform the following steps:
script element.When a browsing context is REQUIRED to replace the current location with a specified URI new-uri, it MUST perform the following steps:
script element.When a browsing context is REQUIRED to reload the curent location, it MUST perform the following steps:
script element.When browsing contexts it REQUIRED to change history position by delta steps, they MUST perform the following steps:
script element.Window Interface, Location Attributes
interface Window : views::AbstractView {
// ...
// assigning this has special behavior in ECMAScript, but it is otherwise
// read only. specifically, in ES a string URI can be assigned to location,
// having the same effect as location.assign(URI)
readonly attribute Location location;
readonly attribute History history;
// ...
};Window objects MUST have the following
attributes:
location attribute MUST be the
Location object associated with the
Window object's browsing
context.
history attribute MUST be the
History object associated with the
Window object's browsing
context.
DocumentWindow Interface, Location Attributes
interface DocumentWindow : views::DocumentView {
// ...
// same special JS assignment as window.location
readonly attribute Location location;
// ...
};DocumentWindow objects MUST implement the following
attributes:
location attribute MUST be
the Location object associated
with the browsing context presenting the
document. The value MUST be the same as the
Location object for all views of
the document.
Location InterfaceThe Location interface is defined by
the IDL interface below, which can also be found in the IDL Definitions Appendix.
An object that implements the Location
interface is called a Location
object.
Each Location object is associated
with a browsing context. Many
Location object methods and attributes
operate on the browsing context
interface Location {
attribute dom::DOMString href;
// pieces of the URI, per the generic URI syntax
attribute dom::DOMString hash;
attribute dom::DOMString host;
attribute dom::DOMString hostname;
attribute dom::DOMString pathname;
attribute dom::DOMString port;
attribute dom::DOMString protocol;
attribute dom::DOMString search;
void assign(in dom::DOMString uri);
void replace(in dom::DOMString uri);
void reload();
};Location objects MUST implement the following attributes:
hrefhref attribute MUST be the
browsing context's
current-location. When the href
attribute is set to a new value, the new value MUST not be
reflected immediately. Instead, the Location's
browsing context MUST navigate at the next
opportunity to the newly set value.
hashhash attribute MUST be the
result of
parseHash(current-location, false).
When this attribute is set to a new value
new-hash, user agents MUST NOT change the value
of the hash attribute but instead MUST perform
the following steps:
hosthost attribute
MUST be the result of
parseHost(current-location).
When this atribute is set to a new value
new-host, user agents MUST NOT change the value
of the host attribute but instead MUST perform
the following steps:
hostnamehostname attribute
MUST be the result of
parseHostname(current-location).
When this atribute is set to a new value
new-hostname, user agents MUST NOT change the
value of the hostname attribute
but instead MUST perform the following steps:
pathnamepathname attribute
MUST be the result of
parsePathname(current-location).
When this atribute is set to a new value
new-pathname, user agents MUST NOT change the value
of the pathname attribute but instead MUST perform
the following steps:
portport attribute
MUST be the result of
parsePort(current-location).
When this atribute is set to a new value
new-port, user agents MUST NOT change the
value of the port attribute
but instead MUST perform the following steps:
protocolprotocol attribute
MUST be the result of
parseProtocol(current-location).
When this atribute is set to a new value
new-protocol, user agents MUST NOT change the value
of the protocol attribute but instead MUST perform
the following steps:
searchsearch attribute
MUST be the result of
parseSearch(current-location).
When this atribute is set to a new value
new-search, user agents MUST NOT change the value
of the search attribute but instead MUST perform
the following steps:
Location objects MUST implement the following methods:
assign(uri)assign is called, the
Location object MUST
navigate at the next opportunity to
uri.replace(uri)replace is called, the
Location object MUST replace the
curent location with uri.reload()assign is called, the
Location object MUST reload the
curent location.History InterfaceThe History interface is defined by
the IDL interface below, which can also be found in the IDL Definitions Appendix.
An object that implements the History
interface is called a History
object.
Each History object is associated
with a browsing context. Many
History object methods and attributes
operate on the browsing context
interface History {
readonly attribute long length;
void go(in long delta);
void back();
void forward();
};History objects MUST implement the following attributes:
lengthlength
attribute MUST be the number of items in the browsing
context's session history.History objects MUST implement the following methods:
go(delta)go is called, the
browsing context MUST
change history position by
delta steps.back()back is called, the
browsing context MUST change history
position by -1 steps.back()forward is called, the
browsing context MUST change history
position by +1 steps.An element that refers to another document which is then embedded is called an embedding element. A document embedded in such an element is called a child document. Seen from a child document, the embedding element is part of a parent document. When a document has no embedding element that points to it the document is a root document. A document can be both a parent document and child document at the same time.
The value of the frameElement attribute of a
Window object MUST be the
embedding element, or
null if there is no such element. The value of the
parent attribute of a Window object MUST be the
parent document's
Window object or the document's Window object if
there is no parent document. The value of the top attribute of
a Window object MUST be the
root document's Window
object.
The name attribute of a Window object MUST be
the name assigned by the embedding
element, the empty string if there is no such element or a value set
by the script author. How this name is extracted from the embedding
element is language specific.
For example, if you have
<object data="file" id="test"/> in an XHTML
document the name DOM attribute within file will be
"test".
The value of the contentDocument attribute of an object that
implements the EmbeddingElement interface MUST be the
child document's
Document object or null if there is no such
object.
contentWindow attribute of an object that
implements the EmbeddingElement interface MUST be the child
document's Window object or null if there is no
such object.
Window Interface, Embedding Attributes
interface Window {
// name attribute of referencing frame/iframe/object, or name passed to
// window.open
attribute dom::DOMString name;
// global object of containing document
readonly attribute Window parent;
// global object of outermost containing document
readonly attribute Window top;
// referencing <html:frame>, <html:iframe>, <html:object>, <svg:foreignObject>,
// <svg:animation> or other embedding point, or null if none
readonly attribute dom::Element frameElement;
};Window object
that contains this object.EmbeddingElement Interface
// must be on an object that also implements dom::Element
interface EmbeddingElement {
readonly attribute dom::Document contentDocument;
readonly attribute Window contentWindow;
};Window Interface, Timer Attributes
interface Window {
// should timers allow more than long, maybe a floating point type?
// don't think anyone's timers have more precision
// one-shot timer
long setTimeout(in TimerListener listener, in long milliseconds);
void clearTimeout(in long timerID);
// repeating timer
long setInterval(in TimerListener listener, in long milliseconds);
void clearInterval(in long timerID);
};
// behavior is always special in ECMAScript, this is defined only for the benefit
// of other languages
interface TimerListener {
// what to put here?
};My current plan for the "security considerations" section is that it will contain the following:
I would rather not have normative requirements on when UAs must or must not throw exceptions or return null or whatever, since these would merely represent our best current understanding of how to implement the security policy.
It may be that some of this belongs in the main body of the spec instead of in Security Considerations, let's figure that out when the security part is actually written.
The WebAPI WG would like to thanks the following people for contributing to this specification:
Björn Höhrmann, Jim Ley, Cameron McCormack and Boris Zbarsky.
Special thanks to Anne van Kesteren for writing the Embedding section and many other additions and improvements.
Special thanks to Ian Hickson for making the first attempt to standardize the Window object in Web Apps 1.0, drafts of which heavily influenced this document. In particular, he coined the term "browsing context".