W3C

Window Object 1.0

W3C Working Draft 07 April 2006

This version:
http://www.w3.org/TR/2006/WD-Window-20060407/
Latest version:
http://www.w3.org/TR/Window
Editors:
Ian Davis (Talis Information Ltd.) <ian.davis@talis.com>
Maciej Stachowiak (Apple Computer, Inc.) <mjs@apple.com>

Abstract

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 long-standing 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.

Status of this Document

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 is the 05 April 2006 Working Draft of the Window Object, the first publication of this specification. This document is produced by the Web API WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. The authors of this document are the members of the W3C Web API Working Group.

Web content and browser developers are encouraged to review this draft. Please send comments to public-webapi@w3.org, the W3C's public email list for issues related to Web APIs. Archives of the list are available.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working 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.

Table of Contents

1. Introduction

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.

1.1. Examples of usage

This section is not normative.

ACTION-129: Write Window Object 1.0 "examples of usage" section.

1.2. Not in This Specification

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.

1.3. Definitions

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:

A flux capacitor is the part of user agents that has the most negative imaginary flux impedance.

An example of use:

When the engines are damaged, user agents typically calibrate the flux capacitor.

1.4. Conformance

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:

conforming implementation
A conforming implementation of the Window Object 1.0 specification is one that implements all the interfaces in this specification, and satisfies all other MUST-, REQUIRED- and SHALL-level criteria in all parts of this document other than language binding appendices.
conforming ECMAScript implementation
A conforming ECMAScript implementation of the Window Object 1.0 specification is a conforming implementation that maps all of the interfaces in this specification to ECMAScript [ECMAScript], and satisfies the additional requirements in the ECMAScript Language Binding Appendix.
conforming Java implementation
A conforming Java implementation of the Window Object 1.0 specification is a conforming implementation that maps all of the interfaces in this specification to Java [Java], and satisfies the additional requirements in the Java Language Binding Appendix.

2. Browsing Contexts

ACTION-130: Need to add definition of "document"

A browsing context is a place where a user agent presents 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, for example by following a hyperlink. More is specified about navigation behavior in the Navigation section.

A visual user agent typically presents 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.

An object that implements the Document interface [DOM3Core] and is presented in a browsing context MUST also implement the DocumentWindow interface.

Each view of a Document presented in a browsing context MUST be represented by an object that implements the Window interface. One of these is 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.

ISSUE-61: Should the Window spec drop any conformance requirements for AbstractViews besides the defaultView?

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.

When an event implementing the UIEvent interface [DOM3EV] is dispatched on any node in a Document presented in a browsing context, the value of the view attribute of the event MUST be the Window object where the user originated the event.

ISSUE-63: Should Window 1.0 drop the arguably redundant requirment on UIEvent.view?
ISSUE-64: Should the Window spec define Window's place in DOM event flow?

2.1. The Window Interface, Basic Attributes

The Window interface is fully specified in IDL in the IDL Definitions Appendix. To better organize this specification, it is described in prose in mulitple 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.


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.

2.1.1. Attributes

Window objects MUST have the following attributes:

window attribute
The value of the window attribute MUST be the same Window object that has the attribute: the attribute is a self-reference.
self attribute
The value of the self 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.
ACTION-131: Need to define "being the same object" in such a way that it is an equivalence relation. Then the second conformance clause for "self" can just be a note.

2.1.2. Use in scripting

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.

2.2. The DocumentWindow Interface, Basic Attributes

To 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.

ISSUE-65: Should we also specify the parentWindow property? It is effectively a synonym for defaultView but implemented by a different set of UAs.

interface DocumentWindow : views::DocumentView {
    // ...
};

The value of the defaultView attribute inherited by objects that implement the DocumentWindow interface inherit from the AbstractView interface MUST be the default view for the browsing context presenting the document, if any. In addition to the AbstractView interface, the default view MUST implement the Window interface. If a document is not being presented in a browsing context but nontheless implements the DocumentWindow interface, the value of the defaultView attribute MUST be null.

ISSUE-66: should Documents that aren't being presented be required to have a null defaultView?
Need prose description for this section, including definition of terms, etc.

3.1. The 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;

    // ...
};

3.1.1. Attributes

Window objects MUST have the following attributes:

location
The value of the location attribute MUST be the Location object that represents the window's current location.
Need to define the term "current location" in prose.

3.2. The DocumentWindow Interface, Location Attributes


interface DocumentWindow  : views::DocumentView {
    // ...
    // same special JS assignment as window.location
    readonly attribute Location location;
    // ...
};

3.2.1. Attributes

DocumentWindow objects MUST implement the following attributes:

location
The value of the location attribute MUST be a Location object that represents the DocumentWindow's current location. The value MUST be the same as the Location for all views of the document.
Need to define the term "current location" in prose.

3.3. The Location Interface


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 url);
    void replace(in dom::DOMString url);
    void reload();

    dom::DOMString toString();
};

3.3.1. Attributes

Location objects MUST implement the following attributes:

href
The value of the href attribute MUST be the absolute URI reference [RFC2396]
use newer URI RFC?
that is the Location's current location. When the href attribute is set, the Location's window MUST navigate to the newly set value.
Must define the term navigate
ISSUE-67: Should resolution of relative URI references sent to location be defined in JS bindings or generally?
hash
If the absolute URI reference[RFC2396] for the Location's current location has a fragment identifier[RFC2396], then the value of the hash attribute the value of this attribute MUST be the string concatenation of the hash mark(#) and the fragment identifier. Otherwise, the value of the hash attribute MUST be the empty string. When this atribute is set to a new value new-hash, user agents MUST perform the following steps:
  1. Give the hash attribute the value new-hash.
  2. Reconstruct the location URI
    Need to define the term "reconstruct the location URI".
  3. Navigate to the result of step 2.
The remainder of these attribute descriptions need to be rewritten to state conformance requirements. In the manner of the above.
host
This attribute represents the network host of the Location's URI. If the port attribute is not null then the host attribute's value is the concatenation of the hostname attribute, a colon (:) and the port attribute. If the port attribute is null then the host attribute's value is identical to the hostname attribute.
hostname
This attribute represents the name or IP address of the network location without any port number.
pathname
This attribute represents the path component of the Location's URI which consists of everything after the host and port up to and excluding the first question mark (?) or hash mark (#).
port
This attribute represents the port number of the network location.
protocol
This attribute represents the scheme of the URI including the trailing colon (:)
search
This attribute represents the query portion of a URI. It consists of everything after the pathname up to and excluding the first hash mark (#).

3.3.2. Methods

Location objects MUST implement the following methods:

These all need to be rewritten to state conformance requirements.
Need description for assign.
ISSUE-68: Need description for toString, if we specify that. It has the same value as href; not all implementations have this explicitly but toString is always available in ECMAScript, and probably this should be explicit for the sake of Java. Or we could skip it since it matches href, and define string conversion in the JS bindings.
replace(url)
This function replaces the current history entry with the url specified.
ISSUE-59: we haven't specified history - but we need to if we are to support this
reload()
This function forces the host application to reload the resource identified by the Location.
ISSUE-69: Netscape used to allow a bool argument to force an unconditional GET from the network

4. Embedding: Compound Documents by Reference

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 normative definitions of the various attributes should be moved to below the IDL to match other sections.

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.

For the ES bindings appendix: In ECMAScript these DOM attributes, even though readonly, to be set to different values. In such cases the attributes are simply the values set by the script author.
This does not deal with security. Security should probably be taken care of in a separate part of the specification. That there is no restriction by design, but by security environment.

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.

Need to mention that it can be set by Window.open() and the "target" attribute in some languages, basically anything that can open a new top-level browsing context.

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.

Need to discuss the possibility of embedding elements containing non-DOM content, like images or plugin content.
Likewise the 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.

4.1. The 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;
};
This needs fixing to clearly state the conformance requirements.
This also needs to be merged with the above I think [anne].
parent
An attribute containing a reference to Window object that contains this object.
top
An attribute containing a reference to the topmost Window object in the hierarchy that contains this object.
name
An attribute containing a unique name used to refer to this Window object.
Need to describe how this could come from a containing element.
frameElement
@@TODO

4.2. The EmbeddingElement Interface


// must be on an object that also implements dom::Element
interface EmbeddingElement {
    readonly attribute dom::Document contentDocument;
    readonly attribute Window contentWindow;
};
Need actual description.

5. Timers

Need to describe processing model for timers.

5.1. The 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);
};
setTimeout(function, milliseconds)
This method calls the function once after a specified number of milliseconds elapses, until canceled by a call to clearTimeout. The methods returns a timerID which may be used in a subsequent call to clearTimeout to cancel the interval.
setInterval(function, milliseconds)
This method calls the function every time a specified number of milliseconds elapses, until canceled by a call to clearInterval. The methods returns an intervalID which may be used in a subsequent call to clearInterval to cancel the interval.
clearTimeout(timerID)
Cancels a timeout that was set with the setTimeout method.
clearInterval(intervalID)
Cancels an interval that was set with the setTimeout method.

5.2. The TimerListener Interface


// behavior is always special in ECMAScript, this is defined only for the benefit
// of other languages
interface TimerListener {
    // what to put here?
};
ISSUE-70: what to do about timers?
Need to define this. In ES bindings, a function or string is the only thing allowed.

6. Security Considerations

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.

A. IDL Definitions

Need to fill in the full IDL here.

B. ECMAScript Language Binding

Need to define all the ECMAScript-specific issues, such as which properties are shadowable or replaceable, assigning to the location property, passing functions or strings as timers, etc.

C. Java Language Binding

Need to write this.

D. Acknowledgements

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 improvenets.

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".

E. References

Need to be able to include organization and date for references.
Need appropriate cites for DOM Core and OMG IDL.
Need titles and authors for DOM2Views
Need titles and authors for DOM3Core
Need titles and authors for ECMAScript
Need titles and authors for Java
DOM2Views
,
DOM3Core
,
DOM3EV
Document Object Model (DOM) Level 3 Events Specification, Philippe Le Hégaret (W3C), and Tom Pixley (Netscape Communications Corporation).
ECMAScript
,
Java
,
RFC2119
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner.
RFC2396
Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, and L. Masinter.