JavaScript Bible, Gold Edition part 56 ppsx

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