298 Part III ✦ Document Objects Reference Note: Resizing the Navigator 4 browser window, especially if that window con- tains positioned elements (as DIV or LAYER elements) causes serious problems not only for the content, but also for scripts in the page. Content can get jumbled, and scripts may disappear. Your only hope is to use an onResize event handler to reload the page and get back to a known point. For some ideas on handling this problem, see the article at http://developer.netscape.com/viewsource/ goodman_resize/goodman_resize.html . One point not covered in the article is that the Windows version of NN4 issues a resize event when scroll bars appear in a window. This resize event can make any reload-on-resize strategy turn into an infinite loop. To guard against this, you have to inspect the window.innerWidth and window.innerHeight properties to see if the window has really changed (the property values don’t change when the scrollbars appear). Here is an example of script statements that go in the Head script of a page that has to worry about this problem in NN4: var Nav4 = (navigator.appName == “Netscape” && parseInt(navigator.appVersion) == 4) if (Nav4) { var loadWidth = window.innerWidth var loadHeight = window.innerHeight } function restore() { if (loadWidth != window.innerWidth || loadHeight != window.innerHeight) { history.go(0) } } if (Nav4) window.onresize = restore Related Items: event object (Chapter 29). onUnload NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓ ✓ ✓ ✓✓✓ An unload event reaches the current window just before a document is cleared from view. The most common ways windows are cleared are when new HTML docu- ments are loaded into them or when a script begins writing new HTML on the fly for the window or frame. Limit the extent of the onUnload event handler to quick operations that do not inhibit the transition from one document to another. Do not invoke any methods that display dialog boxes. You specify onUnload event handlers in the same places in an HTML document as the onLoad handlers: as a <BODY> tag attribute for a sin- gle-frame window or as a <FRAMESET> tag attribute for a multiframe window. Both onLoad and onUnload event handlers can appear in the same <BODY> or <FRAME- SET> tag without causing problems. The onUnload event handler merely stays windowObject.onUnload 299 Chapter 16 ✦ Window and Frame Objects safely tucked away in the browser’s memory, waiting for the unload event to arrive for processing as the document gets ready to clear the window. Let me pass along one caution about the onUnload event handler. Even though the event fires before the document goes away, don’t burden the event handler with time-consuming tasks, such as generating new objects or submitting a form. The document will probably go away before the function completes, leaving the func- tion looking for objects and values that no longer exist. The best defense is to keep your onUnload event handler processing to a minimum. Related Items: onLoad event handler. FRAME Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties Methods Event Handlers borderColor contentDocument Document frameBorder height longDesc marginHeight marginWidth noResize scrolling src width Syntax Accessing properties or methods of a FRAME element object from a FRAMESET: (IE4+) document.all.frameID. property | method([parameters]) (IE5+/NN6) document.getElementById(“frameID”). property | method([parameters]) Accessing properties of methods of a FRAME element from a frame document: (IE4+) parent.document.all.frameID. property | method([parameters]) (IE5+/NN6) parent.document.getElementById(“frameID”). property | method([parameters]) FRAME 300 Part III ✦ Document Objects Reference About this object As noted in the opening section of this chapter, a FRAME element object is dis- tinct from the frame object that acts as a window object in a document hierarchy. The FRAME element object is available to scripts only when all HTML elements are exposed in the object model, as in IE4+ and NN6. Because the FRAME element object is an HTML element, it shares the properties, methods, and event handlers of all HTML elements, as described in Chapter 15. By and large, you access the FRAME element object to set or modify an attribute value in the <FRAME> tag. If so, you simplify matters if you assign an identifier to the ID attribute of the tag. Your tag still needs a NAME attribute if your scripts refer to frames through the original object model (a parent.frameName reference). While there is no law against using the same identifier for both NAME and ID attributes, using different names to prevent potential conflict with references in browsers that recognize both attributes is best. To modify the dimensions of a frame, you must go the FRAMESET element object that defines the COLS and ROWS attributes for the frameset. These properties can be modified on the fly in IE4+ and NN6. Properties borderColor Value: Hexadecimal triplet or color name string Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ If a frame displays a border (as determined by the FRAMEBORDER attribute of the FRAME element or BORDER attribute of the FRAMESET element), it can have a color set separately from the rest of the frames. The initial color (if different from the rest of the frameset) is usually set by the BORDERCOLOR attribute of the <FRAME> tag. After that, scripts can modify settings as needed. Modifying a single frame’s border can be risky at times, depending on your color combinations. In practice, different browers appear to follow different rules when it comes to negotiating conflicts or defining just how far a single frame’s border extends into the border space. Moreover, IE5/Windows exhibits some strange col- oration behavior when applying a border color to a single frame. Color changes to individual frame borders do not always render. Verify your designs on as many browsers and operating system variations as you can to test your combinations. Example on the CD-ROM Related Items: FRAME.frameBorder, FRAMESET.frameBorder properties. On the CD-ROM FRAME.borderColor 301 Chapter 16 ✦ Window and Frame Objects contentDocument Value: document object reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The contentDocument property of a FRAME element object is nothing more than a reference to the document contained by that frame. This property bridges the gap between the FRAME element object and the frame object. Both of these objects contain the same document object, but from a scripting point of view, refer- ences most typically use the frame object to reach the document inside a frame, while the FRAME element is used to access properties equated with the FRAME tag’s attributes. But if your script finds that it has a reference to the FRAME element object, you can use the contentDocument property to get a valid reference to the document, and therefore any other content of the frame. Example on the CD-ROM Related Items: document object. Document Value: document object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ Because IE4 for Windows implements frames as what are known as ActiveX Web Browser objects, there are times when the properties of the Web Brower object can fill in when the regular object model has a gap. Such is the case when trying to gain access to the document object contained by a FRAME element object. Recall (from Chapter 15) that the document property of an HTML element refers to the document that contains the current object. In the case of a FRAME element, that would be the framesetting document. But to jump across the normal element node hierarchy from the FRAME element to the document it contains, you can use the Document (upper- case “D”) property.Even though IE5 no longer uses the Web Browser object for frames, the Document property continues to be available. Example on the CD-ROM Related Items: window.document property. On the CD-ROM On the CD-ROM FRAME.Document 302 Part III ✦ Document Objects Reference frameBorder Value: yes | no | 1 | 0 as strings Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The frameBorder property offers scripted access to a FRAME element object’s FRAMEBORDER attribute setting. IE4+ does not respond well to modifying this prop- erty after the page has loaded. Values for the frameBorder property are strings that substitute for Boolean values. Values yes or 1 mean that the border is (supposed to be) turned on; no or 0 turn off the border. Example on the CD-ROM Related Items: FRAMESET.frameBorder properties. height width Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ IE4+ lets you retrieve the height and width of a FRAME element object. These values are not necessarily the same as the document.body.clientHeight and document.body.clientWidth, because the frame dimensions include chrome associated with the frame, such as scrollbars. These values are read-only. If you need to modify the dimensions of a frame, do so via the FRAMESET element object’s rows and/or cols properties. Reading integer values for a frame’s height and width properties is much easier than trying to parse the rows and cols string properties. Example on the CD-ROM Related Items: FRAMESET object. On the CD-ROM On the CD-ROM FRAME.height 303 Chapter 16 ✦ Window and Frame Objects longDesc Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The longDesc property is the scripted equivalent of the LONGDESC attribute of the <FRAME> tag. This HTML 4.0 attribute is intended to provide browsers with a URL to a document that contains a long description of the element. Future browsers can use this feature to provide information about the frame for visually impaired site visitors. marginHeight marginWidth Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ Browsers tend to automatically insert content within a frame by adding a margin between the content and the edge of the frame. These values are represented by the marginHeight (top and bottom edges) and marginWidth (left and right edges) properties. Although the properties are not read-only, changing the values after the frameset has loaded does not alter the appearance of the document in the frame. If you need to alter the margin(s) of a document inside a frame, adjust the document. body.style margin properties. Also be aware that although the default values of these properties are empty (meaning when no MARGINHEIGHT or MARGINWIDTH attributes are set for the <FRAME> tag), margins are built into the page. The precise pixel count of those margins varies with operating system. Related Items: style object (Chapter 30). noResize Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ Web designers commonly fix their framesets so that users cannot resize the frames (by dragging any divider border between frames). The noResize property FRAME.noResize 304 Part III ✦ Document Objects Reference lets you read and adjust that behavior of a frame after the page has loaded. For example, during some part of the interaction with a user on a page, you may allow the user to modify the frame size manually while in a certain mode. Or you may grant the user one chance to resize the frame. When the onResize event handler fires, a script sets the noResize property of the FRAME element to false. If you turn off resizing for a frame, all edges of the frame become non-resizable, regardless of the noResize value setting of adjacent frames. Turning off resizability has no effect on the ability of scripts to alter the sizes of frames via the FRAMESET element object’s cols or rows properties. Example on the CD-ROM Related Items: FRAMESET.cols, FRAMESET.rows properties. scrolling Value: yes | no | 1 | 0 as strings Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The scrolling property lets scripts turn scrollbars on and off inside a single frame of a frameset. By default, scrolling is turned on unless overridden by the SCROLL attribute of the <FRAME> tag. Values for the scrolling property are strings that substitute for Boolean values. Values yes or 1 mean that scrollbars are visible (provided there is more content than can be viewed without scrolling); no or 0 hide scrollbars in the frame. IE4+ also recognizes (and sets as default) the auto value. This property is partially broken in IE5.5/Windows. While the object records changes to the property, the frame’s appearance does not change. NN6 has the same problem, plus some others, such as the property not returning a value unless the SCROLLING attribute is specified in the FRAME element’s tag. Example (with Listing 16-45) on the CD-ROM On the CD-ROM Note On the CD-ROM FRAME.scrolling 305 Chapter 16 ✦ Window and Frame Objects src Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The src property of a FRAME element object offers an additional way of navigat- ing to a different page within a frame (meaning other than assigning a new URL to the location.href property of the frame object). For backward compatibility with older browsers, however, continue using location.href for scripted navigation. Remember that the src property belongs to the FRAME element object, not the window object it represents. Therefore, references to the src property must be via the element’s ID and/or node hierarchy. Example on the CD-ROM Related Items: location.href property. FRAMESET Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties Methods Event Handlers border borderColor cols frameBorder frameSpacing rows Syntax Accessing properties or methods of a FRAMESET element object from a FRAMESET: (IE4+) document.all.framesetID. property | method([parameters]) (IE5+/NN6) document.getElementById(“framesetID”). property | method([parameters]) On the CD-ROM FRAMESET 306 Part III ✦ Document Objects Reference Accessing properties of methods of a FRAMESET element from a frame document: (IE4+) parent.document.all.framesetID. property | method([parameters]) (IE5+/NN6) parent.document.getElementById(“framesetID”). property | method([parameters]) About this object The FRAMESET element object is the script-accessible equivalent of the element generated via the <FRAMESET> tag. This element is different from the parent (win- dow-type) object from the original object model. A FRAMESET element object has properties and methods that impact the HTML element; in contrast, the window object referenced from documents inside frames via the parent or top window references contains a document and all the content that goes along with it. When framesets are nested in one another, a node parent–child relationship exists between containing and contained framesets. For example, consider the following skeletal nested frameset structure: <FRAMESET ID=”outerFrameset” COLS=”30%, 70%”> <FRAME ID=”frame1”> <FRAMESET ID=”innerFrameset” ROWS=”50%,50%”> <FRAME ID=”frame2”> <FRAME ID=”frame3”> </FRAMESET> </FRAMESET> When writing scripts for documents that go inside any of the frames of this structure, references to the framesetting window and frames are a flatter hierarchy than the HTML signifies. A script in any frame references the framesetting window via the parent reference; a script in any frame references another frame via the parent.frameName reference. In other words, the window objects of the frameset defined in a document are all siblings and share the same parent. Such is not the case when viewing the above structure from the perspective of W3C node terminology. Parent–child relationships are governed by the nesting of HTML elements, irrespective of whatever windows get generated by the browser. Therefore, frame frame2 has only one sibling, frame3. Both of those share one parent, innerFrameset. Both innerFrameset and frame1 are children of outerFrameset. If your script were sitting on a reference to frame2, and you wanted to change the cols property of outerFrameset, you would have to traverse two generations of nodes: frame2Ref.parentNode.parentNode.cols = “40%,60%” What might confuse matters ever more in practice is that a script belonging to one of the frames must use window object terminology to jump out of the current window object to the frameset that generated the frame window for the document. In other words, there is no immediate way to jump directly from a document to the FRAME element object that defines the frame in which the document resides. The docu- ment’s script accesses the node hierarchy of its frameset via the parent.document reference. But this reference is to the document object that contains the entire frame- set structure. Fortunately, the W3C DOM provides the getElementById() method to FRAMESET 307 Chapter 16 ✦ Window and Frame Objects extract a reference to any node nested within the document. Thus, a document inside one of the frames can access the FRAME element object just as if it were any element in a typical document (which it is): parent.document.getElementById(“frame2”) No reference to the containing FRAMESET element object is necessary. Or, to make that column width change from a script inside one of the frame windows, the statement would be: parent.document.getElementById(“outerFrame”).cols = “40%,60%” The inner frameset is equally accessible by the same syntax. Properties border Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The border property of a FRAMESET element object lets you read the thickness (in pixels) of the borders between frames of a frameset. If you do not specify a BOR- DER attribute in the frameset’s tag, the property is empty, rather than reflecting the actual border thickness applied by default. Example on the CD-ROM Related Items: FRAMESET.frameBorder property. borderColor Value: Hexadecimal triplet or color name string Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The borderColor property lets you read the value of the color assigned to the BORDERCOLOR attribute of the frameset’s tag. Although the property is read/write, changing the color by script does not alter the border colors rendered in the browser window. Attribute values set as color names are returned as hexadecimal triplets when you read the property value. On the CD-ROM FRAMESET.borderColor . property FRAME.noResize 304 Part III ✦ Document Objects Reference lets you read and adjust that behavior of a frame after the page has loaded. For example, during some part of the interaction with. method([parameters]) (IE5+/NN6) parent.document.getElementById(“frameID”). property | method([parameters]) FRAME 300 Part III ✦ Document Objects Reference About this object As noted in the opening section of this. against using the same identifier for both NAME and ID attributes, using different names to prevent potential conflict with references in browsers that recognize both attributes is best. To modify