JavaScript: The Definitive Guide

Previous Chapter 21
JavaScript Reference
Next
 

Window.open() Method

Name

Window.open() Method---open a new browser window or locate a named window

Availability

Navigator 2.0, Internet Explorer 3.0; enhanced in Navigator 3.0

Synopsis

window.open(url, name, [features, [replace]])

Arguments

url

A string that specifies the URL to be displayed in the new window, or the empty string for a blank window. This argument is optional in Navigator 2.0 and 3.0, but is required in Internet Explorer 3.0.

name

A string of alphanumeric and underscore characters that specifies a name for the new window. This name can be used as the value of the TARGET attribute of <A> and <FORM> HTML tags. If this argument names a window that already exists, then the open() method will not create a new window, but will simply return a reference to the named window. In this case, the features argument is ignored. This argument is optional in Navigator 2.0 and 3.0, but is required in Internet Explorer 3.0.

features

A string that specifies which features of a standard browser window are to appear in the new window. The format of this string is specified below. This argument is optional; if it is not specified, then the new window will have all standard features.

replace

An optional Boolean argument that specifies whether the url that is loaded into the new page should create a new entry in the window's browsing history or replace the current entry in the browsing history. If this argument is true then no new history entry will be created. This argument is not supported by Navigator 2.0 or Internet Explorer 3.0, although those browsers will ignore it if it is specified. Also, notice that it doesn't make much sense to use this argument for newly created windows; it is intended for use when changing the contents of an existing window.

Returns

A reference to a Window object, which may be newly created, or to an already existing one.

Description

The open() method looks up an already existing window or opens a new browser window. If the name argument specifies the name of an existing window, then a reference to that window is returned. The returned window will display the URL specified by url, but the features argument will be ignored. This is the only way in JavaScript to obtain a reference to a window which is known only by name.

If the name argument is not specified, or if no window with that name already exists, the the open() method creates a new browser window. The created window displays the URL specified by url, has the name specified by name, and has the size and controls specified by features (the format of this argument is described below). If url is the empty string, then open() opens a blank window.

The name argument specifies a name for the new window. This name may only contain alphanumeric characters and the underscore character. It may be used as the value of the TARGET attribute of an <A> or <FORM> tag in HTML, to force documents to be displayed in the window.

With Navigator 3.0, when you use Window.open() to load a new document into a named window, you can also use the replace argument to specify whether the new document will have its own entry in the window's browsing history, or whether it will replace the history entry of the current document. If replace is true, the new document will replace the old. If this argument is false is or not specified, then the new document will have its own entry in the Window's browsing history. This argument provides functionality much like that of the Location.replace() method.

The features argument is a comma-separated list of features to appear in the window. If this optional argument is empty or not specified at all, then all features will be present in the window. On the other hand, if features specifies any one feature, then any features that do not appear in the list will not appear in the window. The string should not contain any spaces or other whitespace. Each element in the list has the format:

feature[=value]

For most features, the value is yes or no. For these features, the equals sign and the value may be omitted--if the feature appears, yes is assumed, and if it doesn't no is assumed. For the width and height features, the value is required and must specify a size in pixels.

The available features and their meanings are listed below. Note, however, that on X11 platforms in Navigator 2.0, only the width and height features work, and new browser windows are not created with any of the standard controls, even when the features argument is omitted entirely.

toolbar

The browser toolbar, with Back and Forward buttons, etc.

location

The input field for entering URLs directly into the browser.

directories

Directory buttons, such as "What's New" and "What's Cool" in Netscape.

status

The status line.

menubar

The menu bar.

scrollbars

This feature enables horizontal and vertical scrollbars when they are necessary.

resizable

If this feature is not present or is set to no, then the window will not have resize handles around its border. (Depending on the platform, the user may still have ways to resize the window.) Note that a common bug is to misspell this feature as "resizeable", with an extra "e".

width

This feature must be followed by a value that specifies the width of the window in pixels.

height

This feature must be followed by a value that specifies the height of the window in pixels.

Don't confuse this Window.open() method with the document.open() method; the two perform very different functions. For clarity in your code, you may want to use window.open() instead of open(). (Recall that the window property is simply a way to explicitly refer to the current window.)

Bugs

In Navigator 2.0, on X11 and Macintosh platforms, the url argument is ineffective. The solution is to call open() once to create the window, and then call it again to set the URL, or better, to use location property of the new (blank) window to load the desired URL.

On X11 platforms in Navigator 2.0, only the width and height features work, and new browser windows are not created with any of the standard controls, even when the features argument is omitted entirely.

See Also

"Location.replace()", "Window", "Window.close()"


Previous Home Next
Window.onunload() Book Index Window.opener

HTML: The Definitive Guide CGI Programming JavaScript: The Definitive Guide Programming Perl WebMaster in a Nutshell