JavaScript Bible, Gold Edition part 32 pdf

158 Part III ✦ Document Objects Reference An unfortunate side effect of button focus in Win32 environments is that the focus highlight (a dotted rectangle) remains around the button after a user clicks it and until another object gets focus. You can eliminate this artifact for browsers and objects that implement the onMouseUp event handler by including the following event handler in your buttons: onMouseUp = “this.blur()” IE5.5 recognizes the often undesirable effect of that dotted rectangle and lets scripts set the hideFocus property of an element to true to keep that rectangle hidden while still giving the element focus. It is a tradeoff for the user, however, because there is no visual feedback about which element has focus. Other elements For other kinds of elements that support the focus() method, you can bring an element into view in lieu of the scrollIntoView() method. Link (A) and AREA ele- ments in Windows versions of IE display the dotted rectangle around them after a user brings focus to them. To eliminate that artifact, use the same onMouseUp = “this.blur()” event handler as (or IE5.5 hideFocus property) just described for form controls. Microsoft increased the breadth of objects that support the blur() and focus() methods in IE5. Example (with Listing 15-23) on the CD-ROM Related Items: window.open(), document.formObject.textObject.select() methods. clearAttributes() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The clearAttributes() method removes all attributes from an element except the NAME and ID values. Thus, styles and event handlers are removed, as are cus- tom attributes assigned in either the HTML source code or later by script. You should know that the clearAttributes() method does not alter the length of the element’s attributes collection because the collection always contains all possi- ble attributes for an element. (See the attributes property for elements earlier in this chapter.) This method is handy if you wish to construct an entirely new set of attributes for an element and prefer to start out with a blank slate. Be aware, however, that On the CD-ROM elementObject.clearAttributes() 159 Chapter 15 ✦ Generic HTML Element Objects unless your scripts immediately assign new attributes to the element, the appearance of the element reverts to its completely unadorned form until you assign new attributes. This means that even positioned elements find their way back to their source code order until you assign a new positioning style. If you sim- ply want to change the value of one or more attributes of an element, it is faster to use the setAttribute() method or adjust the corresponding property. To accomplish a result in NN6 that simulates that of IE5’s clearAttributes(), you must iterate through all attributes of an element and remove those attributes (via the removeAttribute() method) whose names are other than ID and NAME. Example on the CD-ROM Related Items: attributes property; getAttribute(), setAttribute(), removeAttribute(), mergeAttributes(), and setAttributeNode() methods. click() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ ✓ ✓ ✓ ✓✓ ✓ The click() method lets a script perform nearly the same action as clicking an element. While this method was available in one form or another since the begin- ning of scripting, it was available only on INPUT elements that act as buttons (input type button, reset, submit, radio, and checkbox). Most element objects received the method in IE4 and NN6. The behavior of the click() method has also changed over time. Prior to NN4 and IE4, the click() method invoked on a button did not trigger the onClick event handler for the object. This has significant impact if you expect the onClick event handler of a button to function even if a script performs the “click.” For ear- lier browser versions, you have to invoke the event handler statements directly. Also, just because a script is “clicking” a button, not all buttons in all platforms change their appearance in response. For example, NN4 on the Mac does not change the state of a checkbox when clicked remotely. (Win32 versions of version 4 browsers do change state.) If you want to script the action of “clicking” a button, you can safely invoke the resulting event handler function directly. And if the element is a radio button or checkbox, handle the change of state directly (for example, set the checked prop- erty of a checkbox) rather than expect the browser to take care of it for you. Example on the CD-ROM On the CD-ROM On the CD-ROM elementObject.click() 160 Part III ✦ Document Objects Reference Related Item: onClick event handler. cloneNode(deepBoolean) Returns: Node object reference. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The cloneNode() method makes an exact copy of the current node object. This copy does not have a parent node or other relationship with any element once the copy exists (of course, the original node remains in place). The clone also does not become part of the document’s object model unless you explicitly insert or append the node somewhere on the page. The copy includes all element attributes, includ- ing the ID attribute. Because the value returned by the cloneNode() method is a genuine Node object, you can operate on it with any Node object methods while it is still in the non-document object state. The Boolean parameter of the cloneNode() method controls whether the copy of the node includes all child nodes ( true) or just the node itself (false). For example, if you clone a paragraph element by itself, the clone consists only of the raw element (equivalent of the tag pair, including attributes in the start tag) and none of its content. But including child nodes makes sure that all content within that paragraph element is part of the copy. This parameter is optional in IE5 (defaulting to false), but it is required in NN6 and the W3C DOM. Example on the CD-ROM Related Items: Node object (Chapter 14); appendChild(), removeChild(), removeNode(), replaceChild(), and replaceNode() methods. componentFromPoint(x,y) Returns: String. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The componentFromPoint() method assists in some event-related tasks. You can use it for a kind of collision detection (in other words, to determine whether an event occurs inside or outside of a particular element). If the element has scroll- bars, the method can provide additional information about the event such as precisely which component of the scrollbar the user activates. The method is not implemented in IE5/Mac. On the CD-ROM elementObject.componentFromPoint() 161 Chapter 15 ✦ Generic HTML Element Objects A key aspect of this method is that you invoke it on any element that you want to use as the point of reference. For example, if you want to find out if a mouseup event occurs in an element whose ID is myTable, invoke the method as follows: var result = document.all.myTable.componentFromPoint(event.clientX, event.clientY) Parameters passed to the method are x and y coordinates. These coordinates do not have to come from an event, but the most likely scenario links this method with an event of some kind. Mouse events (other than click) work best. The value returned by the method is a string that provides details about where the coordinate point is with respect to the current element. If the coordinate point is inside the element’s rectangle, the returned value is an empty string. Conversely, if the point is completely outside of the element, the returned value is the string “out- side” . For scrollbar pieces, the list of possible returned values is quite lengthy (as shown in Table 15-8). Microsoft defines additional values representing pieces of ele- ment resizing handles when the browser is set to what the company calls DHTML authoring mode in Windows. This mode involves a special ActiveX control that is outside the scope of this book. Table 15-8 lists these extra values just the same. Table 15-8 Returned Values for componentFromPoint() Returned String Element Component at Coordinate Point scrollbarDown Scrollbar down arrow scrollbarHThumb Scrollbar thumb on horizontal bar scrollbarLeft Scrollbar left arrow scrollbarPageDown Scrollbar page-down region scrollbarPageLeft Scrollbar page-left region scrollbarPageRight Scrollbar page-right region scrollbarPageUp Scrollbar page-up region scrollbarRight Scrollbar right arrow scrollbarUp Scrollbar up arrow scrollbarVThumb Scrollbar thumb on vertical bar handleBottom Resize handle at bottom handleBottomLeft Resize handle at bottom left handleBottomRight Resize handle at bottom right handleLeft Resize handle at left handleRight Resize handle at right handleTop Resize handle at top handleTopLeft Resize handle at top left handleTopRight Resize handle at top right elementObject.componentFromPoint() 162 Part III ✦ Document Objects Reference You do not have to use this method for most collision or event detection, how- ever. The event object’s srcElement property returns a reference to whatever object receives the event. Example (with Listing 15-24) on the CD-ROM Related Item: event object. contains(elementObjectReference) Returns: Boolean. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The contains() method reports whether the current object contains another known object within its HTML containment hierarchy. Note that this is not geo- graphical collision detection of overlapping elements, but rather the determination of whether one element is nested somewhere within another. The scope of the contains() method extends as deeply within the current object’s hierarchy as is necessary to locate the object. In essence, the contains() method examines all of the elements that are part of an element’s all array. Therefore, you can use this method as a shortcut replacement for a for loop that examines each nested element of a container for the existence of a specific element. The parameter to the contains() method is a reference to an object. If you have only the element’s ID as a string to go by, you can use the document.all.item() method to generate a valid reference to the nested element. If the parameter is a reference to an element that has the same ID as another within the scope of the method, a script error results because a reference to such an element returns an array of elements rather than a valid object reference. An element always contains itself. Example on the CD-ROM Related Items: item(), document.getElementById() methods. On the CD-ROM Note On the CD-ROM elementObject.contains() 163 Chapter 15 ✦ Generic HTML Element Objects detachEvent() See attachEvent(). dispatchEvent(eventObject) Returns: Boolean. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The dispatchEvent() method allows a script to fire an event aimed at any object capable of supporting that event. This is the W3C event model way of gener- alizing mechanisms that earlier browsers sometimes mimic with object methods such as click() and focus(). The process of generating one of these events is similar to the way a script gen- erates a new node and inserts that node somewhere in the document object model. For events, however, the object that is created is an Event object, which is gener- ated via the document.createEvent() method. An event generated in this manner is simply a specification about an event. Use properties of an event object to supply specifics about the event, such as its coordinates or mouse button. Then dispatch the event to a target object by invoking that target object’s dispatchEvent() method and passing the newly created Event object as the sole parameter. Interpreting the meaning of the Boolean value that the dispatchEvent() method returns is not straightforward. The browser follows the dispatched event through whatever event propagation is in effect for that object and event type (either bub- bling or capture). If any of the event listener functions that are triggered by this dispatched event invoke the preventDefault() method, the dispatchEvent() method returns false to indicate that the event did not trigger the native action of the object; otherwise, the method returns true. Notice that this returned value indi- cates nothing about propagation type or how many event listeners run as a result of dispatching this event. While the dispatchEvent() method is implemented in NN6, the browser does not yet provide a way to generate new events from scratch. And if you attempt to redirect an existing event to another object via the dispatchEvent() method, the browser is prone to crashing. Example (with Listing 15-25) on the CD-ROM Related Item: fireEvent() method. On the CD-ROM Caution elementObject.dispatchEvent() 164 Part III ✦ Document Objects Reference fireEvent(“eventType”[, eventObjectRef]) Returns: Boolean. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ While some objects have methods that emulate physical events (for example, the click() and focus() methods), IE5.5 generalizes the mechanism by letting a script direct any valid event to any object. The fireEvent() method is the vehicle. One required parameter is the event type, formatted as a string. IE event types are coded just like the property names for event handlers (for example, onclick, onmouseover, and so on). A second, optional parameter is a reference to an existing event object. This object can be an event that some user or system action triggers (meaning that the fireEvent() method is in a function invoked by an event handler). The existing event can also be an object created by the IE5.5 document.createEventObject() method. In either case, the purpose of providing an existing event object is to set the properties of the event object that the fireEvent() method creates. The event type is defined by the method’s first parameter, but if you have other proper- ties to set (for example, coordinates or a keyboard key code), then those properties are picked up from the existing object. Here is an example of a sequence that cre- ates a new mousedown event, stuffs some values into its properties, and then fires the event at an element on the page: var newEvent = document.createEventObject() newEvent.clientX = 100 newEvent.clientY = 30 newEvent.cancelBubble = false newEvent.button = 1 document.all.myElement.fireEvent(“onmousedown”, newEvent) Events generated by the fireEvent() method are just like regular IE window. event objects, and they have several important event object properties that the browser presets. Importantly, cancelBubble is set to false and returnValue is set to true — just like a regular user- or system-induced event. This means that if you want to prevent event bubbling and/or prevent the default action of the event’s source element, then the event handler functions must set these event object prop- erties just like normal event handling in IE. The fireEvent() method returns a Boolean value that the returnValue property of the event determines. If the returnValue property is set to false during event handling, then the fireEvent() method returns false. Under normal processing, the method returns true. Although the W3C DOM Level 2 event model includes the dispatchEvent() method to accommodate script-generated events (and Event object methods to create event objects), Microsoft has so far elected to ignore the standard recom- mendation. While there is some similarity between the basic operations of elementObject.fireEvent() 165 Chapter 15 ✦ Generic HTML Element Objects fireEvent() and dispatchEvent(), the two methods diverge significantly in advanced applications (for example, the way events can propagate and the W3C notion of an Event object). Example (with Listing 15-26) on the CD-ROM Related Item: dispatchEvent() method. focus() See blur(). getAdjacentText(“position”) Returns: String. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The getAdjacentText() method enables you to extract plain text components of an element object (in other words, without any HTML tag information). This method is not implemented in IE5/Mac. The sole parameter is one of four case- insensitive string constant values that indicate from where, in relation to the current object, the text should be extracted. The values are: Parameter Value Description beforeBegin Text immediately in front of the element’s tag, back to the preceding tag afterBegin Text that begins inside the element tag, up to the next tag (whether it be a nested element or the element’s end tag) beforeEnd Text immediately in front of the element’s end tag, back to the preceding tag (whether it be a nested element or the element’s start tag) afterEnd Text immediately following the element’s end tag, forward until the next tag If the current object has no nested elements, then the afterBegin and beforeEnd versions both return the same as the object’s innerText property. When the current object is encased immediately within another element (for exam- ple, a TD element inside a TR element), there is no text before the element’s begin- ning or after the element’s end so these values are returned as empty strings. On the CD-ROM elementObject.getAdjacentText() 166 Part III ✦ Document Objects Reference The strings returned from this method are roughly equivalent to values of text fragment nodes in the W3C DOM, but IE5 treats these data pieces only as string data types rather than as text node types. Cross-browser DOM equivalents for the four versions are: document.getElementById(“objName”).previousSibling.nodeValue document.getElementById(“objName”).firstChild.nodeValue document.getElementById(“objName”).lastChild.nodeValue document.getElementById(“objName”).nextSibling.nodeValue Example on the CD-ROM Related Items: childNodes, data, firstChild, lastChild, nextSibling, nodeValue, and previousSibling properties. getAttribute(“attributeName”[, caseSensitivity]) Returns: See text. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The getAttribute() method returns the value assigned to a specific attribute of the current object. You can use this method as an alternative to retrieving prop- erties of an object, particularly when your script presents you with the attribute name as a string (in contrast to a fully formed reference to an object and its property). Thus, the following example statements yield the same data: var mult = document.all.mySelect.multiple var mult = document.all.mySelect.getAttribute(“multiple”) Returned value types from getAttribute() are either strings (including attribute values assigned as unquoted numeric values) or Booleans (for example, the multiple property of a SELECT element object). The W3C DOM Level 2 standard recommends getAttribute() and setAttribute() for reading and writing element object attribute values, rather than reading and writing those values by way of their corresponding properties. While using these methods is certainly advisable for XML elements, the same DOM standard sends conflicting signals by defining all kinds of properties for HTML ele- ment objects. Browsers, of course, will support access via properties well into the future, so don’t feel obligated to change your ways. Note On the CD-ROM elementObject.getAttribute() 167 Chapter 15 ✦ Generic HTML Element Objects All browsers that support the getAttribute() method require one parameter, which is a string of the attribute name. By default, this parameter is not case-sensi- tive. Note that this has impact on custom attributes that you might assign to HTML or XML elements in your documents. Attribute names are automatically converted to lowercase when they are turned into properties of the object. Therefore, you must avoid reusing attribute names, even if you use different case letters in the source code assignments. IE includes an optional extension to the method in the form of a second parame- ter that enables you to be more specific about the case-sensitivity of the first parameter. The default value of the second parameter is false, which means that the first parameter is not case-sensitive. A value of true makes the first parameter case-sensitive. This matters only if you use setAttribute() to add a parameter to an existing object and in the IE version of that method insists on case-sensitivity. The default behavior of setAttribute() respects the case of the attribute name. See also the discussion of the setAttribute() method later in this chapter with regard to setAttribute()’s influence over the IE attributes property. Example on the CD-ROM Related Items: attributes property; document.createAttribute(), setAttribute() methods. getAttributeNode(“attributeName”) Returns: Attribute node object. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ In the W3C DOM, an attribute is an object that inherits all the properties of a Node object (see Chapter 14). As its name implies, an attribute object represents a name–value pair of an attribute that is explicitly defined inside an element’s tag. The ability to treat attributes as node objects is far more important when working with XML than HTML, but it is helpful to understand attribute nodes within the con- text of the W3C DOM object-oriented view of a document. Importantly, attribute nodes specifically are not recognized as nodes of a document hierarchy. Therefore, an attribute node is not a child node of the element that defines the attribute. But the “nodeness” of attributes comes into play when comparing the contents of an object’s attributes property in the IE and W3C DOM worlds. In IE5+, the attributes property returns an array of all attributes for an element (whether or not the attributes are explicitly included in the tag). But the W3C attributes prop- erty builds on the DOM’s formal structure by returning an object known (internally) as a named node map. Like an array, the named node map has a length property (facilitating for loop interation through the map), plus several methods that allow On the CD-ROM elementObject.getAttributeNode() . 158 Part III ✦ Document Objects Reference An unfortunate side effect of button focus in Win32 environments is that the focus highlight (a dotted. For example, NN4 on the Mac does not change the state of a checkbox when clicked remotely. (Win32 versions of version 4 browsers do change state.) If you want to script the action of “clicking”. care of it for you. Example on the CD-ROM On the CD-ROM On the CD-ROM elementObject.click() 160 Part III ✦ Document Objects Reference Related Item: onClick event handler. cloneNode(deepBoolean) Returns: