8. Document Object Model Range

8.1. Introduction

A Range identifies a range of content in a Document, DocumentFragment or Attr. It is contiguous in the sense that it can be characterized as selecting all of the content between a pair of end-points. Note: In a text editor or a word processor, a user can make a selection by pressing down the mouse at one point in a document, moving the mouse to another point, and releasing the mouse. The resulting selection is contiguous and consists of the content between the two points.
The term 'selecting' does not mean that every Range corresponds to a selection made by a GUI user; however, such a selection can be returned to a DOM user as a Range.

The Range interface provides methods for accessing and manipulating the document tree at a higher level than similar methods in the Node interface. The expectation is that each of the methods provided by the Range interface for the insertion, deletion and copying of content can be directly mapped to a series of Node editing operations enabled by DOM Core. In this sense, the Range operations can be viewed as convenience methods that also enable the implementation to optimize common editing patterns.

This chapter describes the Range interface, including methods for creating and moving a Range and methods for manipulating content with Ranges.

8.2. Definitions and Notation

8.2.1. Position

This chapter refers to two different representations of a document: the text or source form that includes the document markup and the tree representation similar to the one described in the Introduction.

A Range consists of two end-points corresponding to the start and the end of the Range. An end-point's position in a document or document fragment tree can be characterized by a node and an offset. The node is called the container of the end-point and of its position. The container and its ancestors are the ancestor containers of the end-point and of its position. The offset within the node is called the offset of the end-point and its position. If the container is an Attribute, Document, Document Fragment, Element or EntityReference node, the offset is within its child nodes list. If the container is a CharacterData, Comment or ProcessingInstruction node, the offset is within the 16-bit units contained by it.

The end-points of a Range must have a common ancestor container which is either a Document, DocumentFragment or Attr node. That is, the content of a Range must be entirely within the subtree rooted by a single Document, DocumentFragment or Attr Node. This common ancestor container is known as the root container of the Range. The tree rooted by the root container is known as the Range's context tree.

The container of an end-point of a Range must be an Element, Comment, ProcessingInstruction, EntityReference, CDATASection, Document, DocumentFragment, Attr, or Text node. None of the ancestor containers of the end-point of a Range can be a DocumentType, Entity or Notation node.

In terms of the text representation of a document, the end-points of a Range can only be on token boundaries. That is, the end-point of the text range cannot be in the middle of a start- or end-tag of an element or within the name of an entity or character reference. A Range locates a contiguous portion of the content of the structure model.

The relationship between locations in a text representation of the document and in the Node tree interface of the DOM is illustrated in the following diagram:

---

---

Range Example

---

In this diagram, four different Ranges are illustrated. The end-points of each range are labelled with s# (the start of the range) and e# (the end of the range), where # is the number of the Range. For Range 2, the start is in the BODY element and is immediately after the H1 element and immediately before the P element, so its position is between the H1 and P children of BODY. The offset of an end-point whose container is not a Text node is 0 if it is before the first child, 1 if between the first and second child, and so on. So, for the start of the Range 2, the container is BODY and the offset is 1. The offset of an end-point whose container is a Text node is obtained similarly but using 16-bit unit positions instead. For example, the end-point labelled s1 of the Range 1 has a Text node (the one containing "Title") as its container and an offset of 2 since it is between the second and third 16-bit unit.

Notice that the end-points of Ranges 3 and 4 correspond to the same location in the text representation. An important feature of the Range is that an end-point of a Range can unambiguously represent every position within the document tree.

The containers and offsets of the end-points can be obtained through the following read-only Range attributes:

  readonly attribute Node startContainer; 
  readonly attribute long startOffset;
  readonly attribute Node endContainer; 
  readonly attribute long endOffset;

If the end-points of a Range have the same containers and offsets, the Range is said to be a collapsed Range. (This is often referred to as an insertion point in a user agent.)

    <FOO>ABC<BAR>DEF</BAR></FOO>
                  

    <FOO>A^BC<BAR>DEF</BAR></FOO>

    <FOO>A*BC<BAR>DEF</BAR></FOO>

8.3. Creating a Range

A range is created by calling the createRange() method on the DocumentRange interface. This interface can be obtained from the object implementing the Document interface using binding-specific casting methods.

  interface DocumentRange {
    Range createRange();
  }

The initial state of the range returned from this method is such that both of its end-points are positioned at the beginning of the corresponding Document, before any content. In other words, the container of each end-point is the Document node and the offset within that node is 0.

Like some objects created using methods in the Document interface (such as Nodes and DocumentFragments), Ranges created via a particular document instance can select only content associated with that Document, or with DocumentFragments and Attrs for which that Document is the ownerDocument. Such Ranges, then, can not be used with other Document instances.

8.4. Changing a Range's Position

A Range's position can be specified by setting the container and offset of each end-point with the setStart and setEnd methods.

  void setStart(in Node parent, in long offset)
                        raises(RangeException);
  void setEnd(in Node parent, in long offset)
                raises(RangeException);

If one end-point of a Range is set to have a root container other than the current one for the range, the range is collapsed to the new position. This enforces the restriction that both end-points of a Range must have the same root container.

The start position of a Range is guaranteed to never be after the end position. To enforce this restriction, if the start is set to be at a position after the end, the range is collapsed to that position. Similarly, if the end is set to be at a position before the start, the range is collapsed to that position.

It is also possible to set a Range's position relative to nodes in the tree:

  void setStartBefore(in Node node);
                              raises(RangeException);
  void setStartAfter(in Node node);
                       raises(RangeException);
  void setEndBefore(in Node node);
                      raises(RangeException);
  void setEndAfter(in Node node);
                     raises(RangeException);

The parent of the node becomes the container of the end-point and the Range is subject to the same restrictions as given above in the description of setStart() and setEnd().

A Range can be collapsed to either end-point:

  void collapse(in boolean toStart);

Passing TRUE as the parameter toStart will collapse the Range to its start , FALSE to its end.

Testing whether a Range is collapsed can be done by examining the isCollapsed attribute:

  readonly attribute boolean isCollapsed;

The following methods can be used to make a range select the contents of a node or the node itself.

  void selectNode(in Node n);
  void selectNodeContents(in Node n);

The following examples demonstrate the operation of the methods selectNode and selectNodeContents:

Before:
  ^<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
After range.selectNodeContents(FOO):
  <BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
After range.selectNode(FOO):

<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>

8.5. Comparing Range End-Points

It is possible to compare two Ranges by comparing their end-points:

  int compareEndPoints(in CompareHow how, in Range sourceRange) raises(RangeException);

where CompareHow is one of four values: StartToStart, StartToEnd, EndToEnd and EndToStart. The return value is -1, 0 or 1 depending on whether the corresponding end-point of the Range is before, equal to, or after the corresponding end-point of sourceRange. An exception is thrown if the two Ranges have different root containers.

The result of comparing two end-points (or positions) is specified below. An informal but not always correct specification is that an end-point is before, equal to, or after another if it corresponds to a location in a text representation before, equal to, or after the other's corresponding location.

Let A and B be two end-points or positions. Then one of the following holds: A is before B, A is equal to B, or A is after B. Which one holds is specified in the following by examining four cases:

In the first case the end-points have the same container. A is before B if its offset is less than the offset of B, A is equal to B if its offset is equal to the offset of B, and A if after B if its offset is greater than the offset of B.

In the second case a child C of the container of A is an ancestor container of B. In this case, A is before B if the offset of A is less than or equal to the index of the child C and A is after B otherwise.

In the third case a child C of the container of B is an ancestor container of A. In this case, A is before B if the index of the child C is less than the offset of B and A is after B otherwise.

In the fourth case, none of three other cases hold: the containers of A and B are siblings or descendants of sibling nodes. In this case, A is before B if the container of A is before the container of B in a pre-order traversal of the Ranges' context tree and A is after B otherwise.

Note that because the same location in a text representation of the document can correspond to two different positions in the DOM tree, it is possible for two end-points to not compare equal even though they would be equal in the text representation. For this reason, the informal definition above can sometimes be incorrect.

8.6. Deleting Content with a Range

One can delete the contents selected by a Range with:

  void deleteContents();

deleteContents() deletes all nodes and characters selected by the Range. All other nodes and characters remain in the context tree of the Range. Some examples of this deletion operation are:

(1) <FOO>AB<MOO>CD</MOO>CD</FOO>  -->
<FOO>A^CD</FOO>

(2) <FOO>A<MOO>BC</MOO>DE</FOO>  -->
<FOO>A<MOO>B</MOO>^E</FOO>

(3) <FOO>XY<BAR>ZW</BAR>Q</FOO>  -->
<FOO>X^<BAR>W</BAR>Q</FOO>

(4)
<FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO>
-->  <FOO><BAR1>A</BAR1>^<BAR3>D</BAR3>

After deleteContents() is invoked on a Range, the Range is collapsed. If no node was partially selected by the Range, then it is collapsed to its original start point, as in example (1). If a node was partially selected by the Range and was an ancestor container of the start of the Range and no ancestor of the node satisfies these two conditions, then the Range is collapsed to the position immediately after the node, as in examples (2) and (4). If a node waspartially selected by the Range and was an ancestor container of the end of the Range and no ancestor of the node satisfies these two conditions, then the Range is collapsed to the position immediately before the node, as in examples (3) and (4).

8.7. Extracting Content

If the contents of a range need to be extracted rather than deleted, the following method may be used:

  DocumentFragment extractContents();

The extractContents() method removes nodes from the Range's context tree similarly to the deleteContents() method. In addition, it places the deleted contents in a new DocumentFragment. The following examples illustrate the contents of the returned document fragment:

(1) <FOO>AB<MOO>CD</MOO>CD</FOO>  -->
B<MOO>CD</MOO>

(2) <FOO>A<MOO>BC</MOO>DE</FOO>  -->
<MOO>C<MOO>D

(3) <FOO>XY<BAR>ZW</BAR>Q</FOO>  -->
Y<BAR>Z</BAR>

(4)
<FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO>
-->  <BAR1>B</BAR1><BAR2/><BAR3>C</BAR3>

It is important to note that nodes that are partially selected by the range are cloned. Since part of such a node's contents must remain in the Range's context tree and part of the contents must be moved to the new fragment, a clone of the partially selected node is included in the new fragment. Note that cloning does not take place for selected elements; these nodes are moved to the new fragment.

8.8. Cloning Content

The contents of a range may be duplicated using the following method:

  DocumentFragment cloneContents();

This method returns a DocumentFragment that is similar to the one returned by the method extractContents(). However, in this case, the original nodes and character data in the Range are not removed from the Range's context tree. Instead, all of the nodes and text content within the returned DocumentFragment are cloned.

8.9. Inserting Content

A node may be inserted into a range using the following method:

  void insertNode(in Node n) raises(RangeException);

The insertNode() method inserts the specified node into the Range's context tree. For this method, the end of the range is ignored and the node is inserted at the start of the range.

The Node passed into this method can be a DocumentFragment. In that case, the contents of the fragment are inserted at the start position of the range, but the fragment itself is not. Note that if the Node represents the root of a sub-tree, the entire sub-tree is inserted.

The same rules that apply to the insertBefore() method on the Node interface apply here. Specifically, the Node passed in, if it is already has a parent, will be removed from its existing position.

8.10. Surrounding Content

The insertion of a single node to subsume the content selected by a Range can be performed with:

  void surroundContents(in Node n);

The surroundContents() method causes all of the content selected by the range to be rooted by the specified node. Calling surroundContents() with the node FOO in the following examples yields:

     Before:
       <BAR>AB<MOO>C</MOO>DE</BAR>
     After surroundContents(FOO):

<BAR>A<FOO>B<MOO>C</MOO>D</FOO>E</BAR>

Another way of of describing the effect of this method on the Range's context tree is to decompose it in terms of other operations:

1. Remove the contents selected by the range with a call to extractContents().
2. Insert node where the range is now collapsed (after the extraction) with insertNode()
3. Insert the entire contents of the extracted fragment into node. Specifically, invoke the appendChild() on node passing in the DocumentFragment returned as a result of the call to extractContents()
4. Select node and all of its contents with selectNode().

The surroundContents() method raises an exception if the range partially selects a non-Text node. An example of a range for which surroundContents() raises an exception is:

     <FOO>AB<BAR>CD</BAR>E</FOO>

If node has any children, those children are removed before its insertion. Also, if node already has a parent, it is removed from the original parent's childNodes list.

8.11. Miscellaneous Members

One can clone a Range:

  Range cloneRange();

This creates a new Range which selects exactly the same content as that selected by the Range on which the method cloneRange was invoked. No content is affected by this operation.

Because the end-points of a range do not necessarily have the same containers, use:

  readonly attribute Node commonAncestorContainer;

to get the ancestor container of both end-points that is furthest down from the Range's root container

One can get a copy of all the character data selected or partially selected by a range with:

  DOMString toString();

This does nothing more than simply concatenate all the character data selected by the range. This includes character data in both Text and CDATASection nodes.

8.12. Range modification under document mutation

As a document is modified, the Ranges within the document need to be updated. For example, if one end-point of a Range is within a node and that node is removed from the document, then the Range would be invalid unless it is fixed up in some way. This section describes how Ranges are modified under document mutations so that they remain valid.

There are two general principles which apply to Ranges under document mutation: The first is that all Ranges in a document will remain valid after any mutation operation and the second is that, as much as possible, all Ranges will select the same portion of the document after any mutation operation.

Any mutation of the document tree which affect Ranges can be considered to be a combination of basic delete and insertion operations. In fact, it can be convenient to think of those operations as being accomplished using the deleteContents() and insertNode() Range methods.

<P>Abcd efgh XY blah ijkl</P>

1. Before the 'X':

<P>Abcd efgh inserted textXY blah ijkl</P>

2. After the 'X':

<P>Abcd efgh Xinserted textY blah ijkl</P>

3. After the 'Y':

<P>Abcd efgh XYinserted text blah ijkl</P>

4. After the 'h' in "Y blah":

<P>Abcd efgh XY blahinserted text ijkl</P>

<P>Abcd efgh The Range
ijkl</P>

<P>Abcd Range ijkl</P>

<p>Abcd efgh The Range ijkl</p>

<p>Abcd ^kl</p>

<P>ABCD efgh The
<EM>Range</EM> ijkl</P>

<P>ABCD <EM>ange</EM> ijkl</P>

<P>Abcd efgh The Range ijkl</P>

<P>Abcd he Range ijkl</P>

<P>Abcd <EM>efgh The Range
ij</EM>kl</P>

<P>Abcd ^kl</P>

8.13. Formal Description of the Range Interface

To summarize, the complete, formal description of the Range interface is given below:

Interface Range (introduced in DOM Level 2)

IDL Definition

// Introduced in DOM Level 2:
interface Range {
  readonly attribute Node             startContainer;
  readonly attribute long             startOffset;
  readonly attribute Node             endContainer;
  readonly attribute long             endOffset;
  readonly attribute boolean          isCollapsed;
  readonly attribute Node             commonAncestorContainer;
  void               setStart(in Node refNode, 
                              in long offset)
                                        raises(RangeException);
  void               setEnd(in Node refNode, 
                            in long offset)
                                        raises(RangeException);
  void               setStartBefore(in Node refNode)
                                        raises(RangeException);
  void               setStartAfter(in Node refNode)
                                        raises(RangeException);
  void               setEndBefore(in Node refNode)
                                        raises(RangeException);
  void               setEndAfter(in Node refNode)
                                        raises(RangeException);
  void               collapse(in boolean toStart);
  void               selectNode(in Node refNode)
                                        raises(RangeException);
  void               selectNodeContents(in Node refNode)
                                        raises(RangeException);

  typedef enum CompareHow_ {
    StartToStart,
    StartToEnd,
    EndToEnd,
    EndToStart
  } CompareHow;
  short              compareEndPoints(in CompareHow how, 
                                      in Range sourceRange)
                                        raises(DOMException);
  void               deleteContents()
                                        raises(DOMException);
  DocumentFragment   extractContents()
                                        raises(DOMException);
  DocumentFragment   cloneContents()
                                        raises(DOMException);
  void               insertNode(in Node newNode)
                                        raises(DOMException, 
                                               RangeException);
  void               surroundContents(in Node newParent)
                                        raises(DOMException, 
                                               RangeException);
  Range              cloneRange();
  DOMString          toString();
};

Attributes

startContainer of type Node, readonly

Node within which the range begins

startOffset of type long, readonly

Offset within the starting node of the range.

endContainer of type Node, readonly

Node within which the range ends

endOffset of type long, readonly

Offset within the ending node of the range.

isCollapsed of type boolean, readonly

TRUE if the range is collapsed

commonAncestorContainer of type Node, readonly

The common ancestor container of the range's two end-points.

Type Definition CompareHow

Enumeration CompareHow_

Enumerator Values

StartToStart
StartToEnd
EndToEnd
EndToStart

Methods

setStart

Sets the attributes describing the start of the range.

Parameters

Node		refNode		The refNode value. This parameter must be different from null.
long		offset		The startOffset value.

Exceptions

RangeException

NULL_NODE_ERR: Raised if refNode is null. INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Attr, Entity, Notation, or DocumentType node. If an offset is out-of-bounds, should it just be fixed up or should an exception be raised.

No Return Value

setEnd

Sets the attributes describing the end of a range.

Parameters

Node		refNode		The refNode value. This parameter must be different from null.
long		offset		The endOffset value.

Exceptions

RangeException

NULL_NODE_ERR: Raised if refNode is null. INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Attr, Entity, Notation, or DocumentType node.

No Return Value

setStartBefore

Sets the start position to be before a node

Parameters

Node

refNode

Range starts before refNode

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode is an Attr, Entity, Notation, or DocumentType node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

No Return Value

setStartAfter

Sets the start position to be after a node

Parameters

Node

refNode

Range starts after refNode

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode is an Attr, Entity, Notation, or DocumentType node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

No Return Value

setEndBefore

Sets the end position to be before a node.

Parameters

Node

refNode

Range ends before refNode

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode is an Attr, Entity, Notation, or DocumentType node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

No Return Value

setEndAfter

Sets the end of a range to be after a node

Parameters

Node

refNode

Range ends after refNode.

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode is an Attr, Entity, Notation or DocumentType node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

No Return Value

collapse

Collapse a range onto one of its end-points

Parameters

boolean

toStart

If TRUE, collapses the Range onto its start; if FALSE, collapses it onto its end.

No Return Value

No Exceptions

selectNode

Select a node and its contents

Parameters

Node

refNode

The node to select.

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode is an Attr, Entity, Notation or DocumentType node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

No Return Value

selectNodeContents

Select the contents within a node

Parameters

Node

refNode

Node to select from

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Attr, Entity, Notation or DocumentType node.

No Return Value

compareEndPoints

Compare the end-points of two ranges in a document.

Parameters

CompareHow		how
Range		sourceRange

Return Value

short

-1, 0 or 1 depending on whether the corresponding end-point of the Range is before, equal to, or after the corresponding end-point of sourceRange.

Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same document or document fragment.

deleteContents

Removes the contents of a range from the containing document or document fragment without returning a reference to the removed content.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the range is read-only or any of the nodes that contain any of the content of the range are read-only.

No Parameters

No Return Value

extractContents

Moves the contents of a range from the containing document or document fragment to a new DocumentFragment.

Return Value

DocumentFragment

A DocumentFragment containing the extracted contents.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the range is read-only or any of the nodes which contain any of the content of the range are read-only. HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment.

No Parameters

cloneContents

Duplicates the contents of a range

Return Value

DocumentFragment

A DocumentFragment containing contents equivalent to those of this range.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment.

No Parameters

insertNode

Inserts a node into the document or document fragment at the start of the range.

Parameters

Node

newNode

The node to insert at the start of the range

Exceptions

DOMException		NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the start of the range is read-only. WRONG_DOCUMENT_ERR: Raised if newNode and the container of the start of the Range were not created from the same document. HIERARCHY_REQUEST_ERR: Raised if the container of the start of the Range is of a type that does not allow children of the type of newNode or if newNode is an ancestor of the container.
RangeException		INVALID_NODE_TYPE_ERR: Raised if node is an Attr, Entity, Notation, DocumentFragment, or Document node.

No Return Value

surroundContents

Reparents the contents of the range to the given node and inserts the node at the position of the start of the range.

Parameters

Node

newParent

The node to surround the contents with.

Exceptions

DOMException		NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of either end-point of the range is read-only. WRONG_DOCUMENT_ERR: Raised if newParent and the container of the start of the Range were not created from the same document. HIERARCHY_REQUEST_ERR: Raised if the container of the start of the Range is of a type that does not allow children of the type of newParent or if newParent is an ancestor of the container or if node would end up with a child node of a type not allowed by the type of node.
RangeException		BAD_ENDPOINTS_ERR: Raised if the range partially selects a non-text node. INVALID_NODE_TYPE_ERR: Raised if node is an Attr, Entity, DocumentType, Notation, Document, or DocumentFragment node.

No Return Value

cloneRange

Produces a new range whose end-points are equal to the end-points of the range.

Return Value

Range

The duplicated range.

No Parameters

No Exceptions

toString

Returns the contents of a range as a string.

Return Value

DOMString

The contents of the range.

No Parameters

No Exceptions

Interface DocumentRange (introduced in DOM Level 2)

IDL Definition

// Introduced in DOM Level 2:
interface DocumentRange {
  Range              createRange();
};

Methods

createRange

This interface can be obtained from the object implementing the Document interface using binding-specific casting methods.

Return Value

Range

The initial state of the range returned from this method is such that both of its end-points are positioned at the beginning of the corresponding Document, before any content. The range returned can only be used to select content associated with this Document, or with DocumentFragments and Attrs for which this Document is the ownerDocument.

No Parameters

No Exceptions

Exception RangeException introduced in DOM Level 2

The Range object needs additional exception codes to those in DOM Level 1. These codes will need to be consolidated with other exception codes added to DOM Level 2.

IDL Definition

// Introduced in DOM Level 2:
exception RangeException {
  unsigned short   code;
};

// RangeExceptionCode
const unsigned short      BAD_ENDPOINTS_ERR              = 201;
const unsigned short      INVALID_NODE_TYPE_ERR          = 202;
const unsigned short      NULL_NODE_ERR                  = 203;

Definition group RangeExceptionCode

An integer indicating the type of error generated.

Defined Constants

BAD_ENDPOINTS_ERR	If the end-points of a range do not meet specific requirements.
INVALID_NODE_TYPE_ERR	If the container of an end-point of a range is being set to either a node of an invalid type or a node with an ancestor of an invalid type.
NULL_NODE_ERR	If the container of an end-point of a range is being set to null.