TreeWalkerNN 7 IE n/a DOM 2  

  

The TreeWalker object is a live, hierarchical list of nodes that meet criteria defined by the document.createTreeWalker( ) method. The list assumes the same parent-descendant hierarchy for its items as the nodes to which its items point. The createTreeWalker( ) method describes the node where the list begins and which nodes (or classes of nodes) are exempt from the list by way of filtering.

 

The TreeWalker object maintains a kind of pointer inside the list (so that your scripts don't have to). Methods of this object let scripts access the next or previous node (or sibling, child, or parent node) in the list, while moving the pointer in the direction indicated by the method you chose. If scripts modify the document tree after the TreeWalker is created, changes to the document tree are automatically reflected in the sequence of nodes in the TreeWalker.

 

While fully usable in an HTML document, the TreeWalker can be even more valuable in an XML data document. For example, the W3C DOM does not provide a quick way to access all elements that have a particular attribute name (something that the XPATH standard can do easily on the server). But you can define a TreeWalker to point only to nodes that have the desired attribute, and quickly access those nodes sequentially (i.e., without having to script more laborious looping through all nodes in search of the desired elements). As an example, the following filter function allows only those nodes that contain the author attribute to be a member of a TreeWalker object: 

function authorAttrFilter(node) {
    if (node.hasAttribute("author")) {
        return NodeFilter.FILTER_ACCEPT;		
    }
    return NodeFilter.FILTER_SKIP;
}
 

A reference to this function becomes one of the parameters to a createTreeWalker( ) method that also limits the list to element nodes: 

var authorsOnly = document.createTreeWalker(document, 
NodeFilter.SHOW_ELEMENT, authorAttrFilter, false);
 

You can then invoke TreeWalker object methods to obtain a reference to one of the nodes in the list. When you invoke the method, the TreeWalker object applies the filter to candidates relative to the current poistion of the internal pointer in the direction indicated by the method. The next document tree node to meet the method and filter criteria is returned. Once you have that node reference, you can access any DOM node property or method to work with the node, independent of the items in the TreeWalker list.

 
Object Model Reference
  
TreeWalkerReference
 
Object-Specific Properties
 
currentNodeexpandEntityReferencefilterrootwhatToShow
 
Object-Specific Methods
 
firstChild( )lastChild( )nextNode( )nextSibling( )
parentNode( )previousNode( )previousSibling( )
 
Object-Specific Event Handler Properties

None.

currentNodeNN 7 IE n/a DOM 2  

Read/Write  

Returns a reference to the node where the TreeWalker's pointer is positioned. But more importantly, you can also assign a document tree node reference to this property to manually set a new position for the pointer. If the assigned node would normally be filtered out of the list, the next method invocation is performed from the position as if the assigned node were not filtered out of the list.

 
Example
  
myTreeWalker.currentNode = document.getElementById("main");
 
Value

Reference to a document tree node.
 
Default

First node of the document.
expandEntityReference, filter, root, whatToShowNN 7 IE n/a DOM 2  

Read-only  

These four properties reflect the parameter values passed to the document.createTreeWalker( ) method when the object was created.

firstChild( ), lastChild( ), nextSibling( ), parentNode( ), previousSibling( )NN 7 IE n/a DOM 2  

  

These methods return references to nodes within the hierarchy of items in the TreeWalker object. The parent-descendant relationships between nodes are identical to those of the nodes within the document tree. As you invoke any one of these methods, the TreeWalker's internal pointer moves to a position adjacent to the node's spot within the TreeWalker list. If there is no node meeting the desired reference, the method returns null. This means that you need to verify the existence of the node before reading any property of the node: 

if (myTreeWalker.nextSibling( )) {
    var theTag = myTreeWalker.currentNode.tagName;
}
 

If you reference a property of a null reference directly (myTreeWalker.nextSibling( ).tagName, for example), a reference error results.

 
Parameters

None.

 
Returned Value

Reference to a document tree node.

nextNode( ), previousNode( )NN 7 IE n/a DOM 2  

  

Move the internal NodeIterator pointer one position forward (nextNode( )) or backward (previousNode( )), while returning a reference to the node through which the pointer passed en route. These two methods operate as if the hierarchy were flattened (in the manner of a NodeIterator object).

 
Parameters

None.

 
Returned Value

Reference to a node in the document tree.