JavaScript Bible, Gold Edition part 63 potx

468
Part III ✦ Document Objects Reference
pasteHTML(“HTMLText”)
Returns: Nothing.
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
While the execCommand() method offers several commands that insert HTML
elements into a text range, it is probably more convenient to simply paste fully
formed HTML into the current text range (assuming you need to be working with a
text range instead of even more simply setting new values to an element object’s
outerHTML property). Provide the HTML to be inserted as a string parameter to the
pasteHTML() method.
Use the
pasteHTML() method with some forethought. Some HTML that you may
attempt to paste into a text range may force the method to wrap additional tags
around the content you provide to ensure the validity of the resulting HTML. For
example, if you were to replace a text range consisting of a portion of text of a P ele-
ment with, for instance an LI element, the
pasteHTML() method has no choice but
to divide the P element into two pieces, because a P element is not a valid container
for a solo LI element. This division can greatly disrupt your document object hierar-
chy, because the divided P element assumes the same ID for both pieces. Existing
references to that P element will break, because the reference now returns an array
of two like-named objects.
Example on the CD-ROM
Related Items: outerHTML property; insertAdjacenHTML() method.
queryCommandEnabled(“commandName”)
queryCommandIndeterm(“commandName”)
queryCommandState(“commandName”)
queryCommandSupported(“commandName”)
queryCommandText(“commandName”)

queryCommandValue(“commandName”)
Returns: See document.queryCommandEnabled() in Chapter 18.
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
See descriptions under document.queryCommandEnabled() in Chapter 18.
On the
CD-ROM
TextRange.queryCommandEnabled()
469
Chapter 19 ✦ Body Text Objects
select()
Returns: Nothing.
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
The select() method selects the text inside the boundaries of the current text
range. For some operations, such as prompted search and replace, it is helpful to
show the user the text of the current range to highlight what text is about to be
replaced. In some other operations, especially several commands invoked by
execCommand(), the operation works only on a text selection in the document.
Thus, you can use the
TextRange object facilities to set the boundaries, followed
by the
select() method to prepare the text for whatever command you like. Text
selected by the
select() method becomes a selection object (covered earlier in
this chapter).
Example on the CD-ROM
Related Items: selection object.
setEndPoint(“type”, otherRangeRef)
Returns: Nothing.

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
In contrast to the moveEnd() method, which adjusts the end point of the current
range with respect to characters, words, sentences, and the complete range, the
setEndPoint() method sets a boundary of the current range (not necessarily the
ending boundary) relative to a boundary of another text range whose reference is
passed as the second parameter. The first parameter is one of four types that con-
trol which boundary of the current range is to be adjusted and which boundary of
the other range is the reference point. Table 19-3 shows the four possible values
and their meanings.
On the
CD-ROM
TextRange.setEndPoint()
470
Part III ✦ Document Objects Reference
Table 19-3 setEndPoint() Method Types
Type Description
StartToEnd Moves the start point of the current range to the end of the other range
StartToStart Moves the start point of the current range to the start of the other range
EndToStart Moves the end point of the current range to the start of the other range
EndToEnd Moves the end point of the current range to the end of the other range
Note that the method moves only one boundary of the current range at a time. If
you want to make two ranges equal to each other, you have to invoke the method
twice, once with
StartToStart and once with EndToEnd. At that instant, the
isEqual() method applied to those two ranges returns true.
Setting a boundary point with the
setEndPoint() method can have unexpected
results when the revised text range straddles multiple elements. Don’t be surprised
to find that the new HTML text for the revised range does not include tags from the

outer element container.
Example on the CD-ROM
Related Items: TextRange.moveEnd(), TextRange.moveStart(), TextRange.
moveToElementText()
methods.
TextRectangle Object
Properties Methods Event Handlers
bottom
left
right
top
Syntax
Accessing TextRectangle object properties:
[window.]document.all.elemID.getBoundingClientRect().property
[window.]document.all.elemID.getClientRects()[i].property
On the
CD-ROM
TextRectangle
471
Chapter 19 ✦ Body Text Objects
About this object
The IE5+ TextRectangle object (not implemented in IE5/Mac) exposes to
scripts a concept that is described in the HTML 4.0 specification, whereby an ele-
ment’s rendered text occupies a rectangular space on the page just large enough to
contain the text. For a single word, the rectangle is as tall as the line height for the
font used to render the word and no wider than the space occupied by the text. But
for a sequence of words that wraps to multiple lines, the rectangle is as tall as the
line height times the number of lines and as wide as the distance between the left-
most and rightmost character edges, even if it means that the rectangle encloses
some other text that is not part of the element.

If you extract the
TextRectangle object for an element by way of, for example,
the
getBoundingClientRect() method, be aware that the object is but a snap-
shot of the rectangle when the method was invoked. Resizing the page may very
well alter dimensions of the actual rectangle enclosing the element’s text, but the
TextRectangle object copy that you made previously does not change its values
to reflect the element’s physical changes. After a window resize or modification of
body text, any dependent
TextRectangle objects should be recopied from the
element.
Properties
bottom
left
right
top
Values: Integers Read-only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓
The screen pixel coordinates of its four edges define every TextRectangle
object. These coordinates are relative to the window or frame displaying the page.
Therefore, if you intend to align a positioned element with an inline element’s
TextRectangle, your position assignments must take into account the scrolling of
the body.
To my eye, the left edge of a
TextRectangle does not always fully encompass
the left-most pixels of the rendered text. You may have to fudge a few pixels in the
measure when trying to align a real element with the
TextRectangle of another
element.

TextRectangle.bottom
472
Part III ✦ Document Objects Reference
Example (with Listing 19-12) on the CD-ROM
Related Items: getBoundingClientRect(), getClientRects() methods of
element objects (Chapter 15).
✦✦✦
On the
CD-ROM
TextRectangle.bottom
HTML Directive
Objects
T
hanks to the modern browser’s desire to expose all
HTML elements to the document object model, we can
now (in IE4+ and NN6) access a variety of objects that repre-
sent many HTML elements that are normally invisible to the
human viewer of a page. These elements are called directive
elements because they predominantly contain instructions for
the browser — instructions that direct the browser to locate
associated content on the page, link in external specifications,
treat content as executable script statements, and more.
As you browse through the objects of this chapter, you may
wonder why they have so many properties that normally indi-
cate that the elements occupy space on the rendered page.
After all, how can a META element have dimension or position
on the page when it has no renderable content? The reason is
that modern browsers internally employ some form of object-
oriented behavior that lets all HTML elements — rendered or
not — inherit the same set of properties, methods, and event

handlers that any generic element has (see Chapter 15). The
logical flaw is that unrendered elements can have properties
and methods that don’t genuinely apply to them. In such
cases, their property values may be zero, an empty string, or
an empty array. Yet the properties and methods exist in the
objects just the same. Therefore, despite the large number of
objects covered in this chapter, there are relatively few prop-
erties and methods that are not shared already with all HTML
elements (as covered in Chapter 15).
HTML Element Object
For HTML element properties, methods, and event handlers,
see Chapter 15.
Properties Methods Event Handlers
version
20
20
CHAPTER
✦✦✦✦
In This Chapter
Accessing non-
displayed element
objects
Linking operating-
system specific style
sheet definitions
HTML, HEAD, LINK,
TITLE, META, BASE,
and SCRIPT elements
✦✦✦✦
474

Part III ✦ Document Objects Reference
Syntax
Accessing HTML element object properties or methods:
(IE4+) [window.]document.all.elemID.property | method([parameters])
(IE5+/NN6) [window.]document.getElementById(“elemID”).property |
method([parameters])
(IE4+/NN6) [window.]document.body.parentElement.property | method([parameters])
About this object
The HTML element is the big wrapper around all other elements of the page. In
the object tree, the HTML element sits between the all-encompassing
document
object and the element’s most common children, the HEAD and BODY elements.
Other than one deprecated property (
version), the HTML element object offers
nothing of importance to the scripter — with one possible exception. When your
script needs to use methods on the child nodes of the HTML element, you must
invoke most of those methods from the point of view of the HTML element.
Therefore, you should know how to create a reference to the HTML element
object (shown in the preceding “Syntax” section) just in case you need it.
Property
version
Value: String Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓
The version property is an artifact of an “ancient” way an HTML document used
to specify the HTML version of its content. These days, the preferred way to declare
the HTML version for a document is through a Document Type Declaration (DTD)
statement that precedes the
<HTML> tag. An example of a modern DTD statement
that accommodates HTML 4 plus deprecated elements and attributes as well as

frameset support is
<!DOCTYPE HTML PUBLIC “-//W3C//DTD HTML 4.0 Frameset//EN”
“ />See for
several other possibilities. A DTD statement does not affect the
version property
of an HTML element object.
Related Items: None.
HEAD Element Object
For HTML element properties, methods, and event handlers, see Chapter 15.
HEAD
475
Chapter 20 ✦ HTML Directive Objects
Properties Methods Event Handlers
profile
Syntax
Accessing HEAD element object properties or methods:
(IE4+) [window.]document.all.elemID.property | method([parameters])
(IE5+/NN6) [window.]document.getElementById(“elemID”).property |
method([parameters])
About this object
The purpose of the HEAD element is primarily to act as a container for most of
the other HTML directive elements. Other than as a reference point to the child
elements nested within, the HEAD element object rarely comes into play when
scripting a document.
Properties
profile
Value: String Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓
The profile property is the script version of the optional PROFILE attribute

of a HEAD element. While the attribute and property are supported in NN6 (that is,
they exist), they are not used in practice yet. You can find details about the attribute
at
/>Related Items: META element object.
BASE Element Object
For HTML element properties, methods, and event handlers, see Chapter 15.
Properties Methods Event Handlers
href
target
BASE
476
Part III ✦ Document Objects Reference
Syntax
Accessing BASE element object properties or methods:
(IE4+) [window.]document.all.elemID.property | method([parameters])
(IE5+/NN6) [window.]document.getElementById(“elemID”).property |
method([parameters])
About this object
The BASE element enables the page author to specify a default server directory
and/or link target for the entire page. If you omit the BASE element from the HTML,
browsers use the current page’s path as the base URL and the current window or
frame as the default target. Occasionally, a page generated entirely by way of
document.write() has difficulty establishing the same BASE URL as the docu-
ment that generates the content, particularly if the primary page is written out
by a server script (in Perl or in another language). Including a
<BASE> tag in the
dynamically written new page solves the problem; the new page can fetch images
or other external elements via relative URLs within the page.
The two distinctive properties of the BASE element object are rarely scripted,
if ever.

Properties
href
Value: URL String Read/Write
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓✓
The href property is generally an absolute URL to the directory you wish to
declare as the default directory for the page. Even though browsers automatically
set the BASE HREF to the document’s own directory, this object and property do
not have any values unless you explicitly set them in a
<BASE> tag. In IE, changing
this property after a page loads causes the page to re-resolve all relative URLs on
the page to the new BASE HREF. Therefore, if images have relative URLs assigned to
their
src properties (either by way of the tag attribute or script), a change to the
BASE element’s
href property forces the browser to look for those same relative
URLs in the new directory. If the files aren’t there, then the images show up broken
on the page.
Example on the CD-ROM
On the
CD-ROM
BASE.href
477
Chapter 20 ✦ HTML Directive Objects
target
Value: String Read/Write
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓✓
The target property governs the default window or frame that is to receive any
content coming from a server in response to a click on a link or any other element

that has its own
TARGET attribute. Valid values include the name of any frame (as
assigned to the
NAME attribute of the <FRAME> tag) or window (as defined by the
second attribute of the
window.open() method). You can also assign standard
HTML targets (
_blank, _parent, _self, and _top) to this property as strings.
Example on the CD-ROM
BASEFONT Element Object
For HTML element properties, methods, and event handlers, see Chapter 15.
Properties Methods Event Handlers
color
face
size
Syntax
Accessing BASEFONT element object properties or methods:
(IE4+) [window.]document.all.elemID.property | method([parameters])
(IE5+/NN6) [window.]document.getElementById(“elemID”).property |
method([parameters])
About this object
The BASEFONT element enables authors to define a font face, size, and color
for an entire section of an HTML document — or the entire document. Although
page authors still frequently use the BASEFONT element, font control in modern
browsers should fall in the hands of style sheets. (The element is deprecated in
HTML 4.0.) The paradox of this is that the BASEFONT element is accessible as a
scriptable object only in browsers that support style sheets. Even so, I recommend
On the
CD-ROM
BASEFONT