mozilla

Revision 485867 of NodeFilter

  • Revision slug: Web/API/NodeFilter
  • Revision title: NodeFilter
  • Revision id: 485867
  • Created:
  • Creator: Jesse
  • Is current revision? No
  • Comment

Revision Content

{{ DomRef() }}

A NodeFilter interface represents an object 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.

The browser doesn't provide any object implementing this interface. It is the user who is expected to write one, tailoring the acceptNode() method to its needs, and using it with some {{domxref("TreeWalker")}} or {{domxref("NodeIterator")}} objects.

Properties

This interface neither implements, nor inherits, any property.

Methods

This interface doesn't inherit any method.

{{domxref("NodeFilter.acceptNode()")}}
Returns an unsigned short that will be used to tell if a given {{domxref("Node")}} must be accepted or not by the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} iteration algorithm. This method is expected to be written by the user of a NodeFilter. Possible return values are:
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".

Example

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);
}

Specifications

Specification Status Comment
{{SpecName('DOM WHATWG', '#nodeFilter', 'NodeFilter')}} {{Spec2('DOM WHATWG')}}  
{{SpecName('DOM2 Traversal_Range', 'traversal.html#Traversal-NodeFilter', 'NodeFilter')}} {{Spec2('DOM2 Traversal_Range')}} Initial definition.

Browser compatibility

{{CompatibilityTable}}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 1.0 {{CompatGeckoDesktop("1.8.1")}} 9.0 9.0 3.0
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{CompatVersionUnknown}} {{CompatGeckoMobile("1.8.1")}} {{CompatVersionUnknown}} 9.0 3.0

See also

  • Related interfaces: {{domxref("TreeWalker")}}, {{domxref("NodeIterator")}}.

Revision Source

<p>{{ DomRef() }}</p>
<p>A <strong><code>NodeFilter</code></strong> interface represents an object 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>
<div class="note">
 <p>The browser doesn't provide any object implementing this interface. It is the user who is expected to write one, tailoring the <code>acceptNode()</code> method to its needs, and using it with some {{domxref("TreeWalker")}} or {{domxref("NodeIterator")}} objects.</p>
</div>
<h2 id="Properties">Properties</h2>
<p><em>This interface neither implements, nor inherits, any property.</em></p>
<h2 id="Methods">Methods</h2>
<p><em>This interface doesn't inherit any method.</em></p>
<dl>
 <dt>
  {{domxref("NodeFilter.acceptNode()")}}</dt>
 <dd>
  Returns an <code>unsigned short</code> that will be used to tell if a given {{domxref("Node")}} must be accepted or not by the {{ domxref("NodeIterator") }} or {{ domxref("TreeWalker") }} iteration algorithm. This method is expected to be written by the user of a <code>NodeFilter</code>. Possible return values are:
  <table class="standard-table">
   <tbody>
    <tr>
     <td class="header">Constant</td>
     <td class="header">Description</td>
    </tr>
    <tr>
     <td><code>FILTER_ACCEPT</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>
 </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>
<h2 id="Specification" name="Specification">Specifications</h2>
<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('DOM WHATWG', '#nodeFilter', 'NodeFilter')}}</td>
   <td>{{Spec2('DOM WHATWG')}}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 Traversal_Range', 'traversal.html#Traversal-NodeFilter', 'NodeFilter')}}</td>
   <td>{{Spec2('DOM2 Traversal_Range')}}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{CompatibilityTable}}</p>
<div id="compat-desktop">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Chrome</th>
    <th>Firefox (Gecko)</th>
    <th>Internet Explorer</th>
    <th>Opera</th>
    <th>Safari</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>1.0</td>
    <td>{{CompatGeckoDesktop("1.8.1")}}</td>
    <td>9.0</td>
    <td>9.0</td>
    <td>3.0</td>
   </tr>
  </tbody>
 </table>
</div>
<div id="compat-mobile">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Android</th>
    <th>Firefox Mobile (Gecko)</th>
    <th>IE Mobile</th>
    <th>Opera Mobile</th>
    <th>Safari Mobile</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatGeckoMobile("1.8.1")}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>9.0</td>
    <td>3.0</td>
   </tr>
  </tbody>
 </table>
</div>
<h2 id="See_also">See also</h2>
<ul>
 <li>Related interfaces: {{domxref("TreeWalker")}}, {{domxref("NodeIterator")}}.</li>
</ul>
Revert to this revision