6.4 Creating a New Window

NN 2, IE 3

6.4.1 Problem

You want to open a separate subwindow based on scripted action in the main window.

6.4.2 Solution

To generate a new window, use the window.open( ) method, passing parameters for the (absolute or relative) URL of the page to occupy the new window, a text name for the window, and a comma-delimited string of parameters that specify the window's physical characteristics. For example:

var newWind = window.open("subDoc.html", "subWindow", 
              "status,menubar,height=400,width=300");

Preserve the value returned by the method (a reference to the subwindow object) in a global variable if you intend to reference the subwindow from the main window's scripts in other functions later on.

6.4.3 Discussion

If you are not loading an existing document (or one returned by a server process) into the new window, pass an empty string as the first parameter to open the window with a blank content region (so that you can later write dynamic content to it). The window name in the second parameter is the same kind of name that a hyperlink or form's target attribute points to. You should always provide a unique name, to keep multiple subwindows from accidentally colliding with each other.

Probably the trickiest part of creating a new window is defining the third parameter, a comma-delimited string of window properties. If you omit the third parameter altogether, the browser creates a window of the same dimensions and characteristics as the one that it would create if the user were to select New Window from the File menu (which is not necessarily the same size as the current window). But more typically, you want to control attributes such as size, location, and amount of window "chrome" displayed in the window. Table 6-1 lists all of the window attributes that you can specify as part of the third parameter to window.open( ), and the browser versions that support them.

Table 6-1. Window attributes for window.open( ) method

Attribute	NN	IE	Description
alwaysLowered	4	n/a	Always behind all other browser windows. Signed script required.
alwaysRaised	4	n/a	Always in front of all other browser windows. Signed script required.
channelMode	n/a	4	Show in theater mode with channel band.
copyhistory	2	n/a	Copy history listing from opening window to new window.
dependent	4	n/a	Subwindow closes if the window that opened it closes.
directories	2	3	Display directory buttons.
fullscreen	n/a	4	Display no titlebar or menus.
height	2	3	Window interior height in pixels.
hotkeys	4	n/a	Disable menu keyboard shortcuts (except Quit and Security Info).
innerHeight	4	n/a	Content region height. Signed script required for very small measures.
innerWidth	4	n/a	Content region width. Signed script required for very small measures.
left	6	4	Offset of window's left edge from left edge of screen.
location	2	3	Display Location (or Address) text field.
menubar	2	3	Display menu bar (a menu bar is always visible on Mac, letting users hide or show some chrome at will).
outerHeight	4	n/a	Total window height. Signed script required for very small measures.
outerWidth	4	n/a	Total window width. Signed script required for very small measures.
resizable	2	3	Allow window resizing (always allowed in NN 4 and earlier on the Mac).
screenX	4	n/a	Offset of window's left edge from left edge of screen. Signed script required to move window off screen.
screenY	4	n/a	Offset of window's top edge from top edge of screen. Signed script required to move window off screen.
scrollbars	2	3	Display scrollbars if document is too large for window.
status	2	3	Display status bar.
titlebar	4	n/a	Display titlebar. Set this value to no to hide the titlebar. Signed script required.
toolbar	2	3	Display toolbar (with Back, Forward, and other buttons).
top	6	4	Offset of window's top edge from top edge of screen.
width	2	3	Window interior width in pixels.
z-lock	4	n/a	New window is fixed below browser windows. Signed script required.

You can include attributes supported by some browser but not others in the attribute string. Browsers that don't know about a particular attribute simply ignore the attribute. Most of the attributes are Boolean types, indicating whether the feature should be turned on in the new window. For these attributes, you can either assign them values (yes or 1 to switch them on; no or 0 to switch them off), or simply include the attribute name by itself to signify the feature should be turned on. The following two examples display the menu bar and status bar and allow the window to be resized:

window.open("someDoc.html", "newWind", "menubar,status,resizable");
window.open("someDoc.html", "newWind", "menubar=1,status=1,resizable=1");

For Boolean attributes that control window chrome (such as location, resizable, and status), the features are turned on by default; other Booleans (such as alwaysRaised or fullscreen) are turned off by default. An important point to remember is that if you specify even just one attribute, all Boolean values are automatically switched off. Therefore, if you assign a height and width for the window, also turn on the window chrome features you wish to appear in the window. Also, for optimum backward-compatibility, assemble the string of attributes and their values without any spaces after the commas.

In addition to controlling the window chrome that appears in the window, you can set the location of the window on the screen. For example, you can come close to centering the window with a little bit of calculation prior to assigning a value to the left and top attributes (in browsers that support them). The hedge is that the dimensions you can specify for the window across browsers control only the content region of the window, and not any chrome. Thick toolbars of unknown height can throw off the calculations just a bit. Here is a function that opens a new window to a fixed interior size and centers that space on the screen:

var myWindow;
function openCenteredWindow(url) {
    var width = 400;
    var height = 300;
    var left = parseInt((screen.availWidth/2) - (width/2));
    var top = parseInt((screen.availHeight/2) - (height/2));
    var windowFeatures = "width=" + width + ",height=" + height + 
        ",status,resizable,left=" + left + ",top=" + top + 
        ",screenX=" + left + ",screenY=" + top;
    myWindow = window.open(url, "subWind", windowFeatures);
}

If it's possible for the user to open the window more than once, there are other factors to consider when creating the window. See Recipe 6.5 for the case in which the user has hidden the subwindow, and all your script needs to do is bring it in front of the main window.

The issue of whether you should open a subwindow automatically for a visitor is another one of those hotly contested user interface design topics. Unfortunately for scripters who may have valid reasons for opening a secondary window, the world of the "pop-up" advertisement has turned many users against any web site that starts opening multiple windows. A case that used to be made for using secondary windows as the targets for hyperlinks and form submissions was that the site developer didn't want to lose the visitor to another site in the course of web surfing, for fear that the visitor would not come back quickly. The result, however, was that users could find themselves with many windows open on their desktop, cluttering up their workspace.

Cases against opening secondary windows abound. For one, users who know about their browser's context menu (right-click in Windows and Unix, click-and-hold on the Mac) can choose to open a new window on any link they see. That puts the visitor in control of the window madness. Another case from the document markup purist point of view is that secondary windows (and even frames) have no place in electronic documents. It is no accident, for instance, that the target attribute is removed from the strict XHTML specification for hyperlinks and forms. And one final case, which may have the most impact on the development world, is a result of the backlash against pop-up ads. Many service providers use a variety of techniques to filter the window.open( ) method from pages they serve or pass through to their users. Most typically, the changes affect the onload and onunload event handlers of the <body> tag, but one never knows how strict the providers may become.

If you decide to use secondary windows, apply them judiciously and only when they add value to the visitor's experience or solve some other technical requirement of your application. The more you try to trap your visitors with tricks, the less likely it is that they'll come back or recommend the site to others.

6.4.4 See Also

Recipe 6.5 for controlling window layering; Recipe 6.6 and Recipe 6.7 for script communication between a main window and script-generated window; Recipe 6.9 to use a subwindow as a simulated cross-browser modal window.