218Part IIIDocument Objects ReferenceThe purpose and names of the clientLeftand clientTopproperties are confusing at best. Unlike the clientHeightand clientWidthproperties, which apply to the content of an element, the clientLeftand clientTopproperties return essentially no more informationthan the thickness of a border around an element provided the element is positioned. Ifyou do not specify a border or do not position the element, the values are zero (although the document.bodyobject can show a couple of pixels in each direction without explicit settings). If you are trying to read the left and top coordinate positions of an element, theoffsetLeftand offsetTopproperties are more valuable in WinIE; as shown in Listing 15-6, however, the clientTopproperty returns a suitable value in MacIE. Virtually all elementshave the clientLeftand clientTopproperties in IE5+; in IE4, the properties apply only tothe body, button, caption, embed, fieldset, legend, marquee, and textareaobjects. Related Items:offsetLeft, offsetTopproperties. contentEditableValue:Boolean.Read/Write Compatibility:WinIE5.5+, MacIE-, NN-, Moz-, Safari- IE5.5 introduced the concept of editable HTML content on a page. Element tags can include acontenteditableattribute, whose value is echoed via the contentEditableproperty ofthe element. The default value for this property is inherit, which means that the propertyinherits whatever setting this property has in the hierarchy of HTML containers outward tothe body. If you set the contentEditableproperty to true, that element and all nested ele- ments set to inherit the value become editable; conversely, a setting of falseturns off theoption to edit the content. ExampleListing 15-7 demonstrates how to use the contentEditableproperty to allow a piece of textto be edited. When you click the button of a freshly loaded page, the toggleEdit()functioncaptures the opposite of the current editable state via the isContentEditableproperty ofthe divthat is subject to edit. You switch on editing for that element in the next statement byassigning the new value to the contentEditableproperty of the div. For added impact, turnthe text of the divto red to provide additional user feedback about what is editable on thepage. You can also switch the button label to one that indicates the action invoked by thenext click on it. Listing 15-7: Using the contentEditable Property elementObject.clientLeft

217Chapter 15Generic HTML Element ObjectsListing 15-6: Using clientHeight and clientWidth Properties Position and Show Logo Art

To assist in the vertical positioning of the logo, the offsetTopproperty of the divobjectprovides the position of the start of the divwith respect to its outer container (the body). Unfortunately, MacIE uses the clientTopproperty to obtain the desired dimension. Thatmeasure (assigned to the paragraphTopvariable), plus the clientHeightof the div, pro- vides the top coordinate of the image. Related Items: offsetHeight, offsetWidthproperties. clientLeftclientTopValue:Integer.Read-Only Compatibility:WinIE4+, MacIE4+, NN-, Moz-, Safari- elementObject.clientLeft

216Part IIIDocument Objects ReferenceListing 15-5(continued)

A well regulated militia, being necessary to the security of a freestate, the right of the people to keep and bear arms, shall not beinfringed.

You can also create multiple versions of a style rule with different class selector identifiersand apply them at will to a given element. Related Items:rule, stylesheetobjects (Chapter 26); idproperty. clientHeightclientWidthValue:Integer.Read-Only Compatibility:WinIE4+, MacIE4+, NN7, Moz1+, Safari1+ These two properties by and large reveal the pixel height and width of the content within anelement whose stylesheet rule includes height and width settings. In theory, these measuresdo not take into account any margins, borders, or padding that you add to an element byway of stylesheets. In practice, however, different combinations of borders, margins, andpadding influence these values in unexpected ways. One of the more reliable applications ofthe clientHeightproperty enables you to discover, for example, where the text of an over- flowing element ends. To read the rendered dimensions of an element, you are better servedacross browsers with the offsetHeightand offsetWidthproperties. For the document.bodyobject, the clientHeightand clientWidthproperties return theinside height and width of the window or frame (plus or minus a couple of pixels). These takethe place of desirable, but nonexistent, window properties in IE. Internet Explorer 5+ expands the number of objects that employ these properties to includevirtually all objects that represent HTML elements. For IE4, these properties apply only to thefollowing objects: body, button, caption, div, embed, fieldset, legend, marquee, table, td, textarea, th, and tr. Values for these properties in Mozilla-based browsers are zero, except for document.body, which measures the browser s current content area. ExampleListing 15-6 for IE includes an example of how to dynamically size content on a page basedupon the client area width and height. This example calls upon the clientHeightandclientWidthproperties of a divelement that contains a paragraph element. Only the widthof the divelement is specified in its stylesheet rule, which means that the paragraph s textwraps inside that width and extends as deeply as necessary to show the entire paragraph. The clientHeightproperty describes that depth. The clientHeightproperty then calcu- lates where a logo image should be positioned immediately after div, regardless of the lengthof the text. As a bonus, the clientWidthproperty helps the script center the image horizon- tally with respect to the paragraph s text. elementObject.className

215Chapter 15Generic HTML Element ObjectsclassNameValue:String.Read/Write Compatibility:WinIE4+, MacIE4+, NN6+, Moz1+, Safari1+ A class nameis an identifier that is assigned to the classattribute of an element. To associ- ate a CSS rule with several elements in a document, assign the same identifier to the classattributes of those elements, and use that identifier (preceded by a period) as the CSS rule sselector. An element s classNameproperty enables the application of different CSS rules tothat element under script control. Listing 15-5 shows an example of such a script. ExampleThe style of an element toggles between on and off in Listing 15-5 by virtue of setting theelement s classNameproperty alternatively to an existing stylesheet class selector name andan empty string. When you set the classNameto an empty string, the default behavior of theh1element governs the display of the first header. A click of the button forces the stylesheetrule to override the default behavior in the first h1element. Listing 15-5: Working with the className Property

className Property Lab

ARTICLE I

Congress shall make no law respecting an establishment of religion, orprohibiting the free exercise thereof; or abridging the freedom ofspeech, or of the press; or the right of the people peaceably toassemble, and to petition the government for a redress of grievances.

ARTICLE II

ContinuedelementObject.className

214Part IIIDocument Objects Referenceunder construction. Try it out in The Evaluator in IE5+ by entering the following statementsinto the top text field: walkChildren() walkChildren( myP ) The results of this function show the nesting relationships among all parent and child ele- ments within the scope of the initial object. It also shows the act of drilling down to furtherchildrencollections until all child elements are exposed and catalogued. The element tagsalso display their idand/or nameattribute values if any are assigned to the elements in theHTML source code. Listing 15-4: Collecting Child Elementsfunction walkChildren(objRef, n) { var obj; if (objRef) { if (typeof objRef == string ) { obj = document.getElementById(objRef); } else { obj = objRef; } } else { obj = document.body.parentElement; } var output = ; var indent = ; var i, group; if (n) { for (i = 0; i < n; i++) { indent += +--- ; } } else { n = 0; output += Children of < + obj.tagName; output += >n=====================n ; } group = obj.children; for (i = 0; i < group.length; i++) { output += indent + < + group[i].tagName; output += (group[i].id) ? ID= + group[i].id : ; output += (group[i].name) ? NAME= + group[i].name : ; output += >n ; if (group[i].children.length > 0) { output += walkChildren(group[i], n+1); } } return output; } Related Items:canHaveChildren, firstChild, lastChild, parentElementproperties; appendChild(), removeChild(), replaceChild()methods. elementObject.children

213Chapter 15Generic HTML Element Objectsoutput += >n=====================n ; } group = obj.childNodes; for (i = 0; i < group.length; i++) { output += indent; switch (group[i].nodeType) { case 1: output += < + group[i].tagName; output += (group[i].id) ? ID= + group[i].id : ; output += (group[i].name) ? NAME= + group[i].name : ; output += >n ; break; case 3: txt = group[i].nodeValue.substr(0,15); output += [Text: + txt.replace(/[rn]/g, ); if (group[i].nodeValue.length > 15) { output += … ; } output += ]n ; break; case 8: output += [!COMMENT!]n ; break; default: output += [Node Type = + group[i].nodeType + ]n ; } if (group[i].childNodes.length > 0) { output += walkChildNodes(group[i], n+1); } } return output; } Related Items:nodeName, nodeType, nodeValue, parentNodeproperties; cloneNode(), hasChildNodes(), removeNode(), replaceNode(), swapNode()methods. childrenValue:Array of element objects.Read-Only Compatibility:WinIE4+, MacIE4+, NN-, Moz-, Safari- The childrenproperty consists of an array of element objects contained by the currentobject. Unlike the childNodesproperty, childrendoes not take into account text nodes butrather focuses strictly on the HTML (and XML) element containment hierarchy from the pointof view of the current object. Children exposed to the current object are immediate childrenonly. If you want to get all element objects nested within the current object (regardless ofhow deeply nested they are), use the allcollection instead. ExampleListing 15-4 shows how you can use the childrenproperty to walk the child nodes of agiven node. This function accumulates and returns a hierarchical list of child elements fromthe point of view of the document s HTML element (the default) or any element whose IDyou pass as a string parameter. This function is embedded in The Evaluator so that you caninspect the parent child hierarchy of that page or (when using evaluator.jsfor debuggingas described in Chapter 45 on the CD-ROM) the element hierarchy within any page you haveelementObject.children

212Part IIIDocument Objects Referencethe childNodesarray, and verify that the nodeTypeproperty is 1(element) before process- ing 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 thefirstChildand lastChildproperties, described later in this chapter. ExampleListing 15-3 contains an example of how you might code a function that walks the childnodes of a given node. The walkChildNodes()function shown in the listing accumulates andreturns a hierarchical list of child nodes from the point of view of the document s HTML ele- ment (the default) or any element whose ID you pass as a string parameter. This function isembedded in The Evaluator so that you can inspect the child node hierarchy of that page or(when using evaluator.jsfor debugging as described in Chapter 45 on the CD-ROM) thenode hierarchy within any page you have under construction. Try it out in The Evaluator byentering the following statements into the top text field: walkChildNodes() walkChildNodes(getElementById( myP )) The results of this function show the nesting relationships among all child nodes within thescope of the initial object. It also shows the act of drilling down to further childNodescollec- tions until all child nodes are exposed and catalogued. Text nodes are labeled accordingly. The first 15 characters of the actual text are placed in the results to help you identify thenodes when you compare the results against your HTML source code. Listing 15-3: Collecting Child Nodesfunction walkChildNodes(objRef, n) { var obj; if (objRef) { if (typeof objRef == string ) { obj = document.getElementById(objRef); } else { obj = objRef; } } else { obj = (document.body.parentElement) ? document.body.parentElement : document.body.parentNode; } var output = ; var indent = ; var i, group, txt; if (n) { for (i = 0; i < n; i++) { indent += +— ; } } else { n = 0; output += Child Nodes of < + obj.tagName; elementObject.childNodes

211Chapter 15Generic HTML Element Objects 10 Secondary Widget $114.96

Related Items:childNodes, firstChild, lastChild, parentElement, parentNodeproperties; appendChild(), hasChildNodes(), removeChild()methods. canHaveHTMLValue:Boolean.Read-OnlyCompatibility:WinIE5.5+, MacIE-, NN-, Moz-, Safari- While most HTML elements are containers of HTML content, not all are. The canHaveHTMLproperty lets scripts find out whether a particular object can accept HTML content, such asfor insertion or replacement by object methods. The value for a pelement, for example, istrue. The value for a brelement is false. ExampleUse The Evaluator (Chapter 13) to experiment with the canHaveHTMLproperty. Enter the fol- lowing statements into the top text field and observe the results: document.getElementById( input ).canHaveHTMLdocument.getElementById( myP ).canHaveHTMLThe first statement returns falsebecause an inputelement (the top text field in this case) can- not have nested HTML. But the myPelement is a pelement that gladly accepts HTML content. Related Items:appendChild(), insertAdjacentHTML(), insertBefore()methods. childNodes[] Value: Array of node objects.Read-Only Compatibility:WinIE5+, MacIE5+, NN6+, Moz1+, Safari1+ The childNodesproperty consists of an array of node objects contained by the currentobject. Note that child nodes consist of both element objects and text nodes. Therefore, depending on the content of the current object, the number of childNodesand children col- lections may differ. If you use the childNodesarray in a forloop that iterates through a sequence of HTML (orXML) 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 textnodes. This potential problem affects MacIE5 and Moz1. If present, these extra text nodesoccur primarily surrounding block elements. Most looping activity through the childNodesarray aims to examine, count, or modify ele- ment nodes within the collection. If that is your script s goal, then test each node returned byCautionelementObject.childNodes

210Part IIIDocument Objects ReferenceThus, elements (including the normally non-childbearing ones such as hrand input) areaffected by the color change. But if you reset the page and click the largest button, onlythose elements that can contain nested elements receive the color change. Listing 15-2: Reading the canHaveChildren Property

canHaveChildren Property Lab