JavaScript Bible, Gold Edition part 27 pot

108 Part III ✦ Document Objects Reference Table 15-1 (continued) Properties Methods Event Handlers language removeBehavior() onMouseOver lastChild removeChild() onMouseUp length removeEventListener() onPaste localName removeExpression() onPropertyChange namespaceURI removeNode() onReadyStateChange nextSibling replaceAdjacentText() onResize nodeName replaceChild() onResizeEnd nodeType replaceNode() onResizeStart nodeValue scrollIntoView() onSelectStart offsetHeight setActive() offsetLeft setAttribute() offsetParent setAttributeNode() offsetTop setCapture() offsetWidth setExpression() outerHTML supports() outerText swapNode() ownerDocument tags() parentElement urns() parentNode parentTextEdit prefix previousSibling readyState recordNumber runtimeStyle scopeName scrollHeight scrollLeft scrollTop scrollWidth elementObject 109 Chapter 15 ✦ Generic HTML Element Objects Properties Methods Event Handlers sourceIndex style tabIndex tagName tagUrn title uniqueID Syntax To access element properties or methods, use this: (IE4+) [document.all.]objectID.property | method([parameters]) (IE5+/NN6) document.getElementById(objectID).property | method([parameters]) About these objects All objects listed in Table 15-1 are DOM representations of HTML elements that influence either the font style or the context of some HTML content. The large set of properties, methods, and event handlers associated with these objects also applies to virtually every other DOM object that represents an HTML element. Discussions about object details in this chapter apply to dozens of other objects described in succeeding chapters of this reference section. Properties accessKey Value: One-Character String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ For many elements, you can specify a keyboard character (letter, numeral, or punctuation symbol) that, when typed as an Alt+key combination (on the Win32 OS platform) or Ctrl+key combination (on the MacOS), brings focus to that element. An element that has focus is the one that is set to respond to keyboard activity. If the newly focused element is out of view in the document’s current scroll position, the document is scrolled to bring that focused element into view (also see the scrollIntoView() method). The character you specify can be an uppercase or lowercase value, but these values are not case-sensitive. If you assign the same elementObject.accessKey 110 Part III ✦ Document Objects Reference letter to more than one element, the user can cycle through all elements associated with that accessKey value. For IE4, not all elements can receive focus in a meaningful way. For that browser version, you should limit this property to elements that can actually receive focus, such as form elements and links. One way to see what elements on a page can receive focus is to repeatedly press the Tab key while the document is visible. In the Windows platforms, either a dotted line around the element or a text insertion pointer flashing inside a text entry element indicates the focus. Not all operating system platforms provide focus to the same set of elements. IE4 for the Macintosh, for example, does not give focus to button elements. For IE5.5, however, any ele- ment can receive focus — even if no visible outline explicitly indicates this state. Internet Explorer gives some added powers to the accessKey property in some cases. For example, if you assign an accessKey value to a LABEL element object, the focus is handed to the form element associated with that label. Also, when ele- ments such as buttons have focus, pressing the spacebar acts the same as clicking the element with a mouse. Exercise some judgement in selecting characters for accessKey values. If you assign a letter that is normally used to access one of the Windows version browser’s built-in menus (for example, Alt+F for the File menu), that accessKey setting overrides the browser’s normal behavior. To users who rely on keyboard access to menus, your control over that key combination can be disconcerting. Example (with Listing 15-1) on the CD-ROM Related Item: srcollIntoView() method. all Value: Array of nested element objects. Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The all property is a collection (array) of every HTML element and (in IE5+) XML tag within the scope of the current object. Items in this array appear in source- code order, and the array is oblivious to element containment among the items. For HTML element containers, the source-code order is dependent on the position of the start tag for the element — end tags are not counted. But for XML tags, end tags appear as separate entries in the array. Every document.all collection contains objects for the HTML, HEAD, TITLE, and BODY element objects even if the actual HTML source code omits the tags. The object model creates these objects for every document that is loaded into a win- dow or frame. While the document.all reference may be the most common usage, On the CD-ROM elementObject.all 111 Chapter 15 ✦ Generic HTML Element Objects the all property is available for any container element. For example, document. forms[0].all exposes all elements defined within the first form of a page. You can access any element that has an identifier assigned to its ID attribute by that identifier in string form (as well as by index integer). Rather than use the per- formance-costly eval() function to convert a string to an object reference, use the string value of the name as an array index value: var paragraph = document.all[“myP”] Internet Explorer enables you to use either square brackets or parentheses for single collection index values. Thus, the following two examples evaluate identically: var paragraph = document.all[“myP”] var paragraph = document.all(“myP”) In the rare case that more than one element within the all collection has the same ID, the syntax for the string index value returns a collection of just those iden- tically named elements. But you can use a second argument (in parentheses) to sig- nify the integer of the initial collection and thus single out a specific instance of that named element: var secondRadio = document.all(“group0”,1) As a more readable alternative, you can use the item() method (described later in this chapter) to access the same kinds of items within a collection: var secondRadio = document.all.item(“group0”,1) Also see the tags() method (later in this chapter) as a way to extract a set of elements from an all collection that matches a specific tag name. You can simulate the behavior of IE’s all property in NN6. See Chapter 14 for the code you need to add to make that happen. Example on the CD-ROM Related Items: item(), tags() methods. attributes Value: Array of attribute object references. Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The attributes property consists of an array of attributes specified for an ele- ment. In IE5, the attributes array contains an entry for every possible property that the browser has defined for its elements — even if the attribute is not set explicitly in the HTML tag. Also, any attributes that you add later via script facilities On the CD-ROM elementObject.attributes 112 Part III ✦ Document Objects Reference such as the setAttribute() method are not reflected in the attributes array. In other words, the IE5 attributes array is fixed, using default values for all proper- ties except those that you explicitly set as attributes in the HTML tag. NN6’s attributes property returns an array that is a named node map (in W3C DOM terminology). NN6 does not implement all W3C DOM Level 2 methods for a named node map, but you can use the getNamedItem(attrName) and item(index) methods on the array returned from the attributes property to access individual attribute objects via W3C DOM syntax. IE5 and NN6 have different ideas about what an attribute object should be. Table 15-2 shows the variety of properties of an attribute object as defined by the two object models. The larger set of properties in NN6 reveals its dependence on the W3C DOM node inheritance model discussed in Chapter 14. Table 15-2 Attribute Object Properties Property IE5.x NN6 Description attributes No Yes Array of nested attribute objects (null) childNodes No Yes Child node array firstChild No Yes First child node lastChild No Yes Last child node localName No Yes Name within current namespace name No Yes Attribute name nameSpaceURI No Yes XML namespace URI nextSibling No Yes Next sibling node nodeName Yes Yes Attribute name nodeType No Yes Node type (2) nodeValue Yes Yes Value assigned to attribute ownerDocument No Yes document object reference ownerElement No Yes Element node reference parentNode No Yes Parent node reference prefix No Yes XML namespace prefix previousSibling No Yes Previous sibling node specified Yes Yes Whether attribute is explicitly specified (Boolean) value No Yes Value assigned to attribute The most helpful property of an attribute object is the Boolean specified prop- erty. In IE, this lets you know whether the attribute is explicitly specified in the elementObject.attributes 113 Chapter 15 ✦ Generic HTML Element Objects element’s tag. Because NN6 returns only explicitly specified attributes in the attributes array, the value in NN6 is always true. Example on the CD-ROM Related Items: mergeAttributes(), removeAttribute(), setAttribute() methods. behaviorUrns Value: Array of behavior URN strings Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The behaviorUrns property is designed to provide a list of addresses, in the form of URNs (Uniform Resource Names), of all behaviors assigned to the current object. If there are no behaviors, the array has a length of zero. In practice, how- ever, IE5 always returns an array of empty strings. Perhaps the potential exposure of URNs by script was deemed to be a privacy risk. Example on the CD-ROM Related Item: urns() method. canHaveChildren Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ Useful in some dynamic content situations, the canHaveChildren property (not implemented in IE5/Mac) reveals whether a particular element is capable of containing a child (nested) element. Most elements that have start and end tags (particularly the generic elements covered in this chapter) can contain nested elements. In modern object models, a nested element is referred to as a child of its parent container. On the CD-ROM On the CD-ROM elementObject.canHaveChildren 114 Part III ✦ Document Objects Reference Example (with Listing 15-2) on the CD-ROM Related Items: childNodes, firstChild, lastChild, parentElement, parentNode properties; appendChild(), hasChildNodes(), removeChild() methods. canHaveHTML Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ While most HTML elements are containers of HTML content, not all are. The canHaveHTML property lets scripts find out whether a particular object can accept HTML content, such as for insertion or replacement by object methods. The value for a P element, for example, is true. The value for a BR element is false. Example on the CD-ROM Related Items: appendChild(), insertAdjacentHTML(), insertBefore() methods. childNodes Value: Array of node objects. Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The childNodes property consists of an array of node objects contained by the current object. Note that child nodes consist of both element objects and text nodes. Therefore, depending on the content of the current object, the number of childNodes and children collections may differ. On the CD-ROM On the CD-ROM elementObject.childNodes 115 Chapter 15 ✦ Generic HTML Element Objects If you use the childNodes array in a for loop that iterates through a sequence of HTML (or XML) elements, watch out for the possibility that the browser treats source code whitespace (blank lines between elements and even simple carriage returns between elements) as text nodes. This potential problem affects IE5/Mac and NN6 (although later versions may repair the problem). If present, these extra text nodes occur primarily surrounding block elements. Most looping activity through the childNodes array aims to examine, count, or modify element nodes within the collection. If that is your script’s goal, then test each node returned by the childNodes array, and verify that the nodeType property is 1 (element) before processing that node. Otherwise, skip over the node. The skeletal structure of such a loop follows: for (var i = 0; i < myElem.childNodes.length; i++) { if (myElem.childNodes[i].nodeType == 1) { statements to work on element node i } } The presence of these “phantom” text nodes also impacts the nodes referenced by the firstChild and lastChild properties, described later in this chapter. Example (with Listing 15-3) on the CD-ROM Related Items: nodeName, nodeType, nodeValue, parentNode properties; cloneNode(), hasChildNodes(), removeNode(), replaceNode(), swapNode() methods. children Value: Array of element objects. Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The children property consists of an array of element objects contained by the current object. Unlike the childNodes property, children does not take into account text nodes but rather focuses strictly on the HTML (and XML) element con- tainment hierarchy from the point of view of the current object. Children exposed to the current object are immediate children only. If you want to get all element objects nested within the current object (regardless of how deeply nested they are), use the all collection instead. On the CD-ROM Caution elementObject.children 116 Part III ✦ Document Objects Reference Example (with Listing 15-4) on the CD-ROM Related Items: canHaveChildren, firstChild, lastChild, parentElement properties; appendChild(), removeChild(), replaceChild() methods. className Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ A class name is an identifier that is assigned to the CLASS attribute of an element. To associate a CSS rule with several elements in a document, assign the same iden- tifier to the CLASS attributes of those elements, and use that identifier (preceded by a period) as the CSS rule’s selector. An element’s className property enables the application of different CSS rules to that element under script control. Example (with Listing 15-5) on the CD-ROM Related Items: rule, stylesheet objects (Chapter 30); id property. clientHeight clientWidth Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ These two properties by and large reveal the pixel height and width of the con- tent with an element whose style sheet rule includes height and width settings. In theory, these measures do not take into account any margins, borders, or padding that you add to an element by way of style sheets. In practice, however, different combinations of borders, margins, and padding influence these values in unex- pected ways. One of the more reliable applications of the clientHeight property enables you to discover, for example, where the text of an overflowing element ends. On the CD-ROM On the CD-ROM elementObject.clientHeight 117 Chapter 15 ✦ Generic HTML Element Objects For the document.body object, the clientHeight and clientWidth properties return the inside height and width of the window or frame (plus or minus a couple of pixels). These take the place of desirable, but nonexistent, window properties in IE. Internet Explorer 5 expands the number of objects that employ these properties to include virtually all objects that represent HTML elements. For IE4, these proper- ties apply only to the following objects: BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, LEGEND, MARQUEE, TABLE, TD, TEXTAREA, TH, and TR. Example (with Listing 15-6) on the CD-ROM Related Items: offsetHeight, offsetWidth properties. clientLeft clientTop Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The purpose and names of the clientLeft and clientTop properties are confus- ing at best. Unlike the clientHeight and clientWidth properties, which apply to the content of an element, the clientLeft and clientTop properties return essentially no more information than the thickness of a border around an element — provided the ele- ment is positioned. If you do not specify a border or do not position the element, the values are zero (although the document.body object can show a couple of pixels in each direction without explicit settings). If you are trying to read the left and top coor- dinate positions of an element, the offsetLeft and offsetTop properties are more valuable in IE/Windows; as shown in Listing 15-6, however, the clientTop property returns a suitable value in IE/Mac. Virtually all elements have the clientLeft and clientTop properties in IE5+; in IE4, the properties apply only to the BODY, BUTTON, CAPTION, EMBED, FIELDSET, LEGEND, MARQUEE, and TEXTAREA objects. Related Items: offsetLeft, offsetTop properties. contentEditable Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ On the CD-ROM elementObject.contentEditable . implemented in IE5/Mac) reveals whether a particular element is capable of containing a child (nested) element. Most elements that have start and end tags (particularly the generic elements covered. value, but these values are not case-sensitive. If you assign the same elementObject.accessKey 110 Part III ✦ Document Objects Reference letter to more than one element, the user can cycle through. attributes that you add later via script facilities On the CD-ROM elementObject.attributes 112 Part III ✦ Document Objects Reference such as the setAttribute() method are not reflected in the