DOM2 Traversal - Usage

dom2_traversal.js defines the following interfaces. A more complete description of these interfaces, the associated properties and methods, and their usage can be found in a DOM reference.

NodeFilter

TreeWalker

document.createTreeWalker()

Synopsis

document.createTreeWalker(root, whatToShow, filter, expandEntityReferences)

Arguments

root

A reference to the node that will serve as the root of the TreeWalker.

whatToShow

A bitmask of one or more of the NodeFilter flags that indicate what node types to look at. Though all the NodeFilter flags are defined, only the following will actually work in IE5-6: NodeFilter.SHOW_ALL, NodeFilter.SHOW_ELEMENT, NodeFilter.SHOW_ELEMENT, NodeFilter.SHOW_ATTRIBUTE, NodeFilter.SHOW_TEXT, NodeFilter.SHOW_COMMENT, NodeFilter.SHOW_DOCUMENT, NodeFilter.SHOW_DOCUMENT_FRAGMENT.

filter

A NodeFilter-like object. This is an object that has an acceptNode() method which accepts a node as it's single argument and returns either NodeFilter.FILTER_ACCEPT, NodeFilter.FILTER_REJECT, or NodeFilter.FILTER_SKIP to indicate if the node should be included in the TreeWalker.

expandEntityReferences

A boolean to indicate if entity references should be expanded. Because this script was developed for HTML documents, this argument is ignored.

Returns

A TreeWalker object.

Description

document.createTreeWalker() creates a TreeWalker object. The arguments to this method are also available as properties of the TreeWalker. The current node of the TreeWalker is also available as treeWalker.currentNode.

TreeWalker.firstChild()

Synopsis

treeWalker.firstChild()

Returns

The first child node of the current node that passes the treeWalker's filter; null if the current node has no child nodes or if none of the child nodes pass the filter.

Description

The firstChild() method looks through the current node's child nodes (starting with the first child and working down) to find a child that passes the treeWalker's filter. If one is found, that child is returned and it becomes the current node for the TreeWalker. If no acceptable node is found, the method returns null and the current node is not changed.

TreeWalker.lastChild()

Synopsis

treeWalker.lastChild()

Returns

The last child node of the current node that passes the treeWalker's filter; null if the current node has no child nodes or if none of the child nodes pass the filter.

Description

The lastChild() method looks through the current node's child nodes (starting with the last child and working up) to find a child that passes the treeWalker's filter. If one is found, that child is returned and it becomes the current node for the TreeWalker. If no acceptable node is found, the method returns null and the current node is not changed.

TreeWalker.nextNode()

Synopsis

treeWalker.nextNode()

Returns

The node after the current node in a flattened view of the document that passes the treeWalker's filter; null if there are no nodes after the current node that are also descendants of the root node.

Description

The nextNode() and previousNode() methods look at a flattened version of the document (instead of the other methods that preserve the document's structure). The nextNode() method returns the next node after the current node that passes the treeWalker's filter. If one is found, that node is returned and it becomes the current node for the TreeWalker. If there are no root node descendants after the current node that pass the filter, the method returns null and the current node is not changed.

TreeWalker.nextSibling()

Synopsis

treeWalker.nextSibling()

Returns

The next sibling node of the current node that passes the treeWalker's filter; null if the current node has no sibling nodes after it or if none of the later sibling nodes pass the filter.

Description

The nextSibling() method looks through the current node's siblings nodes (starting with the next sibling and working down) to find a sibling that passes the treeWalker's filter. If one is found, that node is returned and it becomes the current node for the TreeWalker. If no acceptable node is found, the method returns null and the current node is not changed.

TreeWalker.parentNode()

Synopsis

treeWalker.parentNode()

Returns

The first ancestor node of the current node that passes the treeWalker's filter; null if the treeWalker's root node is reached before any acceptable nodes are found or if no parent node is found.

Description

The parentNode() method looks at the current node's ancestor nodes (starting with the parent node and working up) to find the first ancestor that passes the treeWalker's filter. If one is found, that node is returned and it becomes the current node for the TreeWalker. If the root node is reached before any acceptable nodes are found, the method returns null and the current node is not changed.

TreeWalker.previousNode()

Synopsis

treeWalker.previousNode()

Returns

The node before the current node in a flattened view of the document that passes the treeWalker's filter; null if there are no nodes before the current node that are also descendants of the root node.

Description

The nextNode() and previousNode() methods look at a flattened version of the document (instead of the other methods that preserve the document's structure). The previousNode() method returns the node before the current node that passes the treeWalker's filter. If one is found, that node is returned and it becomes the current node for the TreeWalker. If there are no root node descendants before the current node that pass the filter, the method returns null and the current node is not changed.

TreeWalker.previousSibling()

Synopsis

treeWalker.previousSibling()

Returns

The previous sibling node of the current node that passes the treeWalker's filter; null if the current node has no sibling nodes before it or if none of the previous sibling nodes pass the filter.

Description

The previousSibling() method looks through the current node's siblings nodes (starting with the previous sibling and working up) to find a sibling that passes the treeWalker's filter. If one is found, that node is returned and it becomes the current node for the TreeWalker. If no acceptable node is found, the method returns null and the current node is not changed.

More about this script

Related to this script

Licensing

This script is released under a Creative Commons License.