Up to now, you've seen how to modify a document directly by manipulating the individual elements or the style sheets. Just as global style sheets manipulate a document's style independent of its structure, the TextRange object manipulates the document's contents independent of both style and structure. This object is intended to complement the inner and outer element properties for manipulating document contents introduced in Chapter 13, "Dynamic Contents." These element properties offer more robust results and should generally be used instead of the TextRange object whenever possible.
The TextRange object provides access to the text as a long buffer of characters. For example, consider the text in this simple document:
<HTML> <BODY> <H1>Welcome</H1> <H2>Table of Contents</H2> <UL> <LI>Chapter 1</LI> <LI>Chapter 2</LI> </UL> </BODY> </HTML>
Figure 14-1 shows the text for this document, positioned below the parsing tree. Characters belonging to a particular element in the tree are shown under that element's influence. For example, Chapter 1 is influenced by the first LI element.
TextRange objects can be created only by special elements that are considered text edit owners. A text edit owner is an element that can create a TextRange object using the createTextRange method, thereby providing access to the underlying buffer. Currently only two types of HTML elements can act as text edit owners in Dynamic HTML: the Body element is the text edit owner for all the rendered contents and the input elements, such as Input, Button, and TextArea, are text edit owners for their contents. For example, you can create a TextRange object for the preceding document by calling the body object's createTextRange method:
var tr = document.body.createTextRange();
Once a TextRange object is created, any of the contents within the object can be freely accessed.
Figure 14-1. Relationship between the TextRange object and the document structure.
Initially, all the text influenced by the text edit owner is spanned by the TextRange object. For example, the TextRange object in the preceding document spans all the text in the Body element. You can use a TextRange object's methods to reposition it to span different text. A TextRange object spans the text that is being manipulated or changed. A script can replace the spanned text just as a user can select old text and type in replacement text in a word processor. The section "Executing Commands" later in this chapter introduces methods for manipulating the appearance of the document that are similar to a user selecting a font or changing the style of text in a rich text editor.
The TextRange object is designed to be robust enough to automatically accept arbitrary HTML embedded in the document. When new text is inserted into a TextRange object, the HTML is also inserted into the document, just as if the user had chosen Paste from an Edit menu and inserted arbitrary text. These operations are powerful, but they are not intended to provide the developer with precise control over the document. Instead, the developer can use these operations to modify the document on a high level without being concerned about the specific HTML code that implements the modifications. The rules governing the HTML code that these operations generate are likely to change for the next release of Microsoft Internet Explorer. Therefore, the TextRange object should not be used when the result of an operation requires the HTML to have a particular shape. Instead, the inner and outer properties should be used.
A TextRange object does not specify the text that it spans in terms of the ordinal indexes of the text range's start and end characters. Rather, it specifies the spanned text in a way that is more loosely bound to positions in the document and can survive state changes to the document. For example, if the TextRange object spans the entire contents of the document and the contents expand or shrink through another process, the TextRange object automatically reflects this change and continues to span the entire contents.
The TextRange object currently is very closely tied to characters, which causes ambiguities between the TextRange object and the document structure. In many cases in HTML, a single character position cannot accurately represent how the character is influenced by the HTML, as shown here:
<P>This is <B><I>bold and italic</I> text.</B></P>
In the TextRange object, these contents are represented as This is bold and italic text. The parent of the letter b in the text buffer is the Italic element, and the parent of the Italic element is the Bold element. No character in the word bold or the preceding space has the Bold element as its immediate parent. Using the TextRange object, you cannot insert boldface but not italic text before the word bold. The TextRange object is currently based on a single insertion point that can exist either before the letter b (which makes the text boldface and italic) or in the space following the word is (which makes the text neither boldface nor italic). The TextRange object cannot insert text between the <B> and <I> tags. To insert text between the <B> and <I> tags, use the insertAdjacentText and insertAdjacentHTML methods, introduced in Chapter 13, "Dynamic Contents." These methods can insert text before or after any begin or end tag in the document's body.