228 Part III ✦ Document Objects Reference opens a window. That window is a valid window object, even if the window is blank. Therefore, after a user loads your page into the browser, the window object part of that document is automatically created for your script to access as it pleases. One conceptual trap to avoid is believing that a window object’s event handler or custom property assignments outlive the document whose scripts make the assign- ments. Except for some obvious physical properties of a window, each new docu- ment that loads into the window starts with a clean slate of window properties and event handlers. Your script’s control over an existing (already open) window’s user interface elements varies widely with the browser and browser version for which your appli- cation is intended. Before the version 4 browsers, the only change you can make to an open window is to the status line at the bottom of the browser window. With IE4+ and NN4+, however, you can control such properties as the size, location, and (with signed scripts in Navigator) the presence of “chrome” elements (toolbars and scrollbars, for example) on the fly. Many of these properties can be changed beyond specific safe limits only if you cryptographically sign the scripts (see Chapter 46) and/or the user grants permission for your scripts to make those modifications. Window properties are far more flexible on all browsers when your scripts gener- ate a new window (with the window.open() method): You can influence the size, toolbar, or other view options of a window. Recent browser versions provide even more options for new windows, including the position of the window and whether the window should even display a title bar. Again, if an option can conceivably be used to deceive a user (for example, silently hiding one window that monitors activity in another window), signed scripts and/or user permission are necessary. The window object is also the level at which a script asks the browser to display any of three styles of dialog boxes (a plain alert dialog box, an OK/Cancel confirma- tion dialog box, or a prompt for user text entry). Although dialog boxes are extremely helpful for cobbling together debugging tools for your own use (Chapter 45), they can be very disruptive to visitors who navigate through Web sites. Because most JavaScript dialog boxes are modal (that is, you cannot do anything else in the browser — or anything at all on a Macintosh — until you dismiss the dialog box), use them sparingly, if at all. Remember that some users may create macros on their computers to visit sites unattended. Should such an automated access of your site encounter a modal dialog box, it is trapped on your page until a human intervenes. All dialog boxes generated by JavaScript identify themselves as being generated by JavaScript (less egregiously so in version 4 browsers and later). This is primarily a security feature to prevent deceitful scripts from creating system- or application- style dialog boxes that convince visitors to enter private information. It should also discourage dialog box usage in Web page design. And that’s good, because dialog boxes tend to annoy users. With the exception of the IE-specific modal and modeless dialog boxes (see the window.showModalDialog() and window.showModeless() methods), JavaScript dialog boxes are not particularly flexible in letting you fill them with text or graphic elements beyond the basics. In fact, you can’t even change the text of the dialog box buttons or add a button. With DHTML-capable browsers, you can use positioned DIV or IFRAME elements to simulate dialog box behavior in a cross-browser way. windowObject 228 Part III ✦ Document Objects Reference 229 Chapter 16 ✦ Window and Frame Objects Properties appCore Components controllers prompter sidebar Values: See Text Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ Navigator 6 provides scriptable access to numerous services that are part of the xpconnect package (“xp” stands for “cross-platform”). These services allow scripts to work with COM objects and the mozilla.org XUL (XML-based User Interface Language) facilities — lengthy subjects that extend well beyond the scope of this book. You can begin to explore this subject within the context of Navigator 6 and scripting at http://www.mozilla.org/scriptable/. clientInformation Value: navigator object Read-only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ In an effort to provide scriptable access to browser-level properties while avoid- ing reference to the Navigator browser brand, Microsoft provides the clientInformation property. Its value is identical to that of the navigator object — an object name that is also available in IE. Use the navigator object for cross-browser applications. (See Chapter 28.) Related Items: navigator object. clipboardData Value: Object Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ windowObject.clipboardData 230 Part III ✦ Document Objects Reference Use the clipboardData object (not implemented in IE5/Mac) to transfer data for such actions as cutting, copying, and pasting under script control. The object contains data of one or more data types associated with a transfer operation. Use this property only when editing processes via the Edit menu (or keyboard equiva- lents) or context menu controlled by script — typically in concert with edit-related event handlers. Working with the clipboardData object requires knowing about its three meth- ods shown in Table 16-1. Familiarity with the edit-related event handlers (“before” and “after” versions of cut, copy, and paste) is also helpful (see Chapter 15). Table 16-1 window.clipboardData Object Methods Method Returns Description clearData([format]) Nothing Removes data from the clipboard. If no format parameter is supplied, all data is cleared. Data formats can be one or more of the following strings: Text, URL, File, HTML, Image. getData(format) String Retrieves data of the specified format from the clipboard. The format is one of the following strings: Text, URL, File, HTML, Image. The clipboard is not emptied when you get the data, so that the data can be retrieved in several sequential operations. setData(format, data) Boolean Stores string data in the clipboard. The format is one of the following strings: Text, URL, File, HTML, Image. For non-text data formats, the data must be a string that specifies the path or URL to the content. Returns true if the transfer to the clipboard is successful. You cannot use the clipboardData object to transfer data between pages that originate from different domains or arrive via different protocols ( http versus https). Example on the CD-ROM Related Items: event.dataTransfer property; onBeforeCopy, onBeforeCut, onBeforePaste, onCopy, onCut, onPaste event handlers. On the CD-ROM windowObject.clipboardData 231 Chapter 16 ✦ Window and Frame Objects closed Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ When you create a subwindow with the window.open() method, you may need to access object properties from that subwindow, such as setting the value of a text field. Access to the subwindow is via the window object reference that is returned by the window.open() method, as in the following code fragment: var newWind = window.open(“someURL.html”,”subWind”) newWind.document.entryForm.ZIP.value = “00000” In this example, the newWind variable is not linked “live” to the window, but is only a reference to that window. If the user should close the window, the newWind variable still contains the reference to the now missing window. Thus, any script reference to an object in that missing window will likely cause a script error. What you need to know before accessing items in a subwindow is whether the window is still open. The closed property returns true if the window object has been closed either by script or by the user. Any time you have a script statement that can be triggered after the user has an opportunity to close the window, test for the closed property before executing that statement. As a workaround for Navigator 2, any property of a closed window reference returns a null value. Thus, you can test whether, say, the parent property of the new window is null: If so, the window has already closed. Internet Explorer 3, on the other hand, triggers a scripting error if you attempt to access a property of a closed window — you have no error-free way to detect whether a window is open or closed in Internet Explorer 3. Example (with Listing 16-4) on the CD-ROM Related Items: window.open(), window.close() methods. Components See appCore. controllers See appCore. On the CD-ROM windowObject.controllers 232 Part III ✦ Document Objects Reference crypto pkcs11 Values: Object References Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The crypto and pkcs11 properties return references to browser objects that are relevant to internal public-key cryptography mechanisms. These subjects are beyond the scope of this book, but you can read more about Netscape’s efforts on this front at http://www.mozilla.org/projects/security/. defaultStatus Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ After a document is loaded into a window or frame, the statusbar’s message field can display a string that is visible any time the mouse pointer is not atop an object that takes precedence over the statusbar (such as a link object or an image map). The window.defaultStatus property is normally an empty string, but you can set this property at any time. Any setting of this property will be temporarily overrid- den when a user moves the mouse pointer atop a link object (see window.status property for information about customizing this temporary statusbar message). Probably the most common time to set the window.defaultStatus property is when a document loads into a window. You can do this as an immediate script statement that executes from the Head or Body portion of the document or as part of a document’s onLoad event handler. The defaultStatus property does not work well in Navigator 2 or Internet Explorer 3, and experiences problems in Navigator 3, especially on the Macintosh (where the property doesn’t change even after loading a different document into the window). Many users simply don’t notice the statusbar change during Web surfing, so don’t put mission-critical information in the statusbar. Example (with Listing 16-5) on the CD-ROM Related Items: window.status property. On the CD-ROM Tip windowObject.defaultStatus 233 Chapter 16 ✦ Window and Frame Objects dialogArguments Value: Varies Read-only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The dialogArguments property is available only in a window that is generated by the IE-specific showModalDialog() or showModelessDialog() methods. Those methods allow a parameter to be passed to the dialog box window, and the dialogArguments property lets scripts inside the dialog box window’s scripts to access that parameter value. The value can be in the form of a string, number, or JavaScript array (convenient for passing multiple values). Example on the CD-ROM Related Items: window.showModalDialog(), window.showModelessDialog() methods. dialogHeight dialogWidth Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ Scripts in a document located inside an IE-specific modal or modeless dialog box (generated by showModalDialog() or showModelessDialog()) can read or modify the height and width of the dialog box window via the dialogHeight and dialogWidth properties. Scripts can access these properties from the main window only for modeless dialog boxes, which remain visible while the user can control the main window contents. Values for these properties are strings and include the unit of measure, the pixel ( px). Example on the CD-ROM Related Items: window.dialogLeft, window.dialogTop properties. On the CD-ROM On the CD-ROM windowObject.dialogHeight 234 Part III ✦ Document Objects Reference dialogLeft dialogTop Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ Scripts in a document located inside an IE-specific modal or modeless dialog box (generated by showModalDialog() or showModelessDialog()) can read or mod- ify the left and top coordinates of the dialog box window via the dialogLeft and dialogTop properties. Scripts can access these properties from the main window only for modeless dialog boxes, which remain visible while the user can control the main window contents. Values for these properties are strings and include the unit of measure, the pixel ( px). If you attempt to change these values so that any part of the dialog box win- dow would be outside the video monitor, the browser overrides the settings to keep the entire window visible. Example on the CD-ROM Related Items: window.dialogHeight, window.dialogTopWidth properties. directories locationbar menubar personalbar scrollbars statusbar toolbar Value: Object Read/Write (with signed scripts) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ Beyond the rectangle of the content region of a window (where your documents appear), the Netscape browser window displays an amalgam of bars and other fea- tures known collectively as chrome. All browsers can elect to remove these chrome On the CD-ROM windowObject.directories 235 Chapter 16 ✦ Window and Frame Objects items when creating a new window (as part of the third parameter of the window.open() method), but until signed scripts were available in Navigator 4, these items could not be turned on and off in the main browser window or any existing window. Navigator 4 promotes these elements to first-class objects contained by the window object. Navigator 6 adds one more feature, called the directories bar — a frame-like device that can be opened or hidden from the left edge of the browser window. At the same time, however, NN6 no longer permits hiding and showing the browser window’s scrollbars. Figure 16-4 points out where each of the six bars appears in a fully chromed Navigator 4 window. The only element that is not part of this scheme is the window’s title bar. You can create a new window without a title bar (with a signed script), but you cannot hide and show the title bar on an existing window. Figure 16-4: Window chrome items Chrome objects have but one property: visible. Reading this Boolean value (possible without signed scripts) lets you inspect the visitor’s browser window for the elements currently engaged. There is no intermediate setting or property for the expanded/collapsed state of the toolbar, locationbar, and personalbar in NN4. Changing the visibility of these items on the fly alters the relationship between the inner and outer dimensions of the browser window. If you must carefully size a window to display content, you should adjust the chrome elements before sizing the window. Before you start changing chrome visibility before the eyes of your page visitors, weigh the decision carefully. Experienced users have fine-tuned the look of their browser windows to just the way they like them. If you mess with that Menubar Personalbar StatusbarLocationbarToolbar Scrollbar windowObject.directories 236 Part III ✦ Document Objects Reference look, you may anger your visitors. Fortunately, changes you make to a chrome ele- ment’s visibility are not stored to the user’s preferences. However, the changes you make survive an unloading of the page. If you change the settings, be sure you first save the initial settings and restore them with an onUnload event handler. The Macintosh menu bar is not part of the browser’s window chrome. Therefore, its visibility cannot be adjusted from a script. Example (with Listing 16-6) on the CD-ROM Related Items: window.open() method. document Value: Object Read-only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ I list the document property here primarily for completeness. Each window object contains a single document object (although in Navigator 4, a window may also contain layers, each of which has a document object, as described in Chapter 31). The value of the document property is the document object, which is not a displayable value. Instead, you use the document property as you build references to properties and methods of the document and to other objects contained by the document, such as a form and its elements. To load a different document into a win- dow, use the location object (see Chapter 17). The document object is described in detail in Chapter 18. Related Items: document object. event Value: Object Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ Only IE4+ treats the event object as a property of the window object. Navigator 4+ and the W3C DOM pass an instance of the Event object as an argument to event handler functions. The connection with the window object in IE is relatively incon- sequential, because all action involving the event object occurs in event handler functions. The only difference is that the object can be treated as a more global On the CD-ROM Tip windowObject.event 237 Chapter 16 ✦ Window and Frame Objects object when one event handler function invokes another. Instead of having to pass the event object parameter to the next function, IE functions can access the event object directly (with or without the window. prefix in the reference). For complete details about the event object in all browsers, see Chapter 29. Related Items: event object. external Value: Object Read-only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The external property (not implemented in IE5/Mac) is useful only when the browser window is a component in another application. The property provides a gateway between the current browser window and the application that acts as a host to the browser window component. With IE4+ acting as a component to the host operating system, the external property can be used to access several methods that influence behaviors outside of the browser. Perhaps the three most useful methods to regular Web page scripters are AddDesktopComponent(), AddFavorite(), and NavigateAndFind(). The first two methods display the same kind of alert dialog box that users get after making these choices from the browser or desktop menus, so that you won’t be able to sneak your Web site onto desktops or Favorites listings without the visitor’s approval. Table 16-2 describes the parameters for these three methods. Table 16-2 Popular window.external Object Methods Method Description AddDesktopComponent(“URL”, Adds a Web site or image to the Active Desktop “type”[, left, top, (if turned on in the user’s copy of Windows). The width, height]) type parameter value is either website or image. Dimensional parameters (optional) are all integer values. AddFavorite(“URL”[, “title”]) Adds the specified URL to the user’s Favorites list. The optional title string parameter is how the URL should be listed in the menu (if missing, the URL appears in the list). NavigateAndFind(“URL”, “findString”, “target”) Navigates to the URL in the first parameter and opens the page in the target frame (an empty string opens in the current frame). The findString is text to be searched for on that page and highlighted when the page loads. windowObject.external . on your page until a human intervenes. All dialog boxes generated by JavaScript identify themselves as being generated by JavaScript (less egregiously so in version 4 browsers and later). This. dialog boxes (see the window.showModalDialog() and window.showModeless() methods), JavaScript dialog boxes are not particularly flexible in letting you fill them with text or graphic elements beyond. (Chapter 45), they can be very disruptive to visitors who navigate through Web sites. Because most JavaScript dialog boxes are modal (that is, you cannot do anything else in the browser — or anything