Javascript [Electronic resources] : The Definitive Guide (4th Edition) نسخه متنی

Availability

DOM Level 2 Traversal

Constants

The following three constants are the legal return values for node
filter functions. Note that they are static properties of the object
named NodeFilter, not properties of individual node filter functions:

short FILTER_ACCEPT = 1

Accept this node. A NodeIterator or TreeWalker will return this node
as part of its document traversal.

short FILTER_REJECT = 2

Reject this node. A NodeIterator or TreeWalker will behave as if this
node does not exist. Furthermore, this return value tells a
TreeWalker to ignore all children of this node.

short FILTER_SKIP = 3

Skip this node. A NodeIterator or TreeWalker will not return this
node, but it will recursively consider its children as part of
document traversal.

The following constants are bit flags that can be set in the
whatToShow argument to the
createNodeIterator( ) and
createTreeWalker( ) methods of the Document
object. Each constant corresponds to one of the types of Document
nodes (see the "Node" reference page for a list of node
types) and specifies that a NodeIterator or TreeWalker should
consider nodes of that type during its traversal of the document.
Multiple constants can be combined using the logical OR operator
|. SHOW_ALL is a special value
with all bits set: it indicates that all nodes should be considered,
regardless of their type.

unsigned long SHOW_ALL = 0xFFFFFFFF;
unsigned long SHOW_ELEMENT = 0x00000001;
unsigned long SHOW_ATTRIBUTE = 0x00000002;
unsigned long SHOW_TEXT = 0x00000004;
unsigned long SHOW_CDATA_SECTION = 0x00000008;
unsigned long SHOW_ENTITY_REFERENCE = 0x00000010;
unsigned long SHOW_ENTITY = 0x00000020;
unsigned long SHOW_PROCESSING_INSTRUCTION = 0x00000040;
unsigned long SHOW_COMMENT = 0x00000080;
unsigned long SHOW_DOCUMENT = 0x00000100;
unsigned long SHOW_DOCUMENT_TYPE = 0x00000200;
unsigned long SHOW_DOCUMENT_FRAGMENT = 0x00000400;
unsigned long SHOW_NOTATION = 0x00000800;

Methods

acceptNode( )

In languages such as Java that do not allow functions to be passed as
arguments, you define a node filter by defining a class that
implements this interface and includes an implementation for this
function. The function is passed a node and must return one of the
constants FILTER_ACCEPT,
FILTER_REJECT, or FILTER_SKIP.
In JavaScript, however, you create a node filter simply by defining a
function (with any name) that accepts a node argument and returns one
of the three filter constants. See the following sections for details
and an example.

Description

A node filter is an object that can examine a Document node and tell
a NodeIterator or TreeWalker whether to include the node in its
document traversal. In JavaScript, a node filter is simply a function
that takes a single node argument and returns one of the three
FILTER_ constants defined earlier. There is no
NodeFilter interface; there is simply an object named NodeFilter that
has properties that define those constants. To use a node filter, you
pass it to the createNodeIterator( ) or
createTreeWalker( ) method of the Document object.
Your node filter function will then be called to evaluate nodes when
you use the resulting NodeIterator or TreeWalker object to traverse
the document.

Node filter functions should ideally be written so that they do not
themselves alter the document tree and do not throw any exceptions.
Also, node filters are not allowed to base their filtering decisions
on the history of past invocations of those filters.

Example

You might define and use a node filter function as follows:

// Define a node filter that filters out everything but
 <h1> and <h2> elements
var myfilter = function(n) {  // Filter node n
if ((n.nodeName == "H1") || (n.nodeName == "H2"))
return NodeFilter.FILTER_ACCEPT;
else
return NodeFilter.FILTER_SKIP;
}
// Now create a NodeIterator that uses the filter
var ni = document.createNodeIterator(document.body,
  // Traverse the document body
NodeFilter.SHOW_ELEMENT,  // Elements only
myfilter,  // Filter by tag name
false);  // No entity expansion

See Also

NodeIterator, TreeWalker

Type of

NodeIterator.filter, TreeWalker.filter

Passed to

Document.createNodeIterator( ), Document.createTreeWalker( )