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=’http://bigbooks.org/schema’> <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 http://bigbooks.org/schema. 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 http://www.w3.org/TR/ 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 . 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. 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. 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