138 Part III ✦ Document Objects Reference Example (with Listing 15-12) on the CD-ROM Related Items: offsetLeft, offsetTop, offsetHeight, offsetWidth properties. outerHTML outerText Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ One way that Internet Explorer exposes an entire element to scripting is by way of the outerHTML and outerText properties. The primary distinction between these two properties is that outerHTML includes the element’s start and end tags whereas outerText includes only rendered text that belongs to the element (including text from any nested elements). The outerHTML property contains not only the text content for an element as seen on the page, but also every bit of HTML tagging associated with that content. For example, consider the following bit of HTML source code: <P ID=”paragraph1”>”How <EM>are</EM> you?” he asked.</P> The value of the P object’s outerHTML property (document.all.paragraph1. outerHTML ) is exactly the same as that of the source code. The browser interprets any HTML tags in a string that you assign to an element’s outerHTML property. This means that you can delete (set the property to an empty string) or replace an entire tag with this property. The document’s object model adjusts itself to whatever adjustments you make to the HTML in this manner. In contrast, the outerText property knows only about the text content of an ele- ment container. In the preceding example, the value of the paragraph’s outerText property (document.all.paragraph1.innerText) is: “How are you?” he asked. If this looks familiar, it’s because in most cases the innerText and outerText properties of an existing element return the exact same strings. If your audience includes Internet Explorer 4 for the Macintosh, be aware that several elements do not support these properties. In addition, IE5/Mac is downright buggy when you try to assign new content to either property. Be sure to test your page thoroughly on these platform combinations. Also see Chapter 14 for some code to add to a page that simulates the outerHTML property for writing in NN6. Example (with Listing 15-13) on the CD-ROM On the CD-ROM On the CD-ROM elementObject.outerHTML 139 Chapter 15 ✦ Generic HTML Element Objects Related Items: innerHTML, innerText properties; replaceNode() method. ownerDocument Value: document object reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The ownerDocument property belongs to any element or node in the W3C and NN6 DOM. The property’s value is a reference to the document node that ultimately contains the element or node. If a script encounters a reference to an element or node (perhaps it has been passed as a parameter to a function), the object’s ownerDocument property provides a way to build references to other objects in the same document or to access properties and methods of the document objects. IE’s version of this property is simply document. Example on the CD-ROM Related Item: document object. parentElement Value: Element object reference or null Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The parentElement property returns a reference to the next outermost HTML element from the current element. This parent–child relationship of elements is often, but not always, the same as a parent–child node relationship (see parentNode property later in this chapter). The difference is that the parentElement property deals only with HTML elements as reflected as document objects, whereas a node is not necessarily an HTML element (for example, an attribute or text chunk). There is also a distinction between parentElement and offsetParent proper- ties. The latter returns an element that may be many generations removed from a given element but is the immediate parent with regard to positioning context. For example, a TD element’s parentElement property is most likely its enclosing TR element, but (in IE5 at least) a TD element’s offsetParent property is its TABLE element. A script can “walk” the element hierarchy outward from an element with the help of the parentElement property. The top of the parent chain is the HTML element. Its parentElement property returns null. On the CD-ROM elementObject.parentElement 140 Part III ✦ Document Objects Reference Example on the CD-ROM Related Items: offsetParent, parentNode properties. parentNode Value: Node object reference or null Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The parentNode property returns a reference to the next outermost node that is reflected as an object belonging to the document. For a standard element object, the parentNode property is the same as IE’s parentElement because both objects happen to have a direct parent–child node relationship as well as a parent–child element relationship. Other kinds of content, however, can be nodes. This includes text fragments within an element. A text fragment’s parentNode property is the next outermost node or element that encompasses that fragment. A text node object in IE does not have a parentElement property. Example on the CD-ROM Related Items: childNodes, nodeName, nodeType, nodeValue, parentElement properties. parentTextEdit Value: Element object reference or null Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ Only a handful of objects in IE’s object model are capable of creating text ranges (see the TextRange object in Chapter 19). To find an object’s next outermost con- tainer capable of generating a text range, use the parentTextEdit property. If an element is in the hierarchy, that element’s object reference is returned. Otherwise (for example, document.body.parentTextEdit), the value is null. IE5/Mac through version 5 does not implement text ranges or associated properties and methods. On the CD-ROM On the CD-ROM elementObject.parentTextEdit 141 Chapter 15 ✦ Generic HTML Element Objects Example (with Listing 15-14) on the CD-ROM Related Items: isTextEdit property; TextRange object (Chapter 19). previousSibling (See nextSibling) readyState Value: String (integer for OBJECT object) Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ A script can query an element to find out if it has loaded all ancillary data (for example, external image files or other media files) before other statements act on that object or its data. The readyState property lets you know the loading status of an element. Table 15-6 lists the possible values and their meanings. Table 15-6 readyState Property Values HTML Value OBJECT Value Description complete 4 Element and data fully loaded interactive 3 Data may not be loaded fully, but user can interact with element loaded 2 Data is loaded, but object may be starting up loading 1 Data is loading uninitialized 0 Object has not started loading data yet For most HTML elements, this property always returns complete. Most of the other states are used by elements such as IMG, EMBED, and OBJECT, which load external data and even start other processes (such as ActiveX controls) to work. In IE4, the readyState property was limited to the following objects: document, EMBED, IMG, LINK, OBJECT, SCRIPT, and STYLE. For IE5+, this property is available to essentially every element. One word of caution: Do not expect the readyState property to reveal if an object exists yet in the document (for example, uninitialized). If the object does not exist, it cannot have a readyState property — the result is a script error for an On the CD-ROM elementObject.readyState 142 Part III ✦ Document Objects Reference undefined object. If you want to run a script only after every element and its data are fully loaded, trigger the function by way of the onLoad event handler for the BODY element or the onReadyStateChange event handler for the object (and check that the readyState property is complete). Example on the CD-ROM Related Items: onReadyStateChange event handler. recordNumber Value: Integer or null Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ Virtually every object has a recordNumber property, but it applies only to ele- ments used in Internet Explorer (for Windows) data binding to represent repeated data. For example, if you display 30 records from an external data store in a table, the TR element in the table is represented only once in the HTML. However, the browser repeats the table row (and its component cells) to accommodate all 30 rows of data. If you click a row, you can use the recordNumber property of the TR object to see which record was clicked. A common application of this facility is in data binding situations that allow for updating records. For example, script a table so that clicking on an uneditable row of data displays that record’s data in editable text boxes elsewhere on the page. If an object is not bound to a data source, or it is a non-repeating object bound to a data source, the recordNumber property is null. Example (with Listing 15-15) on the CD-ROM Related Items: dataFld, dataSrc properties; TABLE, TR objects (Chapter 27). runtimeStyle Value: style object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ You can determine the browser default settings for style sheet attributes with the help of the runtimeStyle property. The style object that this property On the CD-ROM On the CD-ROM elementObject.runtimeStyle 143 Chapter 15 ✦ Generic HTML Element Objects returns contains all style attributes and the default settings at the time the page loads. This property does not reflect values assigned to elements by style sheets in the document or by scripts. The default values returned by this property differ from the values returned by the currentStyle property. The latter includes data about values that are not assigned explicitly by style sheets, yet are influenced by the default behavior of the browser’s rendering engine. In contrast, the runtimeStyle property shows unassigned style values as empty or zero. To change a style property setting, access it via the element’s style object. Example on the CD-ROM Related Items: currentStyle property; style object (Chapter 30). scopeName Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The scopeName property is associated primarily with XML that is embedded within a document. When you include XML, you can specify one or more XML Namespaces that define the “owner” of a custom tag name, thus aiming toward pre- venting conflicts of identical custom tags from different sources in a document. (See Chapter 33 for more about XML objects.) The XML Namespace is assigned (in IE5+) as an attribute of the <HTML> tag that surrounds the entire document: <HTML XMLNS:Fred=’http://www.someURL.com’> After that, the Namespace value precedes all custom tags linked to that Namespace: <Fred:FIRST_Name ID=”fredFirstName”/> To find out the Namespace “owner” of an element, you can read the scopeName property of that element. For the preceding example, the scopeName returns Fred. For regular HTML elements, the returned value is always HTML. The scopeName property is available only in Win32 and UNIX flavors of IE5. The comparable prop- erty in the W3C DOM is localName. Example on the CD-ROM Related Item: tagUrn property. On the CD-ROM On the CD-ROM elementObject.scopeName 144 Part III ✦ Document Objects Reference scrollHeight scrollWidth Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The scrollHeight and scrollWidth properties contain the pixel measures of an object, regardless of how much of the object is visible on the page. Therefore, if the browser window displays a vertical scrollbar, and the body extends below the bottom of the viewable space in the window, the scrollHeight takes into account the entire height of the body as if you were to scroll downward and see the entire element. For most elements that don’t have their own scrollbars, the scrollHeight and scrollWidth properties have the same values as the clientHeight and clientWidth properties. A few compatibility cautions are necessary, however. While these properties are available for virtually every element in IE5+, they are available for only the BODY, BUTTON, CAPTION, DIV, FIELDSET, LEGEND, MARQUEE, and TEXTAREA objects in IE4 for Windows. Moreover, IE for the Macintosh yields the viewable height and width of the BODY element, rather than its true scrolling height and width. The values are accurate, however, for other content elements. Example on the CD-ROM Related Items: clientHeight , clientWidth properties; window.scroll() method. scrollLeft scrollTop Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ If an element is scrollable (in other words, it has its own scrollbars), you can find out how far the element is scrolled in the horizontal and vertical direction via the scrollLeft and scrollTop properties. These values are pixels. For non-scrollable elements, these values are always zero — even if they are contained by elements that are scrollable. For example, if you scroll a browser window (or frame in a On the CD-ROM elementObject.scrollLeft 145 Chapter 15 ✦ Generic HTML Element Objects multiframe environment) vertically, the scrollTop property of the body object is whatever the pixel distance is between the top of the object (now out of view) and the first visible row of pixels of the element. But the scrollTop value of a table that is in the document remains at zero. These properties are available only to the BODY, BUTTON, CAPTION, DIV, FIELD- SET, LEGEND, MARQUEE, SPAN, and TEXTAREA objects in IE4. For IE5+, the proper- ties are available to virtually every element. NN treats scrolling of a BODY element from the point of view of the window. If you want to find out the scrolled offset of the current page in NN4+, use window. scrollX and window.scrollY. Example on the CD-ROM Related Items: clientLeft, clientTop properties; window.scroll() method. sourceIndex Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The sourceIndex property returns the numeric index (zero-based) of the object within the document.all collection. This property is useful if a script needs to access an adjacent object on a page. For example, the following function receives an object reference as a parameter and returns a reference to the object that is next in the source code object order: function getNextObject(obj) { return document.all[(obj.sourceIndex + 1)] } Or if you know only the ID of an object and want to retrieve a reference to the next object in source code order, you can use the following version: function getNextObject(objName) { var index = document.all[objName].sourceIndex return document.all[(index + 1)] } Example on the CD-ROM Related Item: item() method. On the CD-ROM On the CD-ROM elementObject.sourceIndex 146 Part III ✦ Document Objects Reference style Value: style object reference Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The style property is the gateway to an element’s style sheet settings. The property’s value is a style object whose properties enable you to read and write the style sheet settings for the element. While scripts do not usually manipulate the style object as a whole, it is quite common in a Dynamic HTML page for scripts to get or set multiple properties of the style object to effect animation, visibility, and all appearance parameters of the element. Changing properties of the style object may affect the layout of the page. For example, setting the font size of an element to a larger value forces the paragraph to reflow to accommodate the enlarged text. This page reflow is available in IE4+ and NN6. Because NN4 cannot reflow content, severe limitations are placed on changing content after the page loads. You can find significant differences in the breadth of properties of the style object in IE compared with NN. See Chapter 30 for more details on the style object. Example on the CD-ROM Related Items: currentStyle, runtimeStyle properties; style object (Chapter 30). tabIndex Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The tabIndex property controls where in the tabbing sequence the current object receives focus. This property obviously applies only to elements that can receive focus. IE5+ permits giving focus to more elements than IE4 or NN6; but for all browsers compatible with this property, the primary elements for which you may want to control focus (namely form input elements) are covered. IE4/Mac does not give focus to elements other than those that accept text input. The default value of the tabIndex property is 0 (although it is -1 in NN6). A value of 0 (or -1 in NN6) means that elements receive focus in the normal tabbing order on the page, following source code order from the first focusable element. In general, On the CD-ROM elementObject.tabIndex 147 Chapter 15 ✦ Generic HTML Element Objects the browsers treat form elements as focusable elements by default. Nonform ele- ments usually don’t receive focus unless you specifically set their tabIndex proper- ties (or TABINDEX tag attributes). If you set the tabIndex property of one form element to 1, then that element is first in the tabbing order. Meanwhile, the rest fall into source code tabbing order on successive presses of the Tab key. If you set two elements to, say, 1, then the tabbing proceeds in source code order for those two elements and then onto the rest of the elements in source code order starting with the top of the page. In Internet Explorer, you can remove an element from tabbing order entirely by setting its tabIndex property to -1. Users can still click those elements to make changes to form element settings, but tabbing bypasses the element. Example (with Listing 15-16) on the CD-ROM Related Items: blur(), focus() methods. tagName Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The tagName property returns a string of the HTML or (in IE5+ and NN6) XML tag name belonging to the object. All tagName values are returned in all uppercase characters, even if the source code is written in all lowercase or a mixture. This consistency makes it easier to perform string comparisons. For example, you can create a generic function that contains a switch statement to execute actions for some tags and not others. The skeleton of such a function looks like the following: function processObj(objRef) { switch (objRef.tagName) { case “TR”: [statements to deal with table row object] break case “TD”: [statements to deal with table cell object] break case “COLGROUP”: [statements to deal with column group object] break default: [statements to deal with all other object types] } } On the CD-ROM elementObject.tagName . compared with NN. See Chapter 30 for more details on the style object. Example on the CD-ROM Related Items: currentStyle, runtimeStyle properties; style object (Chapter 30) . tabIndex Value: Integer. element. Its parentElement property returns null. On the CD-ROM elementObject.parentElement 140 Part III ✦ Document Objects Reference Example on the CD-ROM Related Items: offsetParent, parentNode. readyState property — the result is a script error for an On the CD-ROM elementObject.readyState 142 Part III ✦ Document Objects Reference undefined object. If you want to run a script only after every