Revision 79962 of NodeFilter

  • Revision slug: DOM/NodeFilter
  • Revision title: NodeFilter
  • Revision id: 79962
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment one or more formatting changes

Revision Content

{{ DomRef() }}

{{ gecko_minversion_header("1.9.1") }}

Summary

A NodeFilter is used to filter the nodes in a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }}. They don't know anything about the DOM or how to traverse nodes; they just know how to evaluate a single node against the provided filter.

Constants

Filter specification constants

These constants specify what nodes should be included in the results of the filter.

Constant Description
SHOW_ALL
Shows all nodes.
SHOW_ATTRIBUTE Shows attribute {{ domxref("Attr") }} nodes. This is meaningful only when creating a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} with an {{ domxref("Attr") }} node as its root; in this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree.
SHOW_CDATA_SECTION
Shows {{ domxref("CDATASection") }} nodes.
SHOW_COMMENT
Shows {{ domxref("Comment") }} nodes.
SHOW_DOCUMENT
Shows {{ domxref("Document") }} nodes.
SHOW_DOCUMENT_FRAGMENT
Shows {{ domxref("DocumentFragment") }} nodes.
SHOW_DOCUMENT_TYPE
Shows {{ domxref("DocumentType") }} nodes.
SHOW_ELEMENT
Shows {{ domxref("Element") }} nodes.
SHOW_ENTITY
Shows {{ domxref("Entity") }} nodes. This is meaningful only when creating a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} with an {{ domxref("Entity") }} node as its root; in this case, it means that the {{ domxref("Entity") }} node will appear in the first position of the traversal. Since entities are not part of the document tree, they do not appear when traversing over the document tree.
SHOW_ENTITY_REFERENCE
Shows {{ domxref("EntityReference") }} nodes.
SHOW_NOTATION
Shows {{ domxref("Notation") }} nodes. This is meaningful only when creating a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} with a {{ domxref("Notation") }} node as its root; in this case, it means that the {{ domxref("Notation") }} node will appear in the first position of the traversal. Since entities are not part of the document tree, they do not appear when traversing over the document tree.
SHOW_PROCESSING_INSTRUCTION
Shows {{ domxref("ProcessingInstruction") }} nodes.
SHOW_TEXT
Shows {{ domxref("Text") }} nodes.

Node accept/reject constants

One of the following constants must be returned by {{ domxref("NodeFilter.acceptNode()") }}.

Constant Description
FILTER_ACCEPT Value returned by the {{ domxref("NodeFilter.acceptNode()") }} method when a node should be accepted.
FILTER_REJECT Value to be returned by the {{ domxref("NodeFilter.acceptNode()") }} method when a node should be rejected. The children of rejected nodes are not visited by the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} object; this value is treated as "skip this node and all its children".
FILTER_SKIP Value to be returned by {{ domxref("NodeFilter.acceptNode()") }} for nodes to be skipped by the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} object. The children of skipped nodes are still considered. This is treated as "skip this node but not its children".

Methods

acceptNode
The accept node method used by the filter is supplied as an object property when constructing the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }}.

Example

var nodeIterator = document.createNodeIterator(
  // Node to use as root
  document.getElementById('someId'),

  // Onlly consider nodes that are text nodes (nodeType 3)
  NodeFilter.SHOW_TEXT,

  // Object containing the function to use for the acceptNode method
  // of the NodeFilter
    { acceptNode: function(node) {
      // Logic to determine whether to accept, reject or skip node
      // In this case, only accept nodes that have content
      // other than whitespace
      if ( ! /^\s*$/.test(node.data) ) {
        return NodeFilter.FILTER_ACCEPT;
      }
    }
  },
  false
);

// Show the content of every non-empty text node that is a child of root
var node;

while ((node = iterator.nextNode())) {
  alert(node.data);
}

Note that in order for the iterator to accept a node, the acceptNode function must return NodeFilter.FILTER_ACCEPT.

Specification

Revision Source

<p>{{ DomRef() }}</p>
<p>{{ gecko_minversion_header("1.9.1") }}</p>
<h2>Summary</h2>
<p>A <code>NodeFilter</code> is used to filter the nodes in a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }}. They don't know anything about the DOM or how to traverse nodes; they just know how to evaluate a single node against the provided filter.</p>
<h2>Constants</h2>
<h3>Filter specification constants</h3>
<p>These constants specify what nodes should be included in the results of the filter.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>SHOW_ALL<br> </code></td> <td>Shows all nodes.</td> </tr> <tr> <td><code>SHOW_ATTRIBUTE</code></td> <td>Shows attribute {{ domxref("Attr") }} nodes. This is meaningful only when creating a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} with an {{ domxref("Attr") }} node as its root; in this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree.</td> </tr> <tr> <td><code>SHOW_CDATA_SECTION<br> </code></td> <td>Shows {{ domxref("CDATASection") }} nodes.</td> </tr> <tr> <td><code>SHOW_COMMENT<br> </code></td> <td>Shows {{ domxref("Comment") }} nodes.</td> </tr> <tr> <td><code>SHOW_DOCUMENT<br> </code></td> <td>Shows {{ domxref("Document") }} nodes.</td> </tr> <tr> <td><code>SHOW_DOCUMENT_FRAGMENT<br> </code></td> <td>Shows {{ domxref("DocumentFragment") }} nodes.</td> </tr> <tr> <td><code>SHOW_DOCUMENT_TYPE<br> </code></td> <td>Shows {{ domxref("DocumentType") }} nodes.</td> </tr> <tr> <td><code>SHOW_ELEMENT<br> </code></td> <td>Shows {{ domxref("Element") }} nodes.</td> </tr> <tr> <td><code>SHOW_ENTITY<br> </code></td> <td>Shows {{ domxref("Entity") }} nodes. This is meaningful only when creating a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} with an {{ domxref("Entity") }} node as its root; in this case, it means that the {{ domxref("Entity") }} node will appear in the first position of the traversal. Since entities are not part of the document tree, they do not appear when traversing over the document tree.</td> </tr> <tr> <td><code>SHOW_ENTITY_REFERENCE<br> </code></td> <td>Shows {{ domxref("EntityReference") }} nodes.</td> </tr> <tr> <td><code>SHOW_NOTATION<br> </code></td> <td>Shows {{ domxref("Notation") }} nodes. This is meaningful only when creating a {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} with a {{ domxref("Notation") }} node as its root; in this case, it means that the {{ domxref("Notation") }} node will appear in the first position of the traversal. Since entities are not part of the document tree, they do not appear when traversing over the document tree.</td> </tr> <tr> <td><code>SHOW_PROCESSING_INSTRUCTION<br> </code></td> <td>Shows {{ domxref("ProcessingInstruction") }} nodes.</td> </tr> <tr> <td><code>SHOW_TEXT<br> </code></td> <td>Shows {{ domxref("Text") }} nodes.</td> </tr> </tbody>
</table>
<h3>Node accept/reject constants</h3>
<p>One of the following constants must be returned by {{ domxref("NodeFilter.acceptNode()") }}.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code><a name="FILTER_ACCEPT">FILTER_ACCEPT</a></code></td> <td>Value returned by the {{ domxref("NodeFilter.acceptNode()") }} method when a node should be accepted.</td> </tr> <tr> <td><code>FILTER_REJECT</code></td> <td>Value to be returned by the {{ domxref("NodeFilter.acceptNode()") }} method when a node should be rejected. The children of rejected nodes are not visited by the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} object; this value is treated as "skip this node and all its children".</td> </tr> <tr> <td><code>FILTER_SKIP</code></td> <td>Value to be returned by {{ domxref("NodeFilter.acceptNode()") }} for nodes to be skipped by the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} object. The children of skipped nodes are still considered. This is treated as "skip this node but not its children".</td> </tr> </tbody>
</table>
<h2>Methods</h2>
<dl> <dt><a name="acceptNode">acceptNode</a></dt> <dd>The accept node method used by the filter is supplied as an object property when constructing the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }}.</dd>
</dl>
<h2>Example</h2>
<pre class="brush: js">var nodeIterator = document.createNodeIterator(
  // Node to use as root
  document.getElementById('someId'),

  // Onlly consider nodes that are text nodes (nodeType 3)
  NodeFilter.SHOW_TEXT,

  // Object containing the function to use for the acceptNode method
  // of the NodeFilter
    { acceptNode: function(node) {
      // Logic to determine whether to accept, reject or skip node
      // In this case, only accept nodes that have content
      // other than whitespace
      if ( ! /^\s*$/.test(node.data) ) {
        return NodeFilter.FILTER_ACCEPT;
      }
    }
  },
  false
);

// Show the content of every non-empty text node that is a child of root
var node;

while ((node = iterator.nextNode())) {
  alert(node.data);
}
</pre>
<p>Note that in order for the iterator to accept a node, the <a href="#acceptNode">acceptNode</a> function must return <a href="#FILTER_ACCEPT">NodeFilter.FILTER_ACCEPT</a>.</p>
<h2>Specification</h2>
<ul> <li><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter" rel="external nofollow" target="_blank" title="http://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter">DOM Level 2 Traversal: NodeFilter</a></li>
</ul>
Revert to this revision