This page is the XPath Contributed Add-on Documentation main page.
With the XPath Contributed Add-on, the following is added to the W3C DOM
parser:
-
DOMNode is extended to support a new function (selectNodeSet) that allows
for XPath expressions to be used on that node's child nodes.
-
A new class, XPATHNodeSet that descends from DOMNodeList
that is the result of the new DOMNode.selectNodeSet call. In addition to the
capabilities provided by DOMNodeList, this class includes new functionality
specific to filtering an XPath result set.
Full documentation of the XPath Contributed Add-on follows:
-
CONTENTS
-
How do I get started with XPath?
-
What XPath expressions are supported?
-
How complete is the XPath processor?
-
What files do I need to include to use XPATH?
-
What are the known limitations with the XPath processor?
-
-
-
DOMNode Extensions
-
DOMNode - selectNodeSet method
-
-
-
XPATHNodeSet
-
XPATHNodeSet object description
-
-
XPATHNodeSet (Native Methods)
-
XPATHNodeSet - getNamedItems method
-
XPATHNodeSet - getTypedItems method
-
-
XPATHNodeSet (Inherited Methods)
-
DOMNodeList - getLength method
-
DOMNodeList - item method
How do I get started with XPath?
It's actually very easy. A nice
XPath tutorial
is available from zvon.org for those not familiar with XPath.
XML for <SCRIPT>'s XPath Contributed Add-on extends the W3C DOMNode class
to incorporate a new method (selectNodeSet) in which an XPath expression can be
applied to the node's children and a new class (XPATHNodeSet) returned based on
the results of the XPath expression. Please see the following example for a
demonstration.
NOTE: A large number of sample XPath example expressions are
available by viewing the XPath Sample Code Page
and launching the "XPath Sample Application - Sample Queries" application.
Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "Hello World"
+ "</TAG1>"
+ "</ROOT>";
//instantiate the W3C DOM Parser
var parser = new DOMImplementation();
//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);
//get the document root
var docRoot = domDoc.getDocumentElement();
//get the TAG1 node via XPath
//start by calling selectNodeSet
//remember, docRoot is a DOMNode
var result = docRoot.selectNodeSet("//TAG1");
//get the TAG1 node from the XPATHNodeSet
var tag1 = result.item(0);
//get the "Hello World" text
var textNode = tag1.getFirstChild();
//the following should be "Hello World"
alert(textNode.toString());
}// end function xmljsDOMExample
What XPath expressions are supported?
Although the XPath Contributed Add-on does not attempt to be fully
W3C complient, most of the common XPath expressions are supported. The
list of supported expressions is shown below:
-
Ordinal queries like //tag1[1]
-
position() queries like //tag1[position()=1]
-
last() queries like //tag1[position=()last()]
-
not() queries like //tag1[not(position()=1)]
-
text() queries like //tag1/text()
-
comment() queries like //tag1/comment()
-
node() queries like //tag1/node()
-
processing-instruction() queries like //tag1/processing-instruction()
-
wild card queries like //tag1/*
-
attribute queries like //@* or //@id
-
attribute subqueries like //tag1[@id=1]
-
count() subqueries like //tag1[count(a)=3]
NOTE: The XPath processor does not support
the use of the "or" (|) operator.
NOTE: A large number of sample XPath example expressions are
available by viewing the XPath Sample Code Page
and launching the "XPath Sample Application - Sample Queries" application.
How complete is the XPath processor?
While providing support for what should be the
majority of the functionality needed for the most common uses of XPath, please
keep in mind that the XPath Contributed Add-on is not fully compliant to the
W3C XPath specificication and has known limitations. Please read the documentation
and ensure any XPath expressions you intend to use are supported before using the
XPath Contributed Add-on.
What files do I need to include to use XPATH?
In order to use XML for <SCRIPT>'s XPath Contributed Add-on, you must include the
following .js file in your HTML Pages. The .js file starting with "tiny" has been
compressed for faster downloads and are functionally identical to their non-compressed
counterparts. The non compressed files may be found in the
contributedAdd-ons/xpath/xpathProcessorSource directory. The
compressed files may be found in the contributedAddonsjsXMLParser/compressed directory.
The XPath Contributed Add-on has been "crunched" using the
Creativyst®JavaScript Compressor
at creativyst.com.
-
xmlxpath.js (or tinyxmlxpath.js)
NOTE: XML for <SCRIPT>'s XPath processor is
only designed to work with the W3C Parser. It does not function with the
Classic DOM parser. If you are using the Classic DOM parser, please use that
parser's TagPath functionality which is similar to XPath.
What are the known limitations with the XPath processor?
XML for <SCRIPT>'s XPath Contributed Add-on has the following known limitations:
-
No native support for namespaces (see workaround below)
-
Not fully compliant to the W3C Spec (see the list of supported XPath expressions)
-
Wild-card searches do not always work as expected. For example, the expression
//*[count(*)=3] should return any node that has three children. This expression
does not work in the XPath Contributed Add-on.
NOTE: Even though the XPath Contributed Add-on does not
natively support namespaces, it is still possible to use XPath with namespaces if
namespace information is included as part of the XPath expression. See the example below.
Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ns1:ROOT xmlns:ns1=\"foo\">"
+ "<ns1:TAG1>"
+ "<ns1:A>data</ns1:A>"
+ "<ns1:B>data</ns1:B>"
+ "<ns1:A>data</ns1:A>"
+ "<ns1:B>data</ns1:B>"
+ "<ns1:A>data</ns1:A>"
+ "</ns1:TAG1>"
+ "</ns1:ROOT>";
//instantiate the W3C DOM Parser
var parser = new DOMImplementation();
//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);
//get the document root
var docRoot = domDoc.getDocumentElement();
//start by calling selectNodeSet
//to return all the nodes under ns1:TAG1
//remember, docRoot is a DOMNode
var xpNSAll = docRoot.selectNodeSet("//ns1:TAG1/*");
//the following should be 5
alert(xpNSAll.getLength());
//now get only the "A" nodes
var xpNSANodes = xpNSAll.getNamedItems("ns1:A");
//the following should be 3
alert(xpNSANodes.getLength());
}// end function xmljsDOMExample
DOMNode - selectNodeSet method
domNode.selectNodeSet(<XPathExpression>);
accepts:
String - The XPath expression to execute on the DOMNode
returns:
XPATHNodeSet - The XPATHNodeSet with the
results of the XPath query.
- or -
null - if an error was reported during the execution of the expression
throws:
N/A
XML for <SCRIPT>'s XPath Contributed Add-on extends the W3C DOMNode class
to incorporate a new method (selectNodeSet) in which an XPath expression can be
applied to the node's children and a new class (XPATHNodeSet) returned based on
the results of the XPath expression.
NOTE: An XPath expression that returns zero nodes is
not considered an error condition. In this case, DOMNode.selectNodeSet will return
an XPATHNodeSet with zero items.
NOTE: A large number of sample XPath example expressions are
available by viewing the XPath Sample Code Page
and launching the "XPath Sample Application - Sample Queries" application.
Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "Hello World"
+ "</TAG1>"
+ "</ROOT>";
//instantiate the W3C DOM Parser
var parser = new DOMImplementation();
//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);
//get the document root
var docRoot = domDoc.getDocumentElement();
//get the TAG1 node via XPath
//start by calling selectNodeSet
//remember, docRoot is a DOMNode
var result = docRoot.selectNodeSet("//TAG1");
//get the TAG1 node from the XPATHNodeSet
var tag1 = result.item(0);
//get the "Hello World" text
var textNode = tag1.getFirstChild();
//the following should be "Hello World"
alert(textNode.toString());
}// end function xmljsDOMExample
XPATHNodeSet object description
XPATHNodeSet descends from DOMNodeList
and is the object returned when DOMNode.selectNodeSet is called. In addition to the
capabilities provided by DOMNodeList, this class includes new functionality
specific to filtering an XPath result set.
XPATHNodeSet - getNamedItems method
XPATHNodeSet.getNamedItems(<name>);
accepts:
String - The name of the DOMNodes to search for
returns:
XPATHNodeSet - The XPATHNodeSet with the
results of the query.
throws:
N/A
getNamedItems allows developers to get a subset of the nodes inside an XPATHNodeSet
based on the node names of the DOMNodes in the original XPATHNodeSet.
Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "<A>data</A>"
+ "<B>data</B>"
+ "<A>data</A>"
+ "<B>data</B>"
+ "<A>data</A>"
+ "</TAG1>"
+ "</ROOT>";
//instantiate the W3C DOM Parser
var parser = new DOMImplementation();
//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);
//get the document root
var docRoot = domDoc.getDocumentElement();
//start by calling selectNodeSet
//to return all the nodes under TAG1
//remember, docRoot is a DOMNode
var xpNSAll = docRoot.selectNodeSet("//TAG1/*");
//the following should be 5
alert(xpNSAll.getLength());
//now get only the "A" nodes
var xpNSANodes = xpNSAll.getNamedItems("A");
//the following should be 3
alert(xpNSANodes.getLength());
}// end function xmljsDOMExample
XPATHNodeSet - getTypedItems method
XPATHNodeSet.getTypedItems(<type>);
accepts:
String - The type of DOMNode to search for
returns:
XPATHNodeSet - The XPATHNodeSet with the
results of the query.
throws:
N/A
getTypedItems allows developers to get a subset of the nodes inside an XPATHNodeSet
based on the node type of the DOMNodes in the original XPATHNodeSet. The available
types to search on are:
-
"text"
-
"comment"
-
"processing-instruction"
-
"node"
If a type other than the ones above is passed in, an empty XPATHNodeSet is returned.
Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "text node"
+ "<!--comment node-->"
+ "<? piTarget piData ?>"
+ "</TAG1>"
+ "</ROOT>";
//instantiate the W3C DOM Parser
var parser = new DOMImplementation();
//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);
//get the document root
var docRoot = domDoc.getDocumentElement();
//start by calling selectNodeSet
//to return all the nodes under TAG1
//remember, docRoot is a DOMNode
var xpNSAll = docRoot.selectNodeSet("//TAG1/*");
//now get only the text node
var xpNSTextItem = xpNSAll.getTypedItems("text");
//the following should be "text node"
alert(xpNSTextItem.item(0).getData());
//now get the comment node
var xpNSCommentItem = xpNSAll.getTypedItems("comment");
//the following should be "comment node"
alert(xpNSCommentItem.item(0).getData());
//now get the processing instruction node
var pi = "processing-instruction";
var xpNSPIItem = xpNSAll.getTypedItems(pi);
//the following should be "piData"
alert(xpNSPIItem.item(0).getData());
//get all nodes
var xpNSNodeItems = xpNSAll.getTypedItems("node");
//the following should be 3
alert(xpNSNodeItems.getLength());
}// end function xmljsDOMExample