The Range Object

The Internet Explorer's TextRange object is a fairly popular one, and the W3C has been working to generalize that object into the Range objectwhich the Internet Explorer does not (yet) implement. Range objects are more general than text rangesthey can contain ranges of HTML from a Web page, including elements and text. Using this object gives you a way to cut up documents in other ways besides using W3C node trees, which some programmers find hard to work with.

To some extent, the Range object has been implemented in Netscape Navigator 6. You can see the properties and methods of this object in that browser in Table 11.19 in overview, and in Tables11.20 and 11.21 in depth.

Table 11.19. Overview of the Properties and Methods of the Range Object

Properties	Methods
`collapsed`	`cloneRange`
`commonAncestorContainer`	`collapse`
`endContainer`	`compareBoundaryPoints`
`endOffset`	`createContextualFragment`
`startContainer`	`deleteContents`
`startOffset`	`detach`
	`insertNode`
	`isValidFragment`
	`selectNode`
	`selectNodeContents`
	`setEnd`
	`setEndAfter`
	`setEndBefore`
	`setStart`
	`setStartAfter`
	`setStartBefore`
	`toString`

Table 11.20. The Properties of the Range Object

Property	NS2	NS6
`collapsed`		x
	Read-only
	This is a Boolean value that, if true, indicates the start and end of the range are at the same point, which means the range is "collapsed." If false, the range is not collapsed.
`commonAncestorContainer`		x
	Read-only
	Holds a reference to the document tree node that the start and end of the range have in common.
`endContainer`		x
	Read-only
	Holds a reference to the document tree node that contains the end of the range.
`endOffset`		x
	Read-only
	Holds the number of characters or nodes between the end of a range and its containing node.
`startContainer`		x
	Read-only
	Holds a reference to the document tree node that contains the start of the range.
`startOffset`		x
	Holds the number of characters or nodes between the start of a range and its containing node.

Table 11.21. The Methods of the Range Object

Method	NS2	NS6
`cloneRange`		x
	Returns: `Range` object
	Clones a range and returns a new copy of it.
	Syntax: `Range` `.cloneContents()` . Netscape has also announced a `cloneContents` method, but it's not yet supported in Netscape Navigator 6.
`collapse`		x
	Returns: Nothing
	Collapses a range down to a single insertion point.
	Syntax: `Range.collapse(` `start` `)` . The `start` parameter is true (the default) if you want the collapsed range to correspond to the beginning of the range, false if you want it to correspond to the end of the range.
`compareBoundaryPoints`		x
	Returns: Integer
	Compares the start and end positions of two ranges.
	Syntax: `Range` `.compareBoundaryPoints(` `type` `,` `range` `)` , where `type` can be `Range` . `START` _ `TO` _ `END` (compares the start of the `Range` object with the end of the `range` parameter), `Range` . `START` _ `TO` _ `START` (compares the start of the `Range` object with the start of the `range` parameter), `Range` . `END` _ `TO` _ `START` (compares the end of the `Range` object with the start of the `range` parameter), `Range` . `START` _ `TO` _ `END` (compares the end of the `Range` object with the end of the `range` parameter). The `range` parameter holds the range to compare the current one to. Returns `-1` if the comparison point in the `Range` object is farther to the left than the comparison point in `range` , if the comparison point in the `Range` object is at the same location as the comparison point in `range` , and `1` if the comparison point in the `Range` object is farther to the right than the comparison point in `range` .
`createContextualFragment`		x
	Returns: Document fragment
	This method creates an HTML string that you can insert into a node tree, avoiding the need to use `createElement` , `createTextNode` , and so on.
	Syntax: `Range` `.createContextualFragment(` `text` `)` , where `text` is the new HTML string.
`deleteContents`		x
	Returns: Nothing
	Deletes the contents of a range from the document tree.
	Syntax: `Range.deleteContents()` .
`detach`		x
	Returns: Nothing
	Eliminates a `Range` object from the current document. There's no need to do this, unless you want to save resources. When you detach a `Range` object, it's gone.
	Syntax: `Range.detach()` .
`insertNode`		x
	Returns: Nothing
	This method is the one you use to insert a node at the start of a range. Unfortunately, its implementation in Netscape Navigator 6.0 doesn't work.
	Syntax: `Range` `.insertNode(` `node` `)` , where `node` is the node to insert, such as a text of element node.
`isValidFragment`		x
	Returns: Boolean
	Indicates whether specific text can be converted to a valid document fragment node using the `createContextFragment` method.
	Syntax: `Range` `.isValidFragment(` `text` `)` . Returns true if so, false otherwise .
`selectNode`		x
	Returns: Nothing
	This method enables you to surround a node with a `Range` .
	Syntax: `Range` `.selectNode(` `node` `)` , where `node` is the node to select. You can surround element or text nodes with this method. If you surround an element node, the start and end of the new range is the next outer element; if you surround a text node, the start and end of the new range is the parent element of the text node.
`selectNodeContents`		x
	Returns: Nothing
	This method enables you to surround a node's contents with a `Range` .
	Syntax: `Range` `.selectNodeContents(` `node` `)` , where `node` is the node to select. You can surround element or text nodes with this method. If you surround an element node, the start and end of the new range is the same element node you pass to this method; if you surround a text node, the start and end of the new range is the text node itself, and the range is collapsed at the beginning of the text.
`setEnd`		x
	Returns: Nothing
	This method enables you to set the end of a range.
	Syntax: `Range` `.setEnd(` `node` `,` `offset` `)` , where `node` is a reference node you're setting the end with respect to, and `offset` is the offset of the new end of the range. If `node` is an element node, `offset` is measured in child elements; if `node` is a text node, `offset` is measured in characters.
`setEndAfter`		x
	Returns: Nothing
	Enables you to set the end of a range after an existing node.
	Syntax: `Range` `.setEndAfter(` `node` `)` , where `node` is a node you're setting your position with respect to.
`setEndBefore`		x
	Returns: Nothing
	Enables you to set the end of a range before an existing node.
	Syntax: `Range` `.setEndBefore(` `node` `)` , where `node` is a node you're setting your position with respect to.
`setStart`		x
	Returns: Nothing
	This method enables you to set the start of a range.
	Syntax: `Range` `.setStart(` `node` `,` `offset` `)` , where `node` is a reference node you're setting the start with respect to, and `offset` is the offset of the new start of the range. If `node` is an element node, `offset` is measured in child elements; if `node` is a text node, `offset` is measured in characters.
`setStartAfter`		x
	Returns: Nothing
	Enables you to set the start of a range after an existing node.
	Syntax: `Range` `.setStartAfter(` `node` `)` , where `node` is a node you're setting your position with respect to.
`setStartBefore`		x
	Returns: Nothing
	Enables you to set the start of a range before an existing node.
	Syntax: `Range` `.setEndBefore(` `node` `)` , where `node` is a node you're setting your position with respect to.
`toString`		x
	Returns: String
	Returns the text in the body of a range as a string.
	Syntax: `Range` `.` `toString()` .