Section IV.10. Working with Text Ranges

IV.10. Working with Text Ranges

The content modification discussions earlier concerned themselves with elements and nodes as part of the document tree structure. Another kind of objectgenerically called a text rangelets scripts transcend the element and node structure of a document by manipulating only the text that a user sees. A text range acts like an invisible selection in a document. Such a selection may start or end anywhere within the document, and not necessarily where text node or element boundaries exist.

Text ranges are implemented very differently between the IE and W3C DOMs (and the W3C DOM version is implemented starting with Mozilla 0.9, Safari 1.3/2.0, and Opera 8). Although the syntaxes and points of view of the two DOMs have little in common, the fundamental sequence of working with a text range is the same in both:

1. Create a text range object (saving a reference to it in a variable).

2. Set the start and end points of the range through text range object methods.

Once the range has the boundaries you desire, your scripts can invoke numerous methods on the range to manipulate its contents. For example, a text range's start and end points can be in the same location of a document (called a collapsed state), which means that the range is acting as an insertion point, where a text range object method can insert some script-generated content. Or the boundaries can be some distance apart (perhaps created as a result of a user physically selecting body text on the page), thus allowing that text to be removed or transformed in some way under script control.

IV.10.1. Browser Support

Despite the similarity in concept, the IE TexTRange object and the W3C Range object might as well be from different planets. The IE Textrange object was first implemented in IE 4 for Windows (it was never implemented in IE for the Mac). You will find that the IE TexTRange is a robust implementation with many features that point to practical application in web pages (enhanced even more with event model extensions for IE/Windows). IE text ranges work on body, button, input, and textarea element content.

In contrast, the W3C Range object specifications are only partially complete in DOM Level 2, with perhaps more details to come in the future. Unfortunately, due to some valuable features missing from the W3C DOM Level 2 version (the ability to search within a range, highlighting text within a range under script control, and treating text segments as words or sentences, to name a few), the W3C versions implemented in even modern W3C DOM-compatible browsers are comparatively underpowered and may not be suitable for the ideas you'll get from the IE feature set.

If you intend to explore both text range infrastructures, be aware of the contrasting philosophies behind the two systems. In the IE world, most of the range specifications and manipulation methods deal with characters, words, and sentencesthe real content you can see on the page. But the W3C version continues with the node-centricity exhibited throughout the DOM, whereby specifying boundary positions relies on text node references and offsets within those nodes. To insert content into a collapsed text range requires the rangeRef.pasteHTML("HTMLText") method in IE (operating like the innerHTML property elsewhere in the IE DOM) and the rangeRef.insertNode(nodeRef) method in the W3C version.

IV.10.2. Typical Text Range Operations

In this section, I'm going to show you the syntax in both DOMs for carrying out basic operations with text ranges. These operations scarcely scratch the surface of what text ranges are for, but they provide you with the fundamentals in both systems to experiment to your heart's delight.

Creating a collapsed text range at the start of the body element

IE 4 and later:

 var rangeRef = document.body.createTextRange( ); rangeRef.collapse(true); 

W3C DOM syntax:

 var rangeRef = document.createRange( ); rangeRef.selectNode(document.body); rangeRef.collapse(true); 

Setting an existing range's boundaries to encompass an element's text

IE 4 and later:

 rangeRef.moveToElementText(document.getElementById("myElem")); 

W3C DOM syntax:

 rangeRef.selectNodeContents(document.getElementById("myElem")); 

Reading an existing range's text content

IE 4 and later:

 var rangeText = rangeRef.text; 

W3C DOM syntax:

 var rangeText = rangeRef.toString( ); 

Removing a range's content from a document tree

IE 4 and later:

 rangeRef.pasteHTML(""); 

W3C DOM syntax:

 rangeRef.deleteContents( ); 

Inserting a new element and text into a collapsed range

IE 4 and later:

 rangeRef.pasteHTML("<em id='inserted'>New emphasized text.</em>"); 

W3C DOM syntax:

 var newText = document.createTextNode("New emphasized text."); var newElem = document.createElement("em"); newElem.setAttribute("id", "inserted"); newElem.appendChild(newText); rangeRef.insertNode(newElem); 

Turning a user selection into a text range

IE 4 and later:

 var rangeRef = document.selection.createRange( ); 

W3C DOM syntax (Mozilla only):

 var rangeRef = window.getSelection( ).getRangeAt(0);