268 Part III ✦ Document Objects Reference that you can control for a newly created window in all browsers. Except where noted, all Boolean values default to yes if you do not specify the third parameter. Table 16-3 window.open() Method Attributes Controllable via Script Attribute Browsers Description alwaysLowered 3 NN4+ (Boolean) Always behind other browser windows alwaysRaised 3 NN4+ (Boolean) Always in front of other browser windows channelmode IE4+ (Boolean) Theater mode with channel band (default is no) copyhistory NN2+, IE3+ (Boolean) Duplicates Go menu history for new window dependent NN4+ (Boolean) Subwindow closes if the opener window closes directories NN2+, IE3+ (Boolean) “What’s New” and other buttons in the row fullscreen IE4+ (Boolean) No title bar or menus (default is no) height NN2+, IE3+ (Integer) Content region height in pixels hotkeys NN4+ (Boolean) If true, disables menu shortcuts (except Quit and Security Info) when menubar is turned off innerHeight 4 NN4+ (Integer) Content region height; same as old height property innerWidth 4 NN4+ (Integer) Content region width; same as old width property left IE4+ (Integer) Horizontal position of top-left corner on screen location NN2+, IE3+ (Boolean) Field displaying the current URL menubar 1 NN2+, IE3+ (Boolean) Menubar at top of window outerHeight 4 NN4+ (Integer) Visible window height outerWidth 4 NN4+ (Integer) Visible window width resizable 2 NN2+, IE3+ (Boolean) Interface elements that allow resizing by dragging screenX 4 NN4+ (Integer) Horizontal position of top-left corner on screen screenY 4 NN4+ (Integer) Vertical position of top-left corner on screen scrollbars NN2+, IE3+ (Boolean) Displays scrollbars if document is larger than window windowObject.open() 269 Chapter 16 ✦ Window and Frame Objects Attribute Browsers Description status NN2+, IE3+ (Boolean) Statusbar at bottom of window titlebar 3 NN4+ (Boolean) Title bar and all other border elements title IE5 (Boolean) Title bar toolbar NN2+, IE3+ (Boolean) “Back,” “Forward,” and other buttons in the row top IE4+ (Integer) Horizontal position of top-left corner on screen width NN2+, IE3+ (Integer) Content region width in pixels z-lock 3 NN4+ (Boolean) Window layer is fixed below browser windows 1 Not on Macintosh because the menubar is not in the browser window; when off in NN4/Mac, displays an abbreviated Mac menubar. 2 Macintosh windows are always resizable. 3 Requires a signed script. 4 Requires a signed script to size or position a window beyond safe threshold. Boolean values are handled a bit differently than you might expect. The value for true can be either yes, 1, or just the feature name by itself; for false, use a value of no or 0. If you omit any Boolean attributes, they are rendered as false. Therefore, if you want to create a new window that shows only the toolbar and statusbar and is resizable, the method looks like this: window.open(“newURL”,”NewWindow”, “toolbar,status,resizable”) A new window that does not specify the height and width is set to the default size of the browser window that the browser creates from a File menu’s New Web Browser command. In other words, a new window does not automatically inherit the size of the window making the window.open() method call. A new window created via a script is positioned somewhat arbitrarily, unless you use the window positioning attributes available in NN4+ and IE4+. Notice that the position attributes are different for each browser ( screenX and screenY for NN; left and top for IE). You can include both sets of attributes in a single parameter string because the browser ignores attributes it doesn’t recognize. Netscape-only signed scripts Many NN-specific attributes are deemed to be security risks and thus require signed scripts and the user’s permission before they are recognized. If the user fails to grant permission, the secure parameter is ignored. A couple of these attributes have different behaviors on different operating system platforms, due to the way the systems manage their application windows. For example, the alwaysLowered, alwaysRaised, and z-locked styles can exist in layers that range behind Navigator’s own windows in the Windows platform; on the Mac, however, such windows are confined to the levels occupied by Navigator. The difference is that Windows allows windows from multiple applications to interleave each other, while the Mac keeps each application’s windows in contiguous layers. windowObject.open() 270 Part III ✦ Document Objects Reference To apply signed scripts to opening a new window with the secure window fea- tures, you must enable UniversalBrowserWrite privileges as you do for other signed scripts (see Chapter 46). A code fragment that generates an alwaysRaised style window follows: <SCRIPT LANGUAGE=”JavaScript” ARCHIVE=”myJar.jar” ID=”1”> function newRaisedWindow() { netscape.security.PrivilegeManager.enablePrivilege(“UniversalBrowserWrite”) var newWindow = window.open(“”,””,”HEIGHT=100,WIDTH=300,alwaysRaised”) netscape.security.PrivilegeManager.disablePrivilege(“UniversalBrowserWrite”) var newContent = “<HTML><BODY><B> “On top of spaghetti!”</B>” newContent += “<FORM><CENTER><INPUT TYPE=’button’ VALUE=’OK’” newContent += “onClick=’self.close()’></CENTER></FORM></BODY></HTML>” newWindow.document.write(newContent) newWindow.document.close() } </SCRIPT> You can experiment with the look and behavior of new windows with any combi- nation of attributes with the help of the script in Listing 16-25. This page presents a table of all NN-specific new window Boolean attributes and creates a new 300×300 pixel window based on your choices. This page assumes that if you are using NN4, you have codebase principals turned on for signed scripts (see Chapter 46). Be careful with turning off the title bar and hotkeys. With the title bar off, the content appears to float in space, because absolutely no borders are displayed. With hotkeys still turned on, you can use Ctrl+W to close this borderless window (except on the Mac, for which the hotkeys are always disabled with the title bar off). This is how you can turn a computer into a kiosk by sizing a window to the screen’s dimensions and setting the window options to “titlebar=no,hotkeys=no, alwaysRaised=yes” . Listing 16-25: New Window Laboratory <HTML> <HEAD> <TITLE>window.open() Options</TITLE> <SCRIPT LANGUAGE=”JavaScript”> var isNav4 = (navigator.appName == “Netscape” && navigator.appVersion.charAt(0) >= 4) ? true : false function makeNewWind(form) { if (isNav4) { netscape.security.PrivilegeManager.enablePrivilege(“UniversalBrowserWrite”) } var attr = “HEIGHT=300,WIDTH=300” for (var i = 0; i < form.elements.length; i++) { if (form.elements[i].type == “checkbox”) { attr += “,” + form.elements[i].name + “=” attr += (form.elements[i].checked) ? “yes” : “no” } } var newWind = window.open(“bofright.htm”,”subwindow”,attr) if (isNav4) { windowObject.open() 271 Chapter 16 ✦ Window and Frame Objects netscape.security.PrivilegeManager.revertPrivilege(“UniversalBrowserWrite”) } } </SCRIPT> </HEAD> <BODY> <FORM> <B>Select new window options:</B> <TABLE BORDER=2> <TR> <TD COLSPAN=2 BGCOLOR=”yellow” ALIGN=”middle”>All Browsers Features:</TD> </TR> <TR> <TD><INPUT TYPE=”checkbox” NAME=”toolbar”>toolbar</TD> <TD><INPUT TYPE=”checkbox” NAME=”location”>location</TD> </TR> <TR> <TD><INPUT TYPE=”checkbox” NAME=”directories”>directories</TD> <TD><INPUT TYPE=”checkbox” NAME=”status”>status</TD> </TR> <TR> <TD><INPUT TYPE=”checkbox” NAME=”menubar”>menubar</TD> <TD><INPUT TYPE=”checkbox” NAME=”scrollbars”>scrollbars</TD> </TR> <TR> <TD><INPUT TYPE=”checkbox” NAME=”resizable”>resizable</TD> <TD><INPUT TYPE=”checkbox” NAME=”copyhistory”>copyhistory</TD> </TR> <TR> <TD COLSPAN=2 BGCOLOR=”yellow” ALIGN=”middle”>Communicator Features:</TD> </TR> <TR> <TD><INPUT TYPE=”checkbox” NAME=”alwaysLowered”>alwaysLowered</TD> <TD><INPUT TYPE=”checkbox” NAME=”alwaysRaised”>alwaysRaised</TD> </TR> <TR> <TD><INPUT TYPE=”checkbox” NAME=”dependent”>dependent</TD> <TD><INPUT TYPE=”checkbox” NAME=”hotkeys” CHECKED>hotkeys</TD> </TR> <TR> <TD><INPUT TYPE=”checkbox” NAME=”titlebar” CHECKED>titlebar</TD> <TD><INPUT TYPE=”checkbox” NAME=”z-lock”>z-lock</TD> </TR> <TR> <TD COLSPAN=2 ALIGN=”middle”><INPUT TYPE=”button” NAME=”forAll” VALUE=”Make New Window” onClick=”makeNewWind(this.form)”></TD> </TR> </TABLE> <BR> </FORM> </BODY> </HTML> windowObject.open() 272 Part III ✦ Document Objects Reference Specifying a window name Getting back to the other parameters of window.open(), the second parameter is the name for the new window. Don’t confuse this parameter with the document’s title, which would normally be set by whatever HTML text determines the content of the window. A window name must be the same style of one-word identifier that you use for other object names and variables. This name is also an entirely different entity than the window object that the open() method returns. You don’t use the name in your scripts. At most, the name can be used for TARGET attributes of links and forms. Loading content into a new window A script generally populates a window with one of two kinds of information: ✦ An existing HTML document whose URL is known beforehand ✦ An HTML page created on the fly To create a new window that displays an existing HTML document, supply the URL as the first parameter of the window.open() method. If your page is having dif- ficulty loading a URL into a new page (except as noted in the sidebar “A Navigator 2 Bug Workaround”), try specifying the complete URL of the target document (instead of just the filename). Leaving the first parameter as an empty string forces the window to open with a blank document, ready to have HTML written to it by your script (or loaded sepa- rately by another statement that sets that window’s location to a specific URL). If you plan to write the content of the window on the fly, assemble your HTML con- tent as one long string value and then use the document.write() method to post that content to the new window. If you plan to append no further writing to the page, also include a document.close() method at the end to tell the browser that you’re finished with the layout (so that the Layout:Complete or Done message appears in the statusbar, if your new window has one). A call to the window.open() method returns a reference to the new window’s object if the window opens successfully. This value is vitally important if your script needs to address elements of that new window (such as when writing to its document). To allow other functions in your script to reference the subwindow, you should assign the result of a window.open() method to a global variable. Before writing to the new window the first time, test the variable to make sure that it is not a null value — the window may have failed to open because of low memory, for instance. If everything is okay, you can use that variable as the beginning of a reference to any property or object within the new window. For example: var newWindow function createNewWindow() { newWindow = window.open(“”,””) if (newWindow != null) { newWindow.document.write(“<HTML><HEAD><TITLE>Hi!</TITLE></HEAD>”) } } That global variable reference continues to be available for another function that perhaps closes the subwindow (via the close() method). windowObject.open() 273 Chapter 16 ✦ Window and Frame Objects When scripts in the subwindow need to communicate with objects and scripts in the originating window, you must make sure that the subwindow has an opener property if the level of JavaScript in the visitor’s browser doesn’t automatically supply one. See the discussion about the window.opener property earlier in this chapter. Invoking multiple window.open() methods with the same window name parameter (the second parameter) does not create additional copies of that window in Netscape browsers (although it does in Internet Explorer). JavaScript prevents you from creat- ing two windows with the same name. Also be aware that a window.open() method does not bring an existing window of that name to the front of the window layers: Use window.focus() for that. windowObject.open() A Navigator 2 Bug Workaround If you’re concerned about backward compatibility with Navigator 2, you should be aware of a bug in the Macintosh and UNIX flavors of the browser. In those versions, if you include a URL as a parameter to window.open(), Navigator opens the window but does not load the URL. A second call to the window.open() method is required. Moreover, the second parameter must be an empty string if you add any third-parameter settings. Here is a sam- ple listing you can adapt for your own usage: <HTML> <HEAD> <TITLE>New Window</TITLE> <SCRIPT LANGUAGE=”JavaScript”> // workaround for window.open() bug on X and Mac platforms function makeNewWindow() { var newWindow = window.open(“http://www.dannyg.com”,””,”status,height=200,width=300”) if (parseInt(navigator.appVersion) == 2 && navigator.appName == “Netscape”) { newWindow = window.open(“http://www.dannyg.com”,””,”status,height=200,width=300”) } } </SCRIPT> </HEAD> <BODY> <FORM> <INPUT TYPE=”button” NAME=”newOne” VALUE=”Create New Window” onClick=”makeNewWindow()”> </FORM> </BODY> </HTML> This workaround can also be used without penalty in Windows versions of Navigator. 274 Part III ✦ Document Objects Reference Internet Explorer idiosyncracies Creating subwindows in IE can be complicated at times by undesirable behavior by the browser. One of the most common problems occurs when you attempt to use document.write() to put content into a newly created window. IE, including some of the latest versions, fails to complete the window opening job before the script statement that uses document.write() executes. This causes a script error because the reference to the subwindow is not yet valid. To work around this, you should put the HTML assembly and document.write() statements in a separate function that gets invoked via a setTimeout() method after the window is created. You can see an example of this in Listing 16-26. Another problem that affects IE is the occasional security violation (“access denied”) warning when a script attempts to access a subwindow. This problem goes away when the page that includes the script for opening and accessing the subwin- dow is served from an http server, rather than accessed from a local hard disk. Finally, an all-too common bug in Windows 95/98 allows the Registry to become mildly corrupted in some key areas that IE needs for opening and referencing new windows. The most common symptom of the problem is a script error on the state- ment that invokes window.open(), but other indications include error messages that the document.write() method is not supported in the subwindow or that the “RPC server” is not available. The problem cannot be fixed by JavaScript but requires human intervention on the affected PC. Here are the steps to repair the problem: 1. Click Start and then click Run. 2. In the Open box, type the following line: regsvr32 actxprxy.dll 3. Click OK and then click OK again after you receive the following message: DllRegisterServer in actxprxy.dll succeeded. 4. Click Start and then click Run. 5. In the Open box, type the following line: regsvr32 shdocvw.dll 6. Click OK and then click OK again after you receive the following message: DllRegisterServer in shdocvw.dll succeeded. 7. Shut down and restart your computer. The corruption is reported to be caused by application installers and unin- stallers that don’t clean up after themselves the way they should. The fact that this problem is rather common in IE4 under both Windows 95 and 98 might make you gun-shy about utilizing multiple windows in your application. Example (with Listing 16-26) on the CD-ROM Related Items: window.close(), window.blur(), window.focus() methods; window.closed property. On the CD-ROM windowObject.open() 275 Chapter 16 ✦ Window and Frame Objects print() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ The print() method provides a scripted way of sending the window or a frame from a frameset to the printer. In all cases, the Print dialog box appears for the user to make the typical printer choices when printing manually. This prevents a rogue print() command from tying up a printer without the user’s permission. The precise behavior of the print() method varies a bit with the different ways NN and IE (not to mention operating systems) handle printing. In NN4+ (except for the Windows OS), you can print all frames of a frameset in one print() command when it is invoked for the framesetting (parent) document. NN4 for Windows, how- ever, does not print the entire frameset at once. You can write a script that iterates through all frames and prints them with delays to let the content be sent to the print spooler: function printFrames(n) { parent.frames[n++].print() if (n < parent.frames.length) { setTimeout(“printFrames(“ + n + “)”,5000) } } Invoke this function as printFrames(0), and the function does the rest. In IE5, the print dialog box gives the user the choice of printing just one frame or all of the frames. Make sure that the print() method is invoked for the desired frame when you want only that frame to print. The browser defaults to printing just that frame. IE5 introduces some print-specific event handlers that are triggered by scripted printing as well as manual printing. The events begin to fire after the user has accepted the Print dialog box. An onBeforePrint event handler can be used to show content that might be hidden from view but should appear in the printout. After the content has been sent to the print spooler, the onAfterPrint event can restore the page. Example (with Listings 16-27 and 16-28) on the CD-ROM NN4 printing anomalies The Windows and Unix versions of NN4 handle printing in a way that can cause the page to not print what the user sees because before the page prints, it is loaded into a hidden window. Any immediate scripts in the page run again, but any user- induced, scripted content modifications will most likely not be a part of the page. On the CD-ROM windowObject.print() 276 Part III ✦ Document Objects Reference While there is no known workaround for resurrecting modified content, your script can at least know if the page is being loaded into one of these hidden win- dows: The NN-specific window.outerHeight and window.outerWidth properties are zero. If you don’t want an immediate script statement to run before being printed, use an if construction to let the nested statement(s) run only if either of those dimension properties is greater than zero. Printing in IE4 While the window.print() method is not available in IE4, it is possible to script printing in the Win32 OS platforms via the built-in browser object. To use this ActiveX object, you must first include the following HTML somewhere in your document (at the end of the BODY is fine): <OBJECT ID=”IEControl” WIDTH=0 HEIGHT=0 CLASSID=”clsid:8856F961-340A-11D0-A96B-00C04FD705A2”> </OBJECT> The long CLASSID attribute must be copied exactly. This HTML adds an object to the document object model that can be scripted. The object has several commands available, one of which provides printing services. The commands are numbered, and the one for printing is the following: IEControl.ExecWB(6, 1) If the user cancels the Print dialog box, a script error may appear, so be sure to trap for errors (see the window.onerror property earlier in this chapter). If you change the second parameter to 2, the Print dialog box does not appear, but that isn’t a very user-friendly way to treat printing. Related Items: window.back(), window.forward(), window.home(), window.find() methods. prompt(“message”, “defaultReply”) Returns: String of text entered by user or null. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ The third kind of dialog box that JavaScript can display includes a message from the script author, a field for user entry, and two buttons (OK and Cancel, or Yes and No on Mac versions of Navigator 2 and 3). The script writer can supply a prewritten answer so that a user confronted with a prompt dialog box can click OK (or press Enter) to accept that answer without further typing. Supplying both parameters to the window.prompt() method is important. Even if you don’t want to supply a default answer, enter an empty string as the second parameter: prompt(“What is your postal code?”,””) If you omit the second parameter, JavaScript inserts the string undefined into the dialog box’s field. This string is disconcerting to most Web page visitors. windowObject.prompt() 277 Chapter 16 ✦ Window and Frame Objects The value returned by this method is a string in the dialog box’s field when the user clicks the OK button. If you’re asking the user to enter a number, remember that the value returned by this method is a string. You may need to perform data- type conversion with the parseInt() or parseFloat() functions (see Chapter 42) to use the returned values in math calculations. When the user clicks the prompt dialog box’s OK button without entering any text into a blank field, the returned value is an empty string ( “”). Clicking on the Cancel button, however, makes the method return a null value. Therefore, the scripter must test for the type of returned value to make sure that the user entered some data that can be processed later in the script, as in var entry = prompt(“Enter a number between 1 and 10:”,””) if (entry != null) { //statements to execute with the value } This script excerpt assigns the results of the prompt dialog box to a variable and executes the nested statements if the returned value of the dialog box is not null (if the user clicked the OK button). The rest of the statements then include data validation to make sure that the entry is a number within the desired range (see Chapter 43). It may be tempting to use the prompt dialog box as a handy user input device. But, as with the other JavaScript dialog boxes, the modality of the prompt dialog box is disruptive to the user’s flow through a document and can also trap auto- mated macros that some users activate to capture Web sites. In forms, HTML fields are better user interface elements for attracting user text entry. Perhaps the safest way to use a prompt dialog box is to have it appear when a user clicks a button ele- ment on a page — and then only if the information you require of the user can be provided in a single prompt dialog box. Presenting a sequence of prompt dialog boxes is downright annoying to users. Example (with Figure 16-13 and Listing 16-29) on the CD-ROM Related Items: window.alert(), window.confirm() method. releaseEvents(eventTypeList) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ If your scripts have enabled NN4-specific event capture for the window object (or document or layer, for that matter), you can turn off that capture with the releaseEvents() method. This method does not inhibit events from reaching On the CD-ROM windowObject.releaseEvents() . user- induced, scripted content modifications will most likely not be a part of the page. On the CD-ROM windowObject.print() 276 Part III ✦ Document Objects Reference While there is no known workaround. number within the desired range (see Chapter 43) . It may be tempting to use the prompt dialog box as a handy user input device. But, as with the other JavaScript dialog boxes, the modality of the. 46). A code fragment that generates an alwaysRaised style window follows: <SCRIPT LANGUAGE= JavaScript ARCHIVE=”myJar.jar” ID=”1”> function newRaisedWindow() { netscape.security.PrivilegeManager.enablePrivilege(“UniversalBrowserWrite”) var