This article describes using the DOM 2 Range with JavaScript and describes its support in mozilla. I put this together rather quickly and it isn’t very robust, but it is better than nothing. Send bugs and comments to mail[@]dylans.org (without the brackets)<\/p>\n
A Range selects all content between a pair of boundary points, and the Range interface provides methods for accessing and manipulating the document tree at a higher level than similar methods in the Node interface. Each of the methods in the Range interface maps directly to a series of DOM Core Methods, so the Range interface is actually just a set of convenience methods to make such manipulations tolerable.<\/p>\n
Currently, all of the examples here will only work in Mozilla-based browsers, as it is not supported in IE 5, 5.5, or 6.0.<\/p>\n
Examples<\/a><\/p>\n This Core DOM method returns a boolean for whether the feature is supported or not.<\/p>\n document.implementation.hasFeature(“Range”,”2.0″);<\/p>\n Method: Supported in Mozilla<\/p>\n This creates a Range with offset 0 and container is the Document node.<\/p>\n Example: A Range is defined by the position of its two boundary points, the start and end of a range. The position in a Document or DocumentFragment tree is represented by a node and an offset. The boundary points must have a common ancestor container which is either a Document, DocumentFragment, or Attr node. This common ancestor is the root container of the Range, and contains the Range’s context tree.<\/p>\n The boundary point contains a reference to a node, and the offset, which is different for nodes which inherit from the Character Data interface (Text, Comment and CDATASection nodes) and those which do not. For the Character Data interface inheriting nodes, the offset is the 16-bit unit position. For example, an offset of four for a text node that has standard English text would mean that the selection was after the fourth letter. For the other node types, the offset is an integer that describes where it is in the childNodes hierarchy. For example, an offset of 2 would be between the second and third child nodes.<\/p>\n To read the position for the offset and container node, use the following methods:<\/p>\n \tstartContainer, startOffset, endContainer, endOffset<\/p>\n This is currently supported in Mozilla. The valid syntax to retrieve the startContainer for a valid Range testRange is<\/p>\n \ttestRange.startContainer;<\/p>\n This requires our Range to have a start and end position. This will be tested to show that the setting of start and end works correctly.<\/p>\n A node or CDATA unit is selected if it is between the two boundary points of a Range. A node is partially selected by a Range if it is an ancestor container to exactly one of the boundary points.<\/p>\n Changing a Range’s Position:<\/p>\n Methods: \twhere parent is the container node and offset is an integer\n<\/p>\n Supported in Mozilla<\/p>\n Example: This is one way to select where a Range starts and ends. You can also set a Range’s position relative to nodes in the tree:<\/p>\n \nMethods: Implemented correctly in Mozilla<\/p>\n Example: You can also collapse a Range to one of its boundary points.<\/p>\n Methods: Attributes: Supported in Mozilla<\/p>\n Examples: You can also have a Range directly that will directly select a Node or its contents<\/p>\n Methods: supported in Mozilla<\/p>\n Example: Method: \thow is one of four values, START_TO_START,START_TO_END,END_TO_END,and END_TO_START, which equal the constants 0,1,2,3 \tIt returns either -1,0,1 dpending on whether the corresponding boundary point is before, equal to, or after the boundary point of sourceRange.\n<\/p>\n Fixed in Mozilla implementations after December, 2000. (see bug #58028<\/a>).. returns -1 instead of 1 and vice versa<\/p>\n Example: Method: The Range is collapsed upon deletion<\/p>\n This is supported in Mozilla, but there are reported bugs such as #43535<\/a> which says sometimes too much is deleted<\/p>\n Example: Method: The Range is deleted from the document and is placed and returned in a new DocumentFragment. Partially Selected Nodes are cloned.\n<\/p>\n Fixed in Mozilla in May, 2001. Refer to bug #58969<\/a>\n<\/p>\n Example: Method: Clones the contents of a Range into a new DocumentFragment with boundaryPoints equal to those in the existing Range<\/p>\n Fixed in Mozilla in May, 2001. Refer to bug Refer to bug #58969<\/a>.\n<\/p>\n Example: Method: Inserts a node into the Range at the starting boundary point, following rules similiar to DOM Core method insertBefore(). If the start of the Range is in a text node, that node will be split, even if the new inserted node is all text.\n<\/p>\n Fixed in Mozilla in May, 2001. Refer to bug Refer to bug #58972<\/a>\n<\/p>\n Example: Subsuming Content Selected by a Range (Wrapping the Range inside its own node)<\/p>\n Method: Fixed in Mozilla in May, 2001. Refer to bug Refer to bug #58974<\/a>\n<\/p>\n Example:<\/p>\n \ttestRange.surroundContents(document.createElement(“div”));\n<\/p>\n An exception is raised if Range partially selects a non-text node<\/p>\n If newParent has any children, they are removed before its insertion, and if it has a parent, it is removed from its parent’s childNodes list.<\/p>\n Method: Clones the Range itself.<\/p>\n This is supported in Mozilla<\/p>\n Example: Attribute This gives the ancestor for the boundary points of a Range that is furthest down from the root<\/p>\n This is supported in Mozilla\n<\/p>\n Example: Get a copy of all character data in a Range:\n<\/p>\n Method: This returns the CDATA in a Range\n<\/p>\n This is supported in Mozilla\n<\/p>\n Example: Implementation can remove a Range from resources\n<\/p>\n Method: I do not think JavaScript developers need to worry about this unless they are worried about performance with a lot of Ranges\n<\/p>\n This is supported in Mozilla\n<\/p>\n Example: Method: Used to combine adjacent text nodes and removed empty text nodes from a node\n<\/p>\n This is supported in Mozilla\n<\/p>\n Example: This section simply describes what happens to a Range when a document is mutated by insertion or deletion<\/p>\n All Ranges remain valid after an mutation operation, and they select the same portion of the docuemtn after mutation.\n<\/p>\n Insertion occurs at a single insertion point. The boundary point of the Range changes upon insertion if they have the same container and the offset of the insertion point is less than the offset of the range boundary point. This will change the end boundary point by increasing its offset. The boundary point will be placed at the start of the newly inserted content if the boundary point and insertion point are equivalent.\n<\/p>\n Deletion will affect the Range is the boundary point of the original Range is within the content being deleted. After deletion, it will be a thte same position as the resulting boundary point of the now collapsed Range used to delete the contents.\n<\/p>\n This behavior is supported in Mozilla, though it is highly probable that there are some quirks.\n<\/p>\nhasFeature:<\/h3>\n
Creating a Range:<\/h3>\n
\n\tcreateRange()<\/p>\n
\n\tdocument.createRange();<\/p>\nPosition:<\/h3>\n
Selection:<\/h3>\n
\n\tsetStart(parent,offset)
\n\tsetEnd(parent,offset)<\/p>\n
\n\ttestRange.setStart(document.getElementsByTagName(“div”).item(0),0);
\n\ttestRange.setEnd(document.getElementsByTagName(“div”).item(0),1);\n<\/p>\n
\n\tsetStartBefore(node);
\n\tsetStartAfter(node);
\n\tsetEndBefore(node);
\n\tsetEndAfter(node);\n<\/p>\n
\n\ttestRange.setStartBefore(document.getElementsByTagName(“div”).item(0));
\n\ttestRange.setEndAfter(document.getElementsByTagName(“div”).item(0));<\/p>\n
\n\tcollapse(bool)
\n\twhere bool is “TRUE” to collapse to the start boudnary point, and “FALSE” to collapse to the end boundary point\n<\/p>\n
\n\t.collapsed\n<\/p>\n
\n\ttestRange.collapse(“TRUE”);
\n\talert(testRange.collapsed); \/\/ should return true\n<\/p>\n
\n\tselectNode(node)
\n\tselectNodeContents(node)\n<\/p>\n
\n\ttestRange.selectNode(document.getElementsByTagName(“div”).item(0));\n<\/p>\nComparing two Ranges by their Boundary Points<\/h3>\n
\n\tcompareBoundaryPoints(how,sourceRange)\n<\/p>\n
\n\tthe sourceRange is the Range which you are comparing to.\n<\/p>\n
\n\ttestRange.selectNode(document.getElementsByTagName(“div”).item(0));
\n\ttestRange2.selectNode(document.getElementsByTagName(“div”).item(1));
\n\talert(testRange.compareBoundaryPoints(0,testRange2)); \/\/ should return -1\n<\/p>\nDeleting Content in a Range:<\/h3>\n
\n\tdeleteContents()\n<\/p>\n
\n\ttestRange.deleteContents();\n<\/p>\nExtracting Contents (like Cut) from a Range:<\/h3>\n
\n\textractContents()\n<\/p>\n
\n\ttestFragment = testRange.extractContents();\n<\/p>\nCloning Content (like Copy) in a Range<\/h3>\n
\n\tcloneContents()\n<\/p>\n
\n\tclonedFragment = testRange.cloneContents();\n<\/p>\nInserting Content in a Range<\/h3>\n
\n\tinsertNode(node)\n<\/p>\n
\n\ttestRange.insertNode(document.createTextNode(“Insert This Text “));\n<\/p>\n
\n\tsurroundContents(newParent)\n<\/p>\nIt is equivalent to the following series of steps:<\/p>\n
Cloning a Range:<\/h3>\n
\n\tcloneRange()\n<\/p>\n
\n\ttestRange2 = testRange.cloneRange();\n<\/p>\nGetting an ancestor container:<\/h3>\n
\n\tcommonAncestorContainer\n<\/p>\n
\n\ttestRange.commonAncestorContainer;\n<\/p>\n
\n\ttoString()\n<\/p>\n
\n\ttestRange.toString();\n<\/p>\n
\n\tdetach()\n<\/p>\n
\n\ttestRange.detach();
\n\talert(testRange); \/\/should alert “”\n<\/p>\nNormalization (part of DOM CORE)<\/h3>\n
\n\tnormalize()\n<\/p>\n
\n\tdocument.getElementByTagName(“div”).item(0).normalize();\n<\/p>\nDocument Mutations:<\/h3>\n