Revision 321377 of NodeFilter

<p>{{ DomRef() }}</p>
<p>{{ gecko_minversion_header("1.9.1") }}</p>
<h2 id="Summary">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 id="Constants">Constants</h2>
<h3 id="Filter_specification_constants">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</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</code></td>
      <td>Shows {{ domxref("CDATASection") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_COMMENT</code></td>
      <td>Shows {{ domxref("Comment") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_DOCUMENT</code></td>
      <td>Shows {{ domxref("Document") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_DOCUMENT_FRAGMENT</code></td>
      <td>Shows {{ domxref("DocumentFragment") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_DOCUMENT_TYPE</code></td>
      <td>Shows {{ domxref("DocumentType") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_ELEMENT</code></td>
      <td>Shows {{ domxref("Element") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_ENTITY</code></td>
      <td>Shows {{ domxref("Entity") }}&nbsp;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</code></td>
      <td>Shows {{ domxref("EntityReference") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_NOTATION</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</code></td>
      <td>Shows {{ domxref("ProcessingInstruction") }}&nbsp;nodes.</td>
    </tr>
    <tr>
      <td><code>SHOW_TEXT</code></td>
      <td>Shows {{ domxref("Text") }}&nbsp;nodes.</td>
    </tr>
  </tbody>
</table>
<h3 id="Node_accept.2Freject_constants">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 id="Methods">Methods</h2>
<dl>
  <dt>
    <code><a name="acceptNode">acceptNode()</a></code></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 id="Example">Example</h2>
<pre class="brush: js">
var nodeIterator = document.createNodeIterator(
  // Node to use as root
  document.getElementById('someId'),

  // Only 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 id="Specification">Specification</h2>
<ul>
  <li><a class="external" href="https://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter" rel="external nofollow" target="_blank" title="https://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter">DOM Level 2 Traversal: NodeFilter</a></li>
</ul>