Text, TextNodeNN 6 IE 5 DOM 1  

  

A Text object is what this book calls in many places a "text node." Microsoft refers to this object as a TextNode object. This object represents the child object containing the characters that go between start and end tags of an element. The Text object exists in the abstract W3C DOM model by virtue of an inheritance chain between it and the fundamental Node object (Node to CharacterData to Text). The Node object ancestry automatically equips the Text object with a long list of properties and methods described among the shared items at the start of this chapter (the properties include: attributes, childNodes, firstChild, lastChild, localName, namespaceURI, nextSibling, nodeName, nodeType, nodeValue, ownerDocument, parentNode, prefix, previousSibling; the methods are: appendChild( ), cloneNode( ), hasAttributes( ), hasChildNodes( ), insertBefore( ), isSupported( ), normalize( ), removeChild( ), replaceChild( )). Along this inheritance chain, the Text object gains some additional properties and methods (described below) that let us manipulate the node's content within the constructs dictated by the formal W3C DOM model. Because the DOM is scripting language-independent, you find properties and methods that may be more easily or more powerfully manipulated through JavaScript string handling (see Chapter 12). Feel free to use those techniques in a client-side JavaScript environment of the browser.

 

Scripts refer to the Text node (or IE TextNode object) only through references that locate the node in the document tree (such as the first child of a particular element node) or as returned by the document.createTextNode( ) method.

 
Object Model Reference
 
elementReference.childReference
textNodeReference.siblingReference
 
Object-Specific Properties
 
datalength
 
Object-Specific Methods
 
appendData( )deleteData( )insertData( )replaceData( )
splitText( )substringData( )
 
Object-Specific Event Handler Properties

None.

accessKeyNN n/a IE 4 DOM 1  

Read/Write  

This is single character key that either gives focus to an element (in some browsers) or activates a form control or link action. The browser and operating system determine if the user must press a modifier key (e.g., Ctrl, Alt, or Command) with the access key to activate the link. In Windows versions of IE 5 and later and Netscape 6, the Alt key is required and the key is not case-sensitive. For Macintosh versions of IE 5 and later and Netscape 6, the Ctrl modifier key is required to effect the action.

 

Although listed here as a widely shared property, that isn't strictly the case across all implementations. Netscape 6 (per the W3C DOM) recognizes this property only for the following elements: a, area, button, input, label, legend, and textarea. To this list, IE 4 adds applet, body, div, embed, isindex, marquee, object, select, span, table, and td (but removes label and legend). IE 5 adds every other renderable element, but with a caution. Except for input and other form-related elements, you must also assign a tabindex attribute or tabIndex property value to the IE 5 and later element (even if it's simply a value of zero for all) to let the accelerator key combination bring focus to the element. As of Version 7, Netscape does not alter UI behavior if a script changes the property's value.

 
Example
 
document.links[3].accessKey = "n";
 
Value

Single alphanumeric (and punctuation) keyboard character.

 
Default

Empty string.

blur( )NN 2 IE 3 DOM 1  

Removes focus from the current object, at which time the object's onblur event fires. Note that the range of elements capable of focus and blur (both the event and method) is limited in all browsers except for more recent versions of IE (see the shared tabindex attribute in Chapter 8). Most reliably for backward compatibility, apply the blur( ) method to blatantly focusable elements, such as text input and textarea elements. Assigning the attribute onfocus="this.blur( );" to a text input element, for instance, is a crude but effective backward-compatible way to largely disable a field for browsers that do not provide genuine element disabling.

 

Use blur( ) and focus( ) methods in moderation on the same page. You can inadvertently trigger endless loops of blurring and focusing if alert dialog boxes are involved along the way. Moreover, be aware that when you invoke the blur( ) method on one object, some other object (perhaps the window object) receives an onfocus event.

 
Parameters

None.

 
Returned Value

None.

dataNN 6 IE 5 DOM 1  

Read/Write  

Contains the string of characters in the text node. The value is the same as the nodeValue property value, and there is no reason to favor one property over the other, except perhaps for plain-language syntactic preferences for reading the code.

 
Example
 
document.getElementById("myP").firstSibling.data = "Some new text.";
 
Value

String.

 
Default

Empty string.

disabledNN 6 IE 4 DOM 1  

Read/Write  

Specifies whether the element is available for user interaction. When set to true, the element cannot receive focus or be modified by the user, and it typically appears grayed out on the page. This property is available for all HTML element objects in IE 5.5 for Windows and later. For IE 4 and IE 5, it applies only to form controls, while Netscape 6 and later recognize the property for form controls and the style element object. A disabled form control's name/value pair is not submitted with its form.

 
Example
 
document.getElementById("myButton").disabled = true;
 
Value

Boolean value: true | false.

 
Default

false

focus( )NN 2 IE 3 DOM 1

Gives focus from the current object, at which time the object's onfocus event fires. Note that the range of elements capable of focus and blur (both the event and method) is limited in all browsers except for more recent versions of IE (see the shared tabindex attribute in Chapter 8). Most reliably for backward compatibility, apply the focus( ) method to blatantly focusable elements, such as text input and textarea elements.

 

To give a text box focus and pre-select all the text in the box, use the sequence of focus( ) and select( ) methods on the element. If this sequence is to occur after windows change (such as after an alert dialog box closes), place the methods in a separate function, and invoke this function through the setTimeout( ) method following the alert( ) method for the dialog. This allows IE/Windows to sequence statement execution correctly.

 
Parameters

None.

 
Returned Value

None.

lengthNN 6 IE 5 DOM 1  

Read-only  

Provides a count of characters in the text node.

 
Example
 
var howMany = document.getElementById("myP").firstSibling.length;
 
Value

Integer.

 
Default

0

appendData( )NN 6 IE 5(Mac)/6(Win) DOM 1  

appendData("newText")

  

Adds characters (passed as a string parameter) to the end of the current text node. The content consists of raw characters, so if you intend to add a sentence to a text node, your scripts are responsible for sentence spacing.

 
Parameters
 
  • String value of text to be appended. A reference that evaluates to a string (such as the data property of another text node in the document) copies the referenced value to the append location.
 
Returned Value

None.

deleteData( )NN 6 IE 5(Mac)/6(Win) DOM 1  

deleteData(startOffset, count)

  

Removes characters from the current text node starting with the character in (zero-based) position signified by startOffset, and for a length of count characters in the normal text direction of the current language. If the length specified for deletion goes beyond the length of the data, all characters to the end of the text node are deleted without throwing an exception. Note that Netscape 6 includes source code white space in its counts for both parameters.

 
Parameters
 
  • Positive integer specifying the zero-based starting character point for the deletion.
  • Positive integer specifying the number of characters to be deleted.
 
Returned Value

None.

insertData( )NN 6 IE 5(Mac)/6(Win) DOM 1  

insertData(startOffset, "newText")

  

Inserts text into a zero-based character position in the text node.

 
Parameters
 
  • Positive integer specifying the zero-based character before which the new text is to be inserted.
  • String value of text to be inserted. A reference that evaluates to a string (such as the data property of another text node in the document) copies the referenced value to the append location.
 
Returned Value

None.

recordNumberNN n/a IE 4 DOM n/a  

Read-only  

Used with IE data binding, returns an integer representing the record within the data set that generated the element (i.e., an element whose content is filled via data binding). Values of this property can be used to extract a specific record from an Active Data Objects (ADO) record set (see recordset property). Although this property is defined for all IE element objects, the other properties related to data binding belong to a subset of elements.

 
Example
 
<script for="tableTemplate" event="onclick">
		    myDataCollection.recordset.absoluteposition = this.recordNumber;
		    ...
		</script>
 
Value

Integer.

 
Default

null

replaceData( )NN 6 IE 5(Mac)/6(Win) DOM 1  

replaceData(startOffset, count, "newText")

  

Replaces text in the current text node with new text. The original content to be removed is signified by the zero-based start position and the number of characters. The string passed as a third parameter goes into the space vacated by the removed text. A bug in IE 5 for Macintosh crops the new text to the length of the removed text.

 
Parameters
 
  • Positive integer specifying the zero-based starting character point for the deletion.
  • Positive integer specifying the number of characters to be deleted.
  • String value of text to be inserted where the remaining text collapses. A reference that evaluates to a string (such as the data property of another text node in the document) copies the referenced value to the append location.
 
Returned Value

None.

splitText( )NN 6 IE 5(Mac)/6(Win) DOM 1  

splitText(offset)

  

Divides the current text node into two sibling text nodes; otherwise, doesn't disturb the text.

 
Parameters
 
  • Positive integer specifying the zero-based character point before which the split occurs.
 
Returned Value

Reference to the second text node.

substringData( )NN 6 IE 5(Mac)/6(Win) DOM 1  

substringData(startOffset, count)

  

Returns a copy of the designated segment of the text node content. The section to be copied is signified by the zero-based start position and the number of characters

 
Parameters
 
  • Positive integer specifying the zero-based starting character point for the copy action.
  • Positive integer specifying the number of characters to be copied.
 
Returned Value

String.

tabIndexNN 6 IE 4 DOM 1  

Read/Write  

This is a number that indicates the sequence of this element within the tabbing order of all focusable elements in the document. Tabbing order follows a strict set of rules. Elements that have values other than zero assigned to their tabIndex properties are first in line when a user starts tabbing in a page. Focus starts with the element with the lowest tabIndex value and proceeds in order to the highest value, regardless of physical location on the page or in the document. If two elements have the same tabIndex values, the element that comes earlier in the document receives focus first. Next come all elements that either don't support the tabIndex property or have the value set to zero. These elements receive focus in the order in which they appear in the document.

 

The W3C DOM and Netscape 6 limit the tabIndex property to the following element objects: a, area, button, input, object, select, textarea. To this list, IE 4 adds applet, body, div, embed, isindex, marquee, span, table, and td. IE 5 adds every other renderable element. A negative value in IE (only) removes an element from tabbing order entirely.

 

Links and anchors cannot be tabbed to with the Mac version of IE 4, so the tabIndex property for a element objects is ignored in that version.

 
Example
 
document.getElementById("link3").tabIndex = 6;
 
Value

Integer.

 
Default

0