398 Part III ✦ Document Objects Reference The other image trick is to be sure to specify HEIGHT and WIDTH attributes for every image, scripted or otherwise. Navigator 2 requires these attributes (as does the HTML 4.0 specification), and document-rendering performance is improved on all platforms, because the values help the browser lay out elements even before their details are loaded. In addition to the document.write() example that follows (see Listings 18-16 through 18-18), you can find fuller implementations that use this method to assem- ble images and bar charts in many of the applications in Chapters 48 through 57. Because you can assemble any valid HTML as a string to be written to a window or frame, a customized, on-the-fly document can be as elaborate as the most complex HTML document that you can imagine. Example on the CD with Figure 18-2 and Listings 18-16, 18-17, and 18-18 Related Items: document.open(); document.close(); document.clear() methods. Event handlers onSelectionChange NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The onSelectionChange event can be triggered by numerous user actions, although all of those actions occur on elements that are under the influence of the IE5.5/Windows edit mode. Related Items: onControlSelect event handler. onStop NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The onStop event fires in IE5 when the user clicks the browser’s Stop button. Use this event handler to stop potentially runaway script execution on a page, because the Stop button does not otherwise control scripts after a page has loaded. If you are having a problem with a runaway repeat loop during development, you can temporarily use this event handler to let you stop the script for debugging. On the CD-ROM document.onStop 399 Chapter 18 ✦ The Document and Body Objects Example on the CD with Listing 18-19 Related Items: Repeat loops (Chapter 39). BODY Element Object For HTML element properties, methods, and event handlers, see Chapter 15. Properties Methods Event Handlers alink createControlRange() onAfterPrint background createTextRange() onBeforePrint bgColor doScroll() onScroll bgProperties bottomMargin leftMargin link noWrap rightMargin scroll scrollLeft scrollTop text topMargin vLink Syntax Accessing BODY element object properties or methods: [window.] document.body.property | method([parameters]) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ On the CD-ROM document.body 400 Part III ✦ Document Objects Reference About this object In object models that reveal HTML element objects, the BODY element object is the primary container of the content that visitors see on the page. The BODY con- tains all rendered HTML. This special place in the node hierarchy gives the BODY object some special powers, especially in the IE object model. As if to signify the special relationship, both the IE and W3C object models pro- vide the same shortcut reference to the BODY element: document.body. As a first- class HTML element object (as evidenced by the long lists of properties, methods, and event handlers covered in Chapter 15), you are also free to use other syntaxes to reach the BODY element. You are certainly familiar with several BODY element attributes that govern body-wide content appearance, such as link colors (in three states) and back- ground (color or image). But IE and NN (and the W3C so far) have some very differ- ent ideas about the BODY element’s role in scripting documents. Many methods and properties that NN considers to be the domain of the window (for example, scrolling, inside window dimensions, and so forth), IE puts into the hands of the BODY element object. Therefore, while NN scrolls the window (and whatever it may contain), IE scrolls the body (inside whatever window it lives). And because the BODY element fills the entire viewable area of a browser window or frame, that viewable rectangle is determined in IE by the body’s scrollHeight and scrollWidth properties, whereas NN4+ features window.innerHeight and window.innerWidth properties. This distinction is important to point out because when you are scripting window- or document-wide appearance factors, you may have to look for properties and methods for the window or BODY element object, depending on your target browser(s). Use caution when referencing the document.body object while the page is load- ing. The object may not officially exist until the page has completely loaded. If you need to set some initial properties via scripting, do so in response to the onLoad event handler located in the <BODY> tag. Attempts at setting BODY element object properties in immediate scripts inside the HEAD element may result in error messages about the object not being found. Properties aLink bgColor link text vLink Value: Hexadecimal triplet or color name string Read/Write Note document.body.aLink 401 Chapter 18 ✦ The Document and Body Objects NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The aLink, link, and vLink properties are the new versions of the document properties alinkColor, linkColor, and vlinkColor. The bgColor is the same as the old document.bgColor property, while the text property is the new version of the document.fgColor property. These new properties are the scripted equiva- lents of the HTML attributes for the BODY element — the property names more closely align themselves with the HTML attributes than the old property names. Link colors that are set via pseudo-class selectors in style sheets (as STYLE attributes of the BODY element) must be accessed via the style property for the BODY object. Over time, these properties will likely fall into disuse as style sheets become more common. Example on the CD Related Items: document.alinkColor, document.bgColor, document.fgColor, document.linkColor, document.vlinkColor properties. background Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The background property lets you set or get the URL for the background image (if any) assigned to the BODY element. A BODY element’s background image over- lays the background color in case both attributes or properties are set. To remove an image from the document’s background, set the document.body.background property to an empty string. Example on the CD Related Items: body.bgColor, body.bgProperties properties. bgColor See aLink On the CD-ROM On the CD-ROM document.body.bgColor 402 Part III ✦ Document Objects Reference bgProperties Value: String constant Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The IE-specific bgProperties property is an alternative way of adjusting whether the background image should remain fixed when the user scrolls the docu- ment or if it should scroll with the document. Initial settings for this behavior should be done via the background-attachment CSS attribute and modified under script control by way of the BODY element’s style.backgroundAttachment property. No matter which way you reference this property, the only allowable values are string constants scroll (the default) or fixed. Example on the CD Related Items: body.background property. bottomMargin leftMargin rightMargin topMargin Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The four IE-specific margin properties are alternatives to setting the correspond- ing four margin style sheet attributes for the BODY element ( body.style.marginBottom, and so on). Style sheet margins represent blank space between the edge of an element’s content and its next outermost container. In the case of the BODY element, that container is an invisible document container. Of the four properties, only the one for the bottom margin may be confusing if the content does not fill the vertical space of a window or frame. The margin value is not automatically increased to accommodate the extra blank space. Different versions and operating system implementations of IE4+ offer a variety of default integer values for these properties. But be aware that their values are not necessarily returned by these properties unless they are explicitly set in the IE- proprietary BODY element attributes of the same name. Therefore, even though a default BODY has a visible margin, the property does not return that default value. On the CD-ROM document.body.bottomMargin 403 Chapter 18 ✦ The Document and Body Objects Example on the CD Related Items: style object. leftMargin See bottomMargin. link See aLink. noWrap Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The noWrap property lets you modify the BODY element behavior normally set via the NOWRAP attribute. Because the property name is a negative, the Boolean logic needed to control it can get confusing. The default behavior for a BODY element is for text to wrap within the width of the window or frame. This behavior occurs when the value of noWrap is its default value of false. By turning noWrap to true, a line of text continues to render past the right edge of the window or frame until the HTML contains a line break (or end of paragraph). If the text continues on past the right edge of the window, the win- dow (or frame) gains a horizontal scrollbar (of course, not if a frame is set to not scroll). By and large, users don’t like to scroll in any direction if they don’t have to. Unless you have a special need to keep single lines intact, let the default behavior rule the day. Example on the CD Related Items: None. rightMargin See bottomMargin. On the CD-ROM On the CD-ROM document.body.rightMargin 404 Part III ✦ Document Objects Reference scroll Value: Constant String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The IE-specific scroll property provides scripted access to the IE-specific SCROLL attribute of a BODY element. By default, an IE BODY element displays a ver- tical scrollbar even if the height of the content does not warrant it; a horizontal scrollbar appears only when the content is forced to be wider than the window or frame. You can make sure that both scrollbars are hidden by setting the SCROLL attribute to “no” or changing it via script. Possible values for this property are the constant strings yes and no. Other than frame attributes and NN4+ signed scripts, other browsers do not pro- vide facilities for turning off scrollbars under script control. You can generate a new window (via the window.open() method) and specify that its scrollbars be hidden. Example on the CD Related Items: window.scrollbars property; window.open() method. scrollLeft scrollTop Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ Even though the scrollLeft and scrollTop properties of the BODY object are the same as those for generic HTML element objects, they play an important roll in determining the position of positioned elements (described more fully in Chapter 31). Because the mouse event and element position properties tend to be relative to the visible content region of the browser window, you must take the scrolling val- ues of the document.body object into account when assigning an absolute posi- tion. Values for both of these properties are integers representing pixels. Example on the CD with Listing 18-20 Related Items: window.pageXOffset, window.pageYOffset properties. On the CD-ROM On the CD-ROM document.body.scrollLeft 405 Chapter 18 ✦ The Document and Body Objects text See aLink. topMargin See bottomMargin. vLink See aLink. Methods createControlRange() Returns: Array. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ This method is listed here for the sake of completeness. Microsoft has so far pro- vided few clues as to when or how to use a controlRange object, except that it has something to do with a document in edit mode. In regular document view mode, the createControlRange() method (not implemented in IE5/Mac) returns an empty array. createTextRange() Returns: TextRange object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The BODY element object is the most common object to use to generate a TextRange object in IE4+, especially when the text you are about to manipulate is part of the document’s body text. The initial TextRange object returned from the createTextRange() method (not implemented in IE5/Mac) encompasses the entire BODY element’s HTML and body text. Further action on the returned object is required to set the start and end point of the range. See Chapter 19’s discussion of the TextRange object for more details. Example on the CD Related Items: TextRange object (Chapter 19). On the CD-ROM document.body.createTextRange() 406 Part III ✦ Document Objects Reference doScroll([“scrollAction”]) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ Use the doScroll() method (not implemented in IE5/Mac) to simulate user action on the scrollbars inside a window or frame that holds the current document. This method comes in handy if you are creating your own scrollbars in place of the standard system scrollbars. Scrolling is instantaneous, however, rather than with animation even if the Display control panel is set for animated scrolling. The param- eter for this method is one of the string constant values shown in Table 18-6. In practice, occasionally the longer scroll action names more closely simulate an actual click on the scrollbar component, whereas the shortcut versions may scroll at a slightly different increment. Table 18-6 document.body.doScroll() Parameters Long Parameter Short Parameter Scroll Action Simulates scrollbarDown down Clicking the down arrow. scrollbarHThumb n/a Clicking the horizontal scrollbar thumb (no scrolling action). scrollbarLeft left Clicking the left arrow. scrollbarPageDown pageDown Clicking the page down area or pressing PgDn (default). scrollbarPageLeft pageLeft Clicking the page left area. scrollbarPageRight pageRight Clicking the page right area. scrollbarPageUp pageUp Clicking the page up area or pressing PgUp. scrollbarVThumb n/a Clicking the vertical scrollbar thumb (no scrolling action). Unlike scrolling to a specific pixel location (by setting the BODY element’s scrollTop and scrollLeft properties), the doScroll() method depends entirely on the spatial relationship between the body content and the window or frame size. Also, the doScroll() method triggers the onScoll event handler for the BODY ele- ment object. Be aware that scripted modifications to body content can alter these spatial rela- tionships. IE is prone to being sluggish in updating all of its internal dimensions after content has been altered. Should you attempt to invoke the doScroll() method after such a layout modification, the scroll may not be performed as document.body.doScroll() 407 Chapter 18 ✦ The Document and Body Objects expected. You may find the common trick of using setTimeout() to delay the invo- cation of the doScroll() method by a fraction of a second. Example on the CD Related Items: body.scroll, body.scrollTop, body.scrollLeft properties; window.scroll(), window.scrollBy(), window.scrollTo() methods. Event handlers onAfterPrint onBeforePrint See the onAfterPrint event handler for the window object, Chapter 16. onScroll NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The onScroll event handler fires for the BODY element object as the result of manual scrolling of the document (via scrollbars or navigation keyboard keys) and scripted scrolling via the doScroll() method, scrollIntoView() method, or adjusting the scrollTop and/or scrollLeft properties of the BODY element object. For manual scrolling and scrolling by doScroll(), the event seems to fire twice in succession. Moreover, the event.srcElement property is null, even when the BODY element is handling the onScroll event handler. Example on the CD with Listing 18-21 Related Items: body.scrollTop, body.scrollLeft properties; srcollIntoView(), body.doScroll() methods. ✦✦✦ On the CD-ROM On the CD-ROM document.body.onScroll . 398 Part III ✦ Document Objects Reference The other image trick is to be sure to specify HEIGHT and. method([parameters]) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ On the CD-ROM document.body 400 Part III ✦ Document Objects Reference About this object In object models that reveal HTML element. body.bgProperties properties. bgColor See aLink On the CD-ROM On the CD-ROM document.body.bgColor 402 Part III ✦ Document Objects Reference bgProperties Value: String constant Read/Write NN2 NN3 NN4