JavaScript Bible, Gold Edition part 29 ppsx

128
Part III ✦ Document Objects Reference
The isDisabled property returns a Boolean value that indicates whether a par-
ticular element object is set to be disabled (see the preceding discussion of the
disabled property). This property is helpful; if a parent element’s disabled prop-
erty is set to
true, then a nested element’s disabled property likely is set to its
default value of
false. But because its parent is disabled, the isDisabled property
of the nested element returns
true. In other words, the isDisabled property
returns the actual disabled status of an element regardless of its
disabled property.
Example on the CD-ROM
Related Item: disabled property.
isMultiLine
Value: Boolean Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓
The isMultiLine property returns a Boolean value that reveals whether the ele-
ment object is capable of occupying or displaying more than one line of text.
Importantly, this value does not reveal whether the element actually occupies mul-
tiple lines; rather, it indicates the potential of doing so. For example, a text INPUT
element cannot wrap to multiple lines, so its
isMultiLine property is false.
However, a BUTTON element can display multiple lines of text for its label, so it
reports
true for the isMultiLine property.
Example on the CD-ROM
isTextEdit
Value: Boolean Read-Only

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓ ✓
The isTextEdit property reveals whether an object can have an IE/Windows
TextRange object created with its content. (See the TextRange object in Chapter
19.) You can create
TextRange objects only from a limited selection of objects in
IE4+ for Windows: BODY, BUTTON, certain form elements (text, password, hidden,
On the
CD-ROM
On the
CD-ROM
elementObject.isTextEdit
129
Chapter 15 ✦ Generic HTML Element Objects
button, reset, and submit types), and TEXTAREA. This property always returns
false in IE5/Mac.
Example on the CD-ROM
Related Items: createRange() method; TextRange object (Chapter 19).
lang
Value: ISO language code string Read/Write
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓✓
The lang property governs the written language system used to render an
element’s text content when overriding the default browser’s language system.
The default value for this property is an empty string unless the corresponding
LANG attribute is assigned a value in the element’s tag. Modifying the property
value by script control does not appear to have any effect in the current browser
implementations.
Example on the CD-ROM
language

Value: String Read/Write
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓ ✓
IE4+’s architecture allows for multiple scripting engines to work with the
browser. Two engines are included with the basic Windows version browser: JScript
(compatible with JavaScript) and Visual Basic Scripting Edition (VBScript). The
default scripting engine is JScript. But if you wish to use VBScript or some other
scripting language in statements that are embedded within event handler attributes
of a tag, you can specifically direct the browser to apply the desired scripting
engine to those script statements by way of the
LANGUAGE attribute of the tag. The
language property provides scripted access to that property. Unless you intend to
modify the event handler HTML code and replace it with a statement in VBScript
On the
CD-ROM
On the
CD-ROM
elementObject.language
130
Part III ✦ Document Objects Reference
(or any other non-JScript-compatible language installed with your browser), you do
not need to modify this property (or read it, for that matter).
Valid values include
JScript, javascript, vbscript, and vbs. Third-party
scripting engines have their own identifier for use with this value. Because the
LANGUAGE attribute is also used in the <SCRIPT> tag, Internet Explorer 5 observes
LANGUAGE=”XML” as well.
Example on the CD-ROM
Related Item: SCRIPT element object.
lastChild

(See firstchild)
length
Value: Integer Read-Only and Read/Write
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓ ✓ ✓ ✓ ✓ ✓✓ ✓
The length property returns the number of items in an array or collection of
objects. Its most common application is as a boundary condition in a
for loop.
While arrays and collections commonly use integer values as index values (always
starting with zero), the
length value is the actual number of items in the group.
Therefore, to iterate through all items of the group, the condition expression should
include a less-than (
<) symbol rather than a less-than-or-equal (<=) symbol, as in
the following:
for (var i = 0; i < someArray.length; i++) { }
For decrementing through an array (in other words, starting from the last item in
the array and working toward the first), the initial expression must initialize the
counting variable as the length minus one:
for (var i = someArray.length - 1; i >= 0; i ) { }
For most arrays and collections, the length property is read-only and governed
solely by the number of items in the group. But in more recent versions of the
browsers, you can assign values to some object arrays (
areas, options, and the
SELECT object) to create placeholders for data assignments. See discussions of the
AREA, SELECT, and OPTION element objects for details. A plain JavaScript array can
also have its
length property value modified by script to either trim items from the
end of the array or reserve space for additional assignments. See Chapter 37 for
more about the

Array object.
On the
CD-ROM
elementObjectCollection.length
131
Chapter 15 ✦ Generic HTML Element Objects
Example on the CD-ROM
Related Items: AREA, SELECT, OPTION, and Array objects.
localName
namespaceURI
prefix
Value: String Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓
The three properties, localName, namespaceURI, and prefix, apply to any
node in an XML document that associates a Namespace URI with an XML tag.
Although NN6 exposes all three properties for all element (and node) objects, the
properties do not return the desired values. Future versions of NN6 should remedy
the situation. In the meantime, this description provides a preview of what values
these three properties will represent.
Consider the following XML content:
<x xmlns:bk=’ /><bk:title>To Kill a Mockingbird</bk:title>
</x>
The element whose tag is <bk:title> is associated with the Namespace URI
defined for the block, and the element’s
namespaceURI property would return the
string
The tag name consists of a prefix (before
the colon) and the local name (after the colon). In the above example, the
prefix

property for the element defined by the <bk:title> tag would be bk, while the
localName property would return title. The localName property of any node
returns the same value as its
nodeName property value, such as #text for a text
node.
For more information about XML Namespaces, visit />REC-xml-names
.
Related Items:
scopeName, tagUrn properties.
On the
CD-ROM
elementObject.localName
132
Part III ✦ Document Objects Reference
nextSibling
previousSibling
Value: Object reference Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
A sibling element is one that is at the same nested level as another element. For
example, the following P element has two child nodes (the EM and SPAN elements).
Those two child nodes are siblings of each other.
<P>MegaCorp is <EM>the</EM> source of the <SPAN CLASS=”hot”>hottest</SPAN>
gizmos.</P>
Sibling order is determined solely by the source code order of the elements.
Therefore, in the previous example, the EM element has no
previousSibling
property. Meanwhile, the SPAN element has no nextSibling property (meaning
that these properties return
null). These properties provide another way to iterate

through all elements at the same level.
Example on the CD-ROM
Related Items: firstChild, lastChild, childNodes properties;
hasChildNodes(), insertAdjacentElement() methods.
nodeName
Value: String Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
For HTML and XML elements, the name of a node is the same as the tag name.
The
nodeName property is provided for the sake of consistency with the node archi-
tecture specified by the formal W3C DOM standard. The value, just like the
tagName
property, is an all-uppercase string of the tag name (even if the HTML source code
is written with lowercase tags).
Some nodes, such as the text content of an element, do not have a tag. The
nodeName property for such a node is a special value: #text. Another kind of node
is an attribute of an element. For an attribute, the
nodeName is the name of the
attribute. See Chapter 14 for more about
Node object properties.
On the
CD-ROM
elementObject.nodeName
133
Chapter 15 ✦ Generic HTML Element Objects
Example on the CD-ROM
Related Item: tagName property.
nodeType
Value: Integer Read-Only

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
The W3C DOM specification identifies a series of constant values that denote cat-
egories of nodes. Not all of these values are implemented in the W3C DOM-capable
browsers, although NN6 includes more than the two supplied by IE5. Table 15-4 lists
the
nodeType values implemented in recent browsers.
Table 15-4 nodeType Property Values
Value Description IE5/5.5 Nav6 & IE5/Mac
1 Element node ✓✓
2 Attribute node ✓
3 Text (#text) node ✓✓
8 Comment node ✓
9 Document node ✓
The nodeType value is automatically assigned to an element, whether the ele-
ment exists in the document’s HTML source code or it is generated on the fly via a
script. For example, if you create a new element through any of the ways available
by script (for example, by assigning a string encased in HTML tags to the
innerHTML
property or by explicitly invoking the document.createElement() method), the
new element assumes a
nodeType of 1.
NN6 goes one step further in supporting the W3C DOM specification by imple-
menting a set of
Node object property constants for each of the nodeType values.
Table 15-5 lists the entire set as defined in the DOM Level 2 specification (not all of
which are implemented in NN6). Substituting these constants for
nodeType integers
can improve readability of a script. For example, instead of
if (myElem.nodeType == 1) { }

it is much easier to see what’s going on with
if (myElem.nodeType == Node.ELEMENT_NODE) { }
On the
CD-ROM
elementObject.nodeType
134
Part III ✦ Document Objects Reference
Table 15-5 W3C DOM nodeType Constants
Reference nodeType Value
Node.ELEMENT_NODE 1
Node.ATTRIBUTE_NODE 2
Node.TEXT_NODE 3
Node.CDATA_SECTION_NODE 4
Node.ENTITY_REFERENCE_NODE 5
Node.ENTITY_NODE 6
Node.PROCESSING_INSTRUCTION_NODE 7
Node.COMMENT_NODE 8
Node.DOCUMENT_NODE 9
Node.DOCUMENT_TYPE_NODE 10
Node.DOCUMENT_FRAGMENT_NODE 11
Node.NOTATION_NODE 12
Example on the CD-ROM
Related Item: nodeName property.
nodeValue
Value: Number, string, or null Read/Write
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓
Of the node types implemented in the W3C DOM-capable browsers, only the text
and attribute types have readable values. An element’s node value returns a
null

value.
For a text node, the
nodeValue property consists of the actual text for that node.
Such a node cannot contain any further nested elements, so the
nodeValue property
offers another way of reading and modifying what Internet Explorer implements as an
element’s
innerText property.
For an attribute node, the
nodeValue property consists of the value assigned to
that attribute. According to the W3C DOM standard, attribute values should be
On the
CD-ROM
elementObject.nodeValue
135
Chapter 15 ✦ Generic HTML Element Objects
reflected as strings. IE5/Windows, however, returns values of type Number when the
value is all numeric characters. Even if you assign a string version of a number to
such a
nodeValue property, it is converted to a Number type internally. NN6 and
IE5/Mac return
nodeValue values as strings in all cases (and convert numeric
assignments to strings).
Example on the CD-ROM
Related Items: attributes, innerText, nodeType properties.
offsetHeight
offsetWidth
Value: Integer Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓✓

It is nearly impossible to reconcile the actual behavior of these properties with
the descriptions provided by Microsoft for Internet Explorer. The genuine complex-
ity comes when an element has one or more of the following style features
attached: borders, margins, and padding. The property values, especially
offsetWidth, are heavily influenced by the height and width attributes assigned
to an element’s style sheet rule. The permutations of elements and their styles plus
the vastly roving range of resulting values make it difficult to recommend the
offsetHeight and offsetWidth properties unless you manage to find the magic
combination that works for your page layout. Differences abound in these proper-
ties’ treatment across operating system versions of IE.
One advantage that
offsetHeight and offsetWidth have over clientHeight
and clientWidth is that the offset properties have values even when you do not
set dimensions for the element in the HTML tag attributes. That’s because these
values are set in relation to the element’s parent element — most often the BODY
element.
Be aware that for a normal element whose height and width are not specified,
the
offsetHeight is determined by the actual height of the content after all text
flows. But the
offsetWidth always extends the full width (plus or minus borders,
margins, and padding) of the containing element. Therefore, the
offsetWidth
property does not reveal the rendered width of text content that is narrower than
the full parent element width. (Through IE5, no property reveals this information.)
To find out the actual width of text within a full-width, block-level element, wrap the
text within an inline element (such as a SPAN) and inspect the
offsetWidth prop-
erty of the SPAN.
Although the

offsetHeight and offsetWidth properties are not part of the
W3C DOM specification, Netscape has implemented these properties in NN6
On the
CD-ROM
elementObject.offsetHeight
136
Part III ✦ Document Objects Reference
because they are convenient for some scriptable Dynamic HTML tasks. Through
these two properties, a script can read the height and width of any block-level or
inline element. As with IE, the NN6
offsetWidth of a text-oriented block-level ele-
ment is the width of the element’s container. For example, a P element consisting of
only a few words may report an
offsetWidth of many hundreds of pixels because
the paragraph’s block extends the full width of the BODY element that represents
the containing parent of the P element.
Example on the CD-ROM
Related Items: clientHeight, clientWidth properties.
offsetLeft
offsetTop
Value: Integer Read-Only
NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓✓
The offsetLeft and offsetTop properties can suffer from the same version
vagaries that afflict
offsetHeight and offsetWidth properties when borders,
margins, and padding are associated with an element. However, the
offsetLeft
and offsetTop properties are valuable in providing pixel coordinates of an element
within the positioning context of the parent element — even when the elements are

not positioned explicitly.
The offsetLeft and offsetTop properties for positioned elements in
IE/Macintosh do not return the same values as the style.left and style.top
properties of the same element. See Listing 31-17 for an example of how to cor-
rect these discrepancies without having to hard-wire the precise pixel differences
in your code.
The element used as a coordinate context for these properties is whatever ele-
ment the
offsetParent property returns. This means that to determine the pre-
cise position of any element, you may have to add some code that iterates through
the
offsetParent hierarchy until that property returns null.
Although the
offsetLeft and offsetTop properties are not part of the W3C
DOM specification, Netscape has implemented these properties in NN6 because they
are convenient for some scriptable Dynamic HTML tasks. Through these two proper-
ties, a script can read the pixel coordinates of any block-level or inline element.
Measurements are made relative to the BODY element, but this may change in the
future. See the discussion later in this chapter about the
offsetParent property.
Note
On the
CD-ROM
elementObject.offsetLeft
137
Chapter 15 ✦ Generic HTML Element Objects
Example on the CD-ROM
Related Items: clientLeft, clientTop, offsetParent properties.
offsetParent
Value: Object reference Read-Only

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5
Compatibility ✓✓✓✓
The offsetParent property returns a reference to the object that acts as a posi-
tioning context for the current element. Values for the
offsetLeft and offsetTop
properties are measured relative to the top-left corner of the offsetParent object.
The returned object is usually, but not always, the next outermost block-level
container. For most document elements, the
offsetParent object is the docu-
ment.body
object (with exceptions for some elements in some browsers).
Table cells, for example, have different
offsetParent elements in different
browsers:
Browser TD offsetParent
IE4/Windows TR
IE5+/Windows TABLE
IE/Mac TABLE
NN6 BODY
Positioned elements also have different results among browsers. In IE, a first-
level positioned element’s
offsetParent element is the BODY; the offsetParent
of a nested positioned element (for example, one absolute-positioned DIV inside
another) is the next outer container (in other words, the positioning context of the
inner element).
The situation for NN6, however, is not as straightforward as it could be. The
offsetParent for any unpositioned element on the page is the BODY element. But
the
offsetParent property for a positioned element (or any element nested inside
a positioned element) returns

null. Even so, the offsetLeft and offsetTop
properties of a positioned element (and its contents) treat the BODY element as the
positioning context. This approach complicates the calculation of the position of an
element inside a positioned element relative to its container. Future versions of NN6
will likely bring the behavior of the
offsetParent property in line with the IE
behavior. See Chapter 31 for more details on browser-specific treatment of position-
able elements.
On the
CD-ROM
elementObject.offsetParent