Range | NN 6 IE n/a DOM 2
The W3C DOM Range objectsimilar in concept to the IE TextRange objectrepresents a sequence of zero or more rendered text characters in a document. When a text range consists of zero characters, it represents an insertion point between two characters (or before the first or after the last character of the document). The Range object automatically keeps track of the node and character offset references for the start and end points of the range, so its methods can copy existing content, delete the range's contents, or insert new contents (in node form) into the existing range while maintaining the integrity of the document tree at every step. Nodeness is important to the Range object, but most of those concerns are handled for you.
A Range object is created via the document.createTextRange( ) method or by turning a user selection into a range via window.getSelection( ).getRangeAt(0). Once a text range is created, use its methods to adjust its start and end point to encompass a desired segment of the text. The choose from a set of additional methods to act on the range. See Chapter 5 for details and examples of using the Range object and how its syntax varies from that of the IE TextRange object.
Object Model Reference
    document.createRange( )
Object-Specific Properties
collapsed | commonAncestorContainer | endContainer
endOffset | startContainer | startOffset
Object-Specific Methods
cloneContents( ) | cloneRange( ) | collapse( )
compareBoundaryPoints( ) | compareNode( ) | comparePoint( )
createContextualFragment( ) | deleteContents( ) | detach( )
extractContents( ) | insertNode( ) | intersectsNode( )
isPointInRange( ) | selectNode( ) | selectNodeContents( )
setEnd( ) | setEndAfter( ) | setEndBefore( )
setStart( ) | setStartAfter( ) | setStartBefore( )
surroundContents( ) | toString( ) |
Object-Specific Event Handler Properties
None.

collapsed | NN 6 IE n/a DOM 2
| Read-only
Returns Boolean true if the range's start and end points are at the same location, encompassing zero characters. A collapsed range can be located anywhere within the document.
Example
    if (rng.collapsed) {
        // act on collapsed text range
    }
Value
Boolean value: true | false.
Default
None.

commonAncestorContainer | NN 6 IE n/a DOM 2
| Read-only
Returns a reference to a document tree node that is the next outermost container that encompasses the current range's start and end points. If the start and end points are, themselves, in the same node (for example, the same text node), the commonAncestorContainer property returns a reference to that node's parent node. IE TextRange equivalent is parentElement( ).
Example
    var containingElem = rng.commonAncestorContainer;
Value
Reference to a node object (commonly an element node type).
Default
None.

endContainer | NN 6 IE n/a DOM 2
| Read-only
Returns a reference to a document tree node that contains the current range's end point.
Example
    var containingElemRight = rng.endContainer;
Value
Reference to a node object.
Default
None.

endOffset | NN 6 IE n/a DOM 2
| Read-only
Returns an integer count of characters or nodes for the end point's location within the node reported by the endContainer property. If the endContainer is a text node, the endOffset property counts the number of characters to the right of the first character of that text node. If the endContainer is an element node, the endOffset property counts the number of nodes between the start of the containing node's content and the end point.
As an example, consider the following document segment that shows a text range in boldface characters, with the start and end points signified by pipe characters:
Note that the start point is within a text node, while the end point sits just outside the span element end tag. The Range object's properties report values as shown in the following table.
Property | Value | Description
--- | --- | ---
commonAncestorContainer | [object HTMLParagraphElement] | The p element embraces both the start and end points.
startContainer | [object Text] | Start point is within a text node.
startOffset | 19 | Start point is at the 20th (zero-based index of 19) character from the start of its container, the text node.
endContainer | [object HTMLParagraphElement] | End point is designated as the end of the span element, which makes the next outer p element the end point's container.
endOffset | 2 | End point is at the 3rd (zero-based index of 2) node in the context of its endContainer p element (first node is a text node; second node is the span element; end point is at the start of the third node of the p element).
Example
    var rngEndOff = rng.endOffset;
Value
Integer.
Default
None.

startContainer | NN 6 IE n/a DOM 2
| Read-only
Returns a reference to a document tree node that contains the current range's start point.
Example
    var containingElemLeft = rng.startContainer;
Value
Reference to a node object.
Default
None.

startOffset | NN 6 IE n/a DOM 2
| Read-only
Returns an integer count of characters or nodes for the start point's location within the node reported by the startContainer property. If the startContainer is a text node, the startOffset property counts the number of characters to the right of the first character of that text node. If the startContainer is an element node, the startOffset property counts the number of nodes between the start of the containing node's content and the start point. See endOffset for more details.
Example
    var rngStartOff = rng.startOffset;
Value
Integer.
Default
None.

cloneContents( ) | NN 7 IE n/a DOM 2
Returns a DocumentFragment node containing a copy of the contents from the current range. Any dangling nodes are resolved as part of the cloning process.
Parameters
None.
Returned Value
Reference to a node of a document fragment type.

cloneRange( ) | NN 6 IE n/a DOM 2
Returns a Range object that is a carbon copy of the current range, including references to associated containers. This method lets you preserve a copy of a Range object's specifications while creating a new Range object. Similar to the IE TextRange object's duplicate( ) method.
Parameters
None.
Returned Value
Reference to a Range object.

collapse( ) | NN 6 IE n/a DOM 2
collapse(toStartFlag) |
Shrinks the current range to an insertion point (start and end points are in the same node at the same offset). The Boolean parameter controls whether the range collapses to the start point (true) or end point (false) of the current range. A script working its way through a document (e.g., using the String.indexOf( ) method to search for the next instance of a string) usually collapses to the end point before shifting the end point to the end of the body to perform the next String.indexOf( ) search.
Parameters
Boolean value that controls whether collapse occurs at the start point (true) or end point (false) of the current range.
Returned Value
None.

compareBoundaryPoints( ) | NN 6 IE n/a DOM 2
compareBoundaryPoints(compareType, sourceRangeRef) |
Returns an integer code indicating the relative positioning of one boundary point of the current range's against a boundary point of a different text range. In the simplest case, the two end points (one from each range) share the same ancestor container. In such a case, the first parameter determines which end points from the two ranges get compared. Use the constants supplied with every Range object, as shown in the following table.
If the first boundary in the comparison occurs earlier in the document than the second boundary, the returned value is -1; if the first boundary comes after the second boundary, the returned value is 1; if the two boundaries are in the identical position, the returned value is 0. Similar to the IE TextRange object's compareEndPoints( ) method.
But the situation can be more complex if the boundary points being compared have different ancestor container nodes. The offset values with respect to container nodes influence the comparison results. Due to the variety of results that can occur with numerous relationships between the compared end points, your scripts will need to perform an intricate analysis of boundaries to assure comparisons report the desired sequence. On the other hand, simply looking for unanimity of boundary points is a much simpler prospect. You may prefer to limit your comparisons to looking only for return values of zero (or any other value) for a more binary determination of boundary comparisons.
Comparison type | Description
--- | ---
rng.START_TO_START | Comparing the start position of the current range against the start position of the source range
rng.START_TO_END | Comparing the start position of the current range against the end position of the source range
rng.END_TO_END | Comparing the end position of the current range against the end position of the source range
rng.END_TO_START | Comparing the end poisition of the current range against the start position of the source range
Parameters
Integer values from 0 to 3 corresponding to comparison types. Integer values are not aligned with the W3C DOM standard in Netscape 6 or 7, but the plain-language constants (such as rng.START_TO_START, shown in the table above) produce the correct comparisons. Reference to a second, previously defined Range object, perhaps preserved through the cloneRange( ) method.
Returned Value
Integer values -1, 0, or 1.

compareNode( ) | NN 6 IE n/a DOM n/a
compareNode(nodeReference) |
A Netscape-only method that returns an integer code indicating the relative position of some other node with respect to the current range. Four plain-language constants are members of every Netscape Range object, and can be used for comparisons of values returned by the compareNode( ) method. Note that the returned values are from the point of view of the node passed as a parameter, rather than from that of the current range.
Returned values and constants are as follows.
By way of example:
Constant | Value | Description
--- | --- | ---
rng.NODE_BEFORE | 0 | Entire node comes before the range.
rng.NODE_AFTER | 1 | Entire node comes after the range.
rng.NODE_BEFORE_AND_AFTER | 2 | Node starts before the current range and ends after it.
rng.NODE_INSIDE | 3 | Node is contained in its entirety within the scope of the range.
Parameters
Reference to any node in the document tree.
Returned Value
Integer values 0, 1, 2, or 3.

comparePoint( ) | NN 6 IE n/a DOM n/a
compareNode(nodeReference, offset) |
A Netscape-only method that returns an integer code indicating the relative position of some other node and offset within that node with respect to the current range. Note that the returned values are from the point of view of the node (more specifically, the point signified by the offset within the node) passed as parameters, rather than from that of the current range.
Returned values are as follows.
By way of example:
Value | Description
--- | ---
-1 | Point comes before the start of the range.
0 | Point is located within the range.
1 | Point comes after the end of the range.
Parameters
Reference to any node in the document tree. Integer offset, counting either nested nodes within an element or characters within a text node.
Returned Value
Integer values -1, 0, 1.

createContextualFragment( ) | NN 6 IE n/a DOM n/a
createContextualFragment(contentString) |
The createContextualFragment( ) method was initially designed as an alternative to the innerHTML convenience property (because the W3C DOM provides little in the way of support for content strings consisting of tags). This method accepts any stringincluding tagged contentas a parameter, and returns a DocumentFragment type of node, ready for appending or inserting into the document tree. Subsequent adoption of the innerHTML property by the Mozilla browser makes this method redundant, except that it is more consistent with the overall nodeness of the W3C DOM.
Parameters
Document content in string form, including tags and attributes.
Returned Value
Reference to a document fragment type of node outside of the document tree. This node can then be applied to the document tree.

deleteContents( ) | NN 6 IE n/a DOM 2
Removes the contents of the current text range from the document tree. If the range is an element node (e.g., with boundaries established via the selectNode( ) method), invoking deleteContents( ) on the range removes the node from the document tree and collapses the range. The Range object remains in memory, but without any content. If you want to capture the content prior to its deletion, do so with other Range object methods (such as cloneRange( ) and, when it works correctly, cloneContents( )).
Parameters
None.
Returned Value
None.

detach( ) | NN 6 IE n/a DOM 2
Destroys the current Range object to the extent that invoking most methods on the object or accessing its properties throw a RangeException of type INVALID_STATE_ERR.
Parameters
None.
Returned Value
None.

extractContents( ) | NN 6 IE n/a DOM 2
Returns a DocumentFragment node containing the contents of the current range, after removing the contents from the document tree. Not working in Netscape as of Version 6.2 except when the range boundaries are set via the selectNodeContents( ) method.
Parameters
None.
Returned Value
Reference to a node of a document fragment type.

insertNode( ) | NN 6 IE n/a DOM 2
insertNode(nodeReference) |
Inserts a node at the start of the current text range. Most useful when the range is already collapsed as a text insertion pointer. The node being inserted can be created fresh (via document.createElement( )) or fetched from elsewhere in the document tree, in which case it is removed from its old position and inserted into the current range. If you insert a text node adjacent to a spot that also happens to be an existing text node, you can wind up with two adjacent text nodes. Invoke the normalize( ) method on the parent to consolidate the text nodes.
Parameters
Reference to any text, element, or document fragment node to be inserted into the range.
Returned Value
Nothing

intersectsNode( ) | NN 6 IE n/a DOM n/a
intersectsNode(nodeReference) |
Returns Boolean true if any part of the current range overlaps with the text or element node that is passed as a parameter. If your script detects an intersection, it can use the compareNode( ) method to obtain more detail about the intersection.
Parameters
Reference to any text or element in the document tree.
Returned Value
Boolean value: true | false.

isPointInRange( ) | NN 6 IE n/a DOM n/a
isPointInRange(nodeReference, offset) |
Returns Boolean true if the location denoted by the parameter values (a node in the document tree and an offset location within that node) is within the current range.
Parameters
Reference to any text or element in the document tree. Integer offset, counting either nested nodes within an element or characters within a text node.
Returned Value
Boolean value: true | false.

selectNode( ), selectNodeContents( ) | NN 6 IE n/a DOM 2
selectNode(nodeReference) selectNodeContents(nodeReference) |
Sets the range's boundary points to encompass a node or just the node's contents. Despite the methods' names, no body text in the rendered document is highlighted.
Your choice of method impacts the way the range's startContainer and endContainer properties are filled. In the following sequence, you see what happens to the range and its properties when an element node and a text node are parameters to these methods. The initial HTML segment is:
Selecting the span element (with the rng.selectNode(document.getElementById("myspan")) method) sets the range to:
The Range object's properties report values as follows.
Using the rng.selectNodeContents(document.getElementById("myspan")) method to select the span element's contents sets the range to:
The Range object's properties report values as follows.
Using the rng.selectNode(document.getElementById("myspan").firstChild) method to select the text node inside the span element sets the range to:
Even though the node passed as a parameter is different (and a different node type), the new range selection looks the same as the previous one. In fact, due to the way the node tree is structured, the Range object's properties report identical values as follows.
Using the rng.selectNodeContents(document.getElementById("myspan")) method to select the contents of the text node inside the span element sets the range to:
In other words, the range collapses to an insertion point at the start of the text node (this may be a bug in Netscape 6), and the text node becomes the container, as shown in the following property enumeration.
Element nodes tend to be the most practical parameter values to pass to either method.
Property | Value | Description
--- | --- | ---
startContainer | [object HTMLParagraphElement] | Start point is right before the span element.
startOffset | 1 | Start point is at the 2nd (zero-based index of 1) node inside the p element.
endContainer | [object HTMLParagraphElement] | End point is immediately after the span element.
endOffset | 2 | End point is at the 3rd (zero-based index of 2) node in the context of its endContainer p element.
Property | Value | Description
--- | --- | ---
startContainer | [object HTMLSpanElement] | Start point is just inside the span element.
startOffset | 0 | Start point is at the 1st (zero-based index of 0) node inside the span element.
endContainer | [object HTMLSpanElement] | End point is immediately after the span element's content.
endOffset | 1 | End point is at a position where the 2nd (zero-based index of 1) node, if present, would be in the context of its endContainer span element.
Property | Value | Description
--- | --- | ---
startContainer | [object HTMLSpanElement] | Start point is just inside the span element.
startOffset | 0 | Start point is at the 1st (zero-based index of 0) node inside the span element.
endContainer | [object HTMLSpanElement] | End point is immediately after the span element's content.
endOffset | 1 | End point is at a position where the 2nd (zero-based index of 1) node, if present, would be in the context of its endContainer span element.
Property | Value | Description
--- | --- | ---
startContainer | [object Text] | Start point is at the beginning of the text node.
startOffset | 0 | Start point is at the 1st (zero-based index of 0) position of the text node.
endContainer | [object Text] | End point is collapsed.
endOffset | 0 | End point is collapsed.
Parameters
Reference to any text or element in the document tree.
Returned Value
None.

setEnd( ), setStart( ) | NN 6 IE n/a DOM 2
setEnd(nodeReference, offset) setStart(nodeReference, offset) |
Establish the document tree locations for the individual boundary points of an existing Range object. Similar to the IE TextRange object's setEndPoint( ) method. The mapping of a location relies upon a node reference and an offset value relative to that node's starting point and type. Offset values count child nodes when the nodeReference is an element node; they count characters when the nodeReference is a text node. To set a boundary at a node edge, the associated methods (setEndAfter( ) and three others) are more convenient.
Parameters
Reference to any element or text node in the document tree. Integer offset, counting either nested nodes within an element or characters within a text node.
Returned Value
None.

setEndAfter( ), setEndBefore( ), setStartAfter( ), setStartBefore( ) | NN 6 IE n/a DOM 2
setEndAfter(nodeReference) setEndBefore(nodeReference) setStartAfter(nodeReference) setStartBefore(nodeReference) |
Establish the document tree locations for the individual boundary points of an existing Range object with respect to a node's edges. These methods assume that you are interested in setting a range's boundaries to places immediately before or after an existing node, and not concerned with other kinds of offsets. Range boundaries do not have to be symmetrical, allowing you to specify the start boundary relative to one node and the end boundary relative to a completely different node later in the document.
Parameters
Reference to any element or text node in the document tree.
Returned Value
None.

surroundContents( ) | NN 7 IE n/a DOM 2
surroundContents(parentNodeReference) |
Encapsulates the current range with a new container, usually a new element node created via the document.createElement( ) method. End points of the current range should have the same parent container prior to applying this method.
Parameters
Reference to a node that becomes the new containing parent for the range.
Returned Value
None.

toString( ) | NN 6 IE n/a DOM 2
Returns a string of the body content contained by the range. No tags or attributes accompany the returned value.
Parameters
None.
Returned Value
String.