DOM Level 2 Traversal and Range modules define an interface called Range which is used to select a section of document structure regardless of node boundaries. This section can be used to read the document's content as well as to manipulate the DOM's structure. The DOM Range can thus be used to select specific parts of the document object; for instance:
The bolded section in the above HTML code snippet can be a range. Once range is created and the positions are set, variety of manipulations are possible of the underlying DOM tree.
Creating a Range
DOM Range object is created in a DOM-compliant browser using createRange() method of the document object. Thus created range is related to the current document object and cannot be used in other documents.
Syntax for createRange()
var curRange = document.createRange();
DOM Range selection
Following methods of the Range object provide a simple way to select a range.
The selectNode(node) method selects the entire node including its children of the given node.
The selectNodeContents(node) method selects only the nodes children.
Example with Range selection methods
Properties of Range interface
The startContainer property selects the node within which the Range begins. In the above example startContainer value for both selectNode() and selectNodeContents() methods are <body> and <p> tags respectively.
The endContainer property selects node within which the Range ends. In the above example endContainer value for both selectNode() and selectNodeContents() methods are </body> and </p> tags respectively.
The startOffset property selects the offset within the starting node of the Range. The offset is the index of the first child node in the Range.
The endOffset property selects the offset within the ending node of the Range. When selectNode() is used to select a Range, endOffset is always startOffset+1, as there is only one node selected between the selected node tags. When selectNodeContents() is used, endOffset is startOffset + number of nodes till the ending node, as all the children are selected.
In the below example endOffset is 3 because it has three nodes inside the <p> tag.
<p id="message"><b>My message</b><br><b>Message content</b></p>
Example of selectNodeContents method
Example of selectNode method
Other Methods for Range selection
The setStartBefore(node) method makes the Range starting from the node given. As the starting point of the range will be set just before the node given by this function.
The setStartAfter(node) method makes the Range starting after the given node. The starting point of the range will be set after the given node. Next sibling of the parent node will be the first node in the selection.
The setEndBefore(node) method sets the ending point of the Range before the given node, so that the range ends with previous sibling of the given node.
The setEndAfter(node) method makes the Range ending after the given node. The given node thus becomes the last node of the collection.
The example below shows an HTML Range with the nodes after selectNodeContents:
<b>One</b><div id="break"></div><b>Two</b><div id="testDiv"></div>
node 1: <b>One</b>
node 2: <div id="break"></div>
node 3: <b>Two</b>
node 4: <div id="testDiv"></div>
Example of Range interface startBefore() and startAfter() methods
The setStart(startNode, startOffset) method sets the start position of a Range specified by starting point through a start node and start offset from the start of start node.
- startNode: where the range should start
- startOffset: For Text, Comment, startOffset is the number if characters from the start of startNode and for HTML nodes, startOffset is number of child nodes after the start node.
The setEnd(endNode, endOffset) method sets the end position of a Range specified by end node and end offset.
- endNode: the node where Range should end
- endOffset: the offset for the end of Range from the start of end node. For Text, Comments, endOffset is the number of characters from the start of endNode and for HTML nodes, it is the number of child nodes from the endNode.
In the following example we are trying to make part of the text displayed as bold.
Example of Range interface setStart() and setEnd() methods
The deleteContents() method simply deletes the content of the given range from the document.
The extractContents() method deletes the content of the given range from the document and also returns the deleted range data which can be used elsewhere.
The cloneContents() method just returns the range data to be used elsewhere, but does not delete in the original document as done by extractContent().
The insertNode(nodeToInsert) method inserts a node at the start boundary point of the Range.
The CompareBoundaryPoints() method compares the current range with range given as parameter based on the method specified.
This method can be:
- Range.START_TO_START: Compares start boundary point of first range to start boundary point of second range
- Range.END_TO_END: Compares end boundary-point of the first range with end boundary point of second range
- Range.START_TO_END: Compares start boundary point of first range with end boundary point of second range
- Range.END_TO_START: Compares the end boundary point of the first range with end boundary point of second range
When done using a Range, the detach() method can be called on the range to safely cleanup after usage. Once detach is called the range can be no longer be approached and used.