Section 25.309. Window.open( ): open a new browser window or locate a named window

25.309. Window.open( ): open a new browser window or locate a named window

JavaScript 1.0:

25.309.1. Synopsis

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

25.309.1.1. Arguments

url

An optional string that specifies the URL to be displayed in the new window. If this argument is omitted, or if the empty string is specified, the new window does not display a document.

name

An optional 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, the open( ) method does not create a new window, but simply returns a reference to the named window. In this case, the features argument is ignored.

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 in the Window Features section. This argument is optional; if it is not specified, the new window has all the standard features.

replace

An optional boolean argument that specifies whether the URL loaded into the window 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, no new history entry is created. Note that this argument is intended for use when changing the contents of an existing named window.

25.309.1.2. Returns

A reference to a Window object, which may be a newly created or an already existing one, depending on the name argument.

25.309.2. Description

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

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

The name argument specifies a name for the new window. This name may contain only 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.

When you use Window.open( ) to load a new document into an existing named window, you can pass the replace argument to specify whether the new document has its own entry in the window's browsing history or whether it replaces the history entry of the current document. If replace is TRue, the new document replaces the old. If this argument is false or is not specified, the new document has its own entry in the Window's browsing history. This argument provides functionality much like that of the Location.replace( ) method.

Don't confuse Window.open( ) with Document.open( ); the two methods perform very different functions. For clarity in your code, you may want to use Window.open( ) instead of open( ). In event handlers defined as HTML attributes, open( ) is usually interpreted as Document.open( ), so in this case, you must use Window.open( ).

25.309.3. Window Features

The features argument is a comma-separated list of features that appears in the window. If this optional argument is empty or not specified, all features are present in the window. On the other hand, if features specifies any one feature, any features that do not appear in the list do 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, value is required and must specify a size in pixels.

Here are the commonly supported features and their meanings:

height

Specifies the height, in pixels, of the window's document display area.

left

The X coordinate, in pixels, of the window.

location

The input field for entering URLs directly into the browser.

menubar

The menu bar.

resizable

If this feature is not present or is set to no, the window does 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."

scrollbars

Enables horizontal and vertical scrollbars when they are necessary.

status

The status line.

toolbar

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

top

The Y coordinate, in pixels, of the window.

width

Specifies the width, in pixels, of the window's document display area.

25.309.4. See Also

Location.replace( ), Window.close( ), the closed and opener properties of Window