Availability

DOM Level 2 Traversal

Properties

Node currentNode

The current position of this TreeWalker and the node relative to which all of the TreeWalker traversal methods operate. This is the node most recently returned by one of those traversal methods or, if none of those methods have been called yet, it is the same as the root property.

Note that this is a read/write property, and you can set it to any valid Document node -- even one that is not a descendant of the original root node or one that would be rejected by the filters used by this TreeWalker. If you change the value of this property, the traversal methods operate relative to the new node you specify. Attempting to set this property to null throws a DOMException with a code of NOT_SUPPORTED_ERR.

readonly boolean expandEntityReferences

This read-only property specifies whether this TreeWalker object expands entity references it encounters while traversing XML documents. The value of this property is set by the call to Document.createTreeWalker( ).

readonly NodeFilter filter

The node filter function, if any, that was specified for this TreeWalker in the call to Document.createTreeWalker( ). If no node filter is in use, this property is null.

readonly Node root

This read-only property specifies the root node at which the TreeWalker begins traversal. It is the initial value of the currentNode property and is specified in the call to Document.createTreeWalker( ).

readonly unsigned long whatToShow

This read-only property is a set of bit flags (see NodeFilter for a list of valid flags) that specifies the types of Document nodes this TreeWalker will consider. If a bit is not set in this property, the corresponding node type will always be ignored by this TreeWalker. Note that the value of this property is specified in the call to Document.createTreeWalker( ).

Methods

firstChild( )

Returns the first child of the current node that is not filtered out, or null.

lastChild( )

Returns the last child of the current node that is not filtered out, or null.

nextNode( )

Returns the next node (in document source order) that is not filtered out, or null.

nextSibling( )

Returns the next sibling of the current node that is not filtered out, or null.

parentNode( )

Returns the parent or nearest ancestor of the current node that is not filtered out, or null.

previousNode( )

Returns the previous node (in document source order) that is not filtered out, or null.

previousSibling( )

Returns the nearest previous sibling of the current node that is not filtered out, or null.

Description

A TreeWalker filters a specified document subtree and defines methods that allow programs to traverse the filtered tree (which may have a significantly different structure than the original document tree). Create a TreeWalker object with the createTreeWalker( ) method of the Document object. Once a TreeWalker is created, you can use its firstChild( ) and nextSibling( ) methods to traverse the filtered subtree it represents in the same way that you might use the firstChild and nextSibling properties of the Node interface to traverse an unfiltered document tree.

A TreeWalker applies the same two filtration steps that a NodeIterator does. The various traversal methods defined by TreeWalker will return only nodes that pass both filters. First, the node type must be one of the types specified by the whatToShow property. See NodeFilter for a list of constants that can be combined to specify the whatToShow argument to Document.createTreeWalker( ). Second, if the filter property is not null, each node that passes the whatToShow test is passed to the filter function specified by the filter property. If this function returns NodeFilter.FILTER_ACCEPT, the node is returned. If it returns NodeFilter.FILTER_REJECT, the node and all of its descendants are skipped by the TreeWalker (this differs from NodeIterator filtration, in which descendants are never automatically rejected). If the node filter function returns NodeFilter.FILTER_SKIP, the TreeWalker ignores the node but does consider its descendants.

Unlike NodeIterators, TreeWalkers are not modified when the underlying document is modified. The current node of a TreeWalker remains unchanged, even if that node is removed from the document. (And, in this case, the TreeWalker can be used to traverse the tree of deleted nodes, if any, that surround that current node.)

Example

// A NodeFilter that rejects <font> tags and any element with a
// class="sidebar" attribute and any descendants of such an element
var filter = function(n) {
    if (n.nodeName == "FONT") return NodeFilter.FILTER_SKIP;
    if (n.nodeType == Node.ELEMENT_NODE && n.className == "sidebar")
        return NodeFilter.FILTER_REJECT;
    return NodeFilter.FILTER_ACCEPT;
}

// Create a TreeWalker using the filter above
var tw = document.createTreeWalker(document.body,  // Walk HTML document body
                                   // Consider all nodes except comments
                                   ~NodeFilter.SHOW_COMMENT,
                                   filter,  // Use filter above
                                   false);  // Don't expand entity references

// Here's a recursive function that traverses a document using a TreeWalker
function traverse(tw) {
    // Remember the current node
    var currentNode = tw.currentNode;

    // Loop through the children of the current node of the TreeWalker
    for(var c = tw.firstChild(  ); c != null; c = tw.nextSibling(  )) {
        process(c);    // Do something to process the child
        traverse(tw);  // And recursively process its children
    }

    // Put the TreeWalker back in the state we found it in
    tw.currentNode = currentNode;
}

See Also

NodeFilter, NodeIterator; Chapter 17

Returned by

Document.createTreeWalker( )