JavaScript Bible, Gold Edition part 33 pps

168 Part III ✦ Document Objects Reference for inserting, removing, reading, or writing attribute name–value pairs within the node map. To a script, the value of the attributes property can behave the same in both IE5 and the W3C DOM provided that scripts don’t have to dig too deeply into the nature of each object model’s idea of what an attribute object is. In IE5, an attribute object is a relatively simple object consisting of nodeName, nodeValue, and specified properties. In the W3C DOM, an attribute object is something more substantial, primarily because it inherits all the properties of the Node object. Table 5-9 compares the properties of an attribute object in NN6 and IE5. Table 15-9 Attribute Object Properties in NN6 and IE5 NN6 IE5 attributes childNodes firstChild lastChild name nextSibling nodeName nodeName nodeType nodeValue nodeValue ownerDocument parentNode previousSibling specified specified value Admittedly, the three properties implemented in IE5 are the most important, but the shortcut approach negates the object-oriented system of the W3C DOM. All of this is a long way to explain the W3C DOM getAttributeNode() method, which returns a W3C DOM attribute object. The sole parameter of the method is a case-insensitive string version of the attribute’s name. You can then use any of the properties shown in Table 15-9 to get or set attribute values. Of course, HTML attributes are generally exposed as properties of HTML elements, so it is usually easier to read or write the object’s properties directly. Example on the CD-ROM On the CD-ROM elementObject.getAttributeNode() 169 Chapter 15 ✦ Generic HTML Element Objects Related Items: attributes property; getAttribute(), removeAttributeNode(), setAttributeNode() methods. getBoundingClientRect() Returns: TextRectangle object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ IE5+ assigns to every content-holding element a rectangle that describes the space that the element occupies on the page. This rectangle is called a bounding rectangle, and it is expressed in the IE5/Windows object model as a TextRectangle object (even when the content is an image or some other kind of object). A TextRectangle object has four properties (top, left, bottom, and right) that are the pixel coordinates that define the rectangle. The getBoundingClientRect() method returns a TextRectangle object that describes the bounding rectangle of the current object. You can access an individual measure of an object’s bounding rectangle, as in the following example: var parTop = document.all.myP.getBoundingClientRect().top For elements that consist of text, such as paragraphs, the dimensions of individual TextRectangles for each line of text in the element influence the dimensions of the bounding rectangle. For example, if a paragraph contains two lines, and the second line extends only halfway across the width of the first line, the width of the second line’s TextRectangle object is only as wide as the actual text in the second line. But because the first line extends close to the right margin, the width of the encompass- ing bounding rectangle is governed by that wider, first line TextRectangle. Therefore, an element’s bounding rectangle is as wide as its widest line and as tall as the sum of the height of all TextRectangle objects in the paragraph. Another method, getClientRects(), enables you to obtain a collection of line- by-line TextRectangle objects for an element. Neither method is implemented in IE5/Mac. Example (with Listing 15-27) on the CD-ROM Related Items: getClientRects() method; TextRectangle object (Chapter 19). getClientRects() Returns: Array of TextRectangle objects. On the CD-ROM elementObject.getClientRects() 170 Part III ✦ Document Objects Reference NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The getClientRects() method returns an array of all TextRectangle objects that fall within the current object the moment the method is invoked. Each TextRectangle object has its own top, left, bottom, and right coordinate prop- erties. You can then, for example, loop through all objects in this array to calculate the pixel width of each line. If you want to find out the aggregate height and/or max- imum width of the entire collection, you can use the getBoundingClientRect() method as a shortcut. This method is not implemented in IE5/Mac. Example on the CD-ROM Related Items: getBoundingClientRect() method; TextRectangle object (Chapter 19). getElementsByTagName(“tagName”) Returns: Array of element objects. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The getElementsByTagName() method returns an array of all elements of the current object whose tags match the tag name supplied as the sole parameter to the method. The tag name parameter must be in the form of a string and is case-insensi- tive. The group of elements returned in the array includes only those elements that are within the containment scope of the current object. Therefore, if you have two table objects in a document and you invoke the getElementsByTagName(“td”) method on one of them, the list of returned table cell elements is confined to those cells within the current table object. The current element is not included in the returned array. The W3C DOM (but not implemented in IE5.x/Windows) accepts a wildcard char- acter ( “*”) as a parameter to the getElementsByTagName() method. The resulting array of elements is similar to what IE4+ returns via the document.all collection. See Chapter 14 for ideas on simulating document.all in NN6 using this technique. Internet Explorer provides additional alternate syntax for this method: the tags() method of the all collection. This alternate syntax also works in IE4 (see the all property earlier in this chapter). On the CD-ROM elementObject.getElementsByTagName() 171 Chapter 15 ✦ Generic HTML Element Objects Example on the CD-ROM Related Items: getElementById(), tags() methods. getExpression(“attributeName”) Returns: String. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The getExpression() method (not implemented in IE5/Mac) returns the text of the expression that was assigned to an element’s attribute via the setExpression() method. The returned value is not the value of the expression, but rather the expres- sion itself. If you want to find out the current value of the expression (assuming that the variables used are within the scope of your script), you can use the eval() func- tion on the call to getExpression(). This action converts the string to a JavaScript expression and returns the evaluated result. One parameter, a string version of the attribute name, is required. Example on the CD-ROM Related Items: document.recalc(), removeExpression(), setExpression() methods. hasChildNodes() Returns: Boolean. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The hasChildNodes() method returns true if the current object has child nodes nested within; it returns false otherwise. A child node is not necessarily the same as a child element, so the following two expressions return true when the current object has at least one child node: document.getElementById(“myObject”).hasChildNodes() document.getElementById(“myObject”).childNodes.length > 0 On the CD-ROM On the CD-ROM elementObject.hasChildNodes() 172 Part III ✦ Document Objects Reference You cannot use the second expression interchangeably with the following state- ment (which uses the IE-only children property): document.getElementById(“myObject”).children.length > 0 You generally use the hasChildNodes() method in a conditional expression to make sure such nodes exist before performing operations on them: if (document.getElementById(“myObject”).hasChildNodes() { statements that apply to child nodes } Example on the CD-ROM Related Items: childNodes property; appendChild(), removeChild(), replaceChild() methods. insertAdjacentElement(“location”, elementObject) Returns: Object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The insertAdjacentElement() method (not implemented in IE5/Mac) inserts an element object (coming from a variety of sources) in a specific position relative to the current object. Both parameters are required. The first must be one of four possible case-insensitive locations for the insertion, shown in the following table: Location Description beforeBegin Before the current element’s start tag afterBegin After the start tag, but before any nested content beforeEnd Before the end tag, but after all other nested content afterEnd After the end tag These locations are relative to the current object. The element type of the cur- rent object (a block-level or inline element) has great bearing on how the inserted element is rendered. For example, suppose you create a B element (using docu- ment.createElement() ) and assign some inner text to it. You then use insertAdjacentElement() in an effort to insert this B element before some text in a P element. Because a P element is a block-level element, the location On the CD-ROM elementObject.insertAdjacentElement() 173 Chapter 15 ✦ Generic HTML Element Objects beforeBegin places the new B element before the start tag of the P element. This means, however, that the bold text appears in a text line above the start of the P element because a <P> tag begins a new block at the left margin of its container (unless instructed otherwise by style sheets). The resulting HTML looks like the following: <B>The new element.</B><P>The original paragraph element.</P> To make the new B element a part of the P element — but in front of the existing P element’s content — use the afterBegin location. The resulting HTML looks like the following: <P><B>The new element.</B>The original paragraph element.</P> To complete the demonstration of the four location types, the following is the result of the beforeEnd location: <P>The original paragraph element. <B>The new element.</B></P> and this is the result of the afterEnd location: <P>The original paragraph element.</P><B>The new element.</B> The object to be inserted is a reference to an element object. The object refer- ence can come from any expression that evaluates to an element object or, more likely, from the result of the document.createElement() method. Bear in mind that the object generated by document.createElement() initially has no content, and all attribute values are set to default values. Moreover, the object is passed to insertAdjacentElement() by reference, which means that there is only one instance of that object. If you attempt to insert that object in two places with two statements, the object is moved from the first location to the second. If you need to copy an existing object so that the original is not moved or otherwise disturbed by this method, use the cloneNode() method to specify the true parameter to cap- ture all nested content of the node. Do not use this method to insert new table elements into a table. Instead, use the many table-specific insertion methods that better treat rows, columns, and cells of a table (see Chapter 27). And if you wish to insert an element that surrounds the current element or wraps all of the content of the current element, use the applyElement() method. Example on the CD-ROM Related Items: document.createElement(), applyElement() methods. insertAdjacentHTML(“location”, “HTMLtext”) insertAdjacentText(“location”, “text”) Returns: Nothing. On the CD-ROM elementObject.insertAdjacentHTML() 174 Part III ✦ Document Objects Reference NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ These two methods insert HTML or straight text at a location relative to the current element. They are intended for use after a page loads, rather than inserting content while the page loads (in which case you can use document.write() wher- ever you need evaluated content to appear on the page). The first parameter must be one of four possible case-insensitive locations for the insertion, shown in the following table: Location Description beforeBegin Before the current element’s start tag afterBegin After the start tag, but before any nested content beforeEnd Before the end tag, but after all other nested content afterEnd After the end tag These locations yield the same results as described in the insertAdjacentElement() function discussed earlier. Whether you use insertAdjacentHTML() or insertAdjacentText() depends on the nature of your content and what you want the browser to do with it. If the content contains HTML tags that you want the browser to interpret and render as if it were part of the page source code, then use the insertAdjacentHTML() method. All tags become objects in the document’s object model. But if you want only to display some text (including HTML tags in their “raw” form), use insertAdjacentText(). The rendering engine does not interpret any tags included in the string passed as the second parameter. Instead, these tags are dis- played as characters on the page. This distinction is identical to the one between the innerHTML and innerText properties. The difference between insertAdjacentHTML() and insertAdjacentElement() is the nature of the content that you insert. The for- mer enables you to accumulate the HTML as a string, while the latter requires the creation of an element object. Also, the two methods in this section work with IE4+ (including Mac versions), whereas insertAdjacentElement() requires the newer object model of IE5 and later. If the HTML you pass as the second parameter of insertAdjacentHTML() contains <SCRIPT> tags, you must set the DEFER attribute in the opening tag. This prevents script statements from executing as you insert them. For inserting new elements into an existing table, use the variety of table object methods for managing rows, columns, and cells (see Chapter 27). elementObject.insertAdjacentHTML() 175 Chapter 15 ✦ Generic HTML Element Objects Example on the CD-ROM Related Items: innerText, innerHTML, outerText, outerHTML properties; insertAdjacentElement(), replaceAdjacentText() methods. insertBefore(newChildNodeObject[, referenceChildNode]) Returns: Node object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The insertBefore() method is the W3C DOM syntax for inserting a new child node into an existing element. Node references for both parameters must be valid Node objects (including those that document.createElement() generates). The behavior of this method might seem counter-intuitive at times. If you include the second parameter (a reference to an existing child node of the current ele- ment), the new child node is inserted before that existing one. But if you omit the second parameter (or its value is null), the new child node is inserted as the last child of the current element — in which case, the method acts the same as the appendChild() method. The true power of this method is summoned when you specify that second parameter; from the point of view of a parent element, you can drop a new child into any spot among its existing children. Bear in mind that the insertBefore() method works from a parent element. Internet Explorer provides additional methods, such as insertAdjacentElement(), to operate from the perspective of what will become a child element. Example (with Listing 15-28) on the CD-ROM Related Items: appendChild(), replaceChild(), removeChild(), insertAdjacentElement() methods. item(index | “index” [, subIndex]) Returns: Object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ On the CD-ROM On the CD-ROM elementObjectCollection.item() 176 Part III ✦ Document Objects Reference The item() method works with most objects that are themselves collections of other objects. In the W3C DOM framework, these kinds of objects are known as named node lists (for objects such as nodes and attributes) or HTML collections (for objects such as elements of a form). While the W3C DOM defines the item() method, it does so with a single numeric parameter that is the index value of the desired object within the collection. NN6 implements this version. If you know the index number of the item, you can use JavaScript array syntax instead. The follow- ing two statements return the same object reference: document.getElementById(“myTable”).childNodes.item(2) document.getElementById(“myTable”).childNodes[2] And for IE’s all object, the index value for a given element is the same as the element’s sourceIndex property. IE4+ extends the possibilities by also allowing a string of the ID of an object within the collection. (Integer values are required for the attributes, rules, and TextRectangle objects, however.) Additionally, if the collection has more than one object with the same ID (never a good idea except when necessary), a second numeric parameter enables you to select which identically named group you want (using zero-based index values within that subgroup). This obviously does not apply to collections, such as attributes and rules, which have no ID associated with them. The method returns a reference to the object specified by the parameters. Example on the CD-ROM Related Items: All object element properties that return collections (arrays) of other objects. mergeAttributes(“sourceObject”) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The mergeAttributes() method (not implemented in IE5/Mac) is a convenient way to propagate attributes in newly created elements without painstakingly adding attributes one at a time. Once you have an object whose attributes can function as a prototype for other elements, those attributes (except for the ID attribute) can be applied to a newly created element instantaneously. Example (with Listing 15-29) on the CD-ROM On the CD-ROM On the CD-ROM elementObject.mergeAttributes() 177 Chapter 15 ✦ Generic HTML Element Objects Related Items: clearAttributes(), cloneNode(), removeAttributes() methods. normalize() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ In the course of appending, inserting, removing, and replacing child nodes of an element, it is conceivable that two text nodes can end up adjacent to each other. While this typically has no effect on the rendering of the content, some XML-centric applications that rely heavily on the document node hierarchy to interpret content properly may not like having two text nodes sitting next to each other. The “proper” form of a node hierarchy is for a single text node to be bounded by other node types. The normalize() method sweeps through the child nodes of the current node object and combines adjacent text nodes into a single text node. The effect obviously impacts the number of child nodes of an element, but it also cleanses the nested node hierarchy. Example on the CD-ROM Related Items: document.createTextNode(), appendChild(), insertBefore(), removeChild(), replaceChild() methods. releaseCapture() setCapture(containerBoolean) Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ You can instruct a single object on an IE5+/Windows page to capture all mouse events ( onmousedown, onmouseup, onmousemove, onmouseout, onmouseover, onclick, and ondblclick) via the IE-specific setCapture() method. This type of event capture is somewhat similar to event capture mechanisms of NN4 and NN6 (which are quite different in and of themselves). However, the syntax is entirely different, as is the overall approach to the code that handles events (see Chapter 29 on the Event object). On the CD-ROM elementObject.releaseCapture() . 168 Part III ✦ Document Objects Reference for inserting, removing, reading, or writing attribute name–value. access an individual measure of an object’s bounding rectangle, as in the following example: var parTop = document.all.myP.getBoundingClientRect().top For elements that consist of text, such as. 19). getClientRects() Returns: Array of TextRectangle objects. On the CD-ROM elementObject.getClientRects() 170 Part III ✦ Document Objects Reference NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility