In order to access this site you need to enable JavaScript!

You are here: Reference > JavaScript > client-side > HTML DOM > methods > evaluate (document, XMLDocument)

evaluate method (document, XMLDocument)

Browser support:

Evaluates an XPath expression and creates an XPathResult object that represents the result.

The evaluate method makes it possible to search within the HTML or XML document by complex search conditions.

Syntax:

object.evaluate (xpathExpression, contextNode, namespaceResolver, resultType, result);

You can find the related objects in the Supported by objects section below.

Parameters:

xpathExpression

String that specifies the XPath expression to evaluate. For more information, please visit the Location Paths (W3C) page.

contextNode

Reference to the node in which the search will take place. The node can be the document or any element in the document.

namespaceResolver

Reference to an XPathNSResolver object or a function that can resolve namespaces.

If the XPath expression specified by the first parameter contains namespaces, this parameter needs to be set, else set it to null. To create an XPathNSResolver object, use the createNSResolver method.
If a function is specified, then it must return a string that represents the namespace URI associated with the namespace prefix passed as the first parameter.

See Example 3 and 4 for details.

resultType

Integer that specifies the type of the result. Predefined constants are available for the possible values of this parameter, in the scope of the XPathResult object. For further details, see the page for the XPathResult object.

The value can be one of the following values (the value of a predefined constant appears in parentheses after the constant):

ANY_TYPE (0)

The type of the result depends on the expression specified by the first parameter of the evaluate method.

NUMBER_TYPE (1)

The result is a number. Use the numberValue property to get the value of the result.

STRING_TYPE (2)

The result is a string. Use the stringValue property to get the value of the result.

BOOLEAN_TYPE (3)

The result is a boolean. Use the booleanValue property to get the value of the result.

UNORDERED_NODE_ITERATOR_TYPE (4)

The result contains all nodes that match the expression, but not necessarily in the same order as they appear in the document hierarchy. Use the iterateNext method to get the matching nodes.

ORDERED_NODE_ITERATOR_TYPE (5)

The result contains all nodes that match the expression, in the same order as they appear in the document hierarchy. Use the iterateNext method to get the matching nodes.

UNORDERED_NODE_SNAPSHOT_TYPE (6)

The result contains snapshots for all nodes that match the expression, but not necessarily in the same order as they appear in the document hierarchy. Use the snapshotItem method to get the matching nodes.

ORDERED_NODE_SNAPSHOT_TYPE (7)

The result contains snapshots for all nodes that match the expression, in the same order as they appear in the document hierarchy. Use the snapshotItem method to get the matching nodes.

ANY_UNORDERED_NODE_TYPE (8)

The result is a node that matches the expression. The result node is not necessarily the first matching node in the document hierarchy. Use the singleNodeValue property to get the matching node.

FIRST_ORDERED_NODE_TYPE (9)

The result is the first node in the document hierarchy that matches the expression. Use the singleNodeValue property to get the matching node.

result

Specifies an existing XPathResult object to use for the results. Set to null if you want to create a new XPathResult object.

Return value:

Returns the created or referred (by the result parameter) XPathResult object.

Example HTML code 1:

This example shows how to get all span elements that are immediate children of a given element:

<head>
    <style>
        .level1 {color:red;}
        .level2 {color:blue;}
        .level3 {color:green;}
    </style>
    <script type="text/javascript">
        function GetSpanElements () {
            var message = "";

            if (document.evaluate) {    // Firefox, Opera, Google Chrome and Safari
                var container = document.getElementById ("container");
                var xPathRes = document.evaluate ( 'span', container, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE, null);

                message += "The contents of the span elements:<br />";
                var actualSpan = xPathRes.iterateNext ();
                while (actualSpan) {
                    message += "<b>" + actualSpan.innerHTML + "</b><br />";
                    actualSpan = xPathRes.iterateNext ()
                }
            }
            else {  // Internet Explorer
                message = "Your browser does not support the evaluate method!";
            }

            var info = document.getElementById ("info");
            info.innerHTML = message;
        }
    </script>
</head>
<body onload="GetSpanElements ()">
    <span class="level1">Span 1</span>
    <div id="container">
        <span class="level2">Span 2</span>
        <div>
            <span class="level3">Span 3</span>
            <span class="level3">Span 4</span>
        </div>
        <span class="level2">Span 5</span>
        <span class="level2">Span 6</span>
    </div>
    <span class="level1">Span 7</span>
    <br /><br />
    <div id="info" style="background-color:#e0b0b0; width:400px"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 2:

This example shows how to get all span elements that are descendants of a given element:

<head>
    <style>
        .level1 {color:red;}
        .level2 {color:blue;}
        .level3 {color:green;}
    </style>
    <script type="text/javascript">
        function GetSpanElements () {
            var message = "";

            if (document.evaluate) {    // Firefox, Opera, Google Chrome and Safari
                var container = document.getElementById ("container");
                var xPathRes = document.evaluate ( './/span', container, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE, null);

                message += "The contents of the span elements:<br />";
                var actualSpan = xPathRes.iterateNext ();
                while (actualSpan) {
                    message += "<b>" + actualSpan.innerHTML + "</b><br />";
                    actualSpan = xPathRes.iterateNext ()
                }
            }
            else {  // Internet Explorer
                message = "Your browser does not support the evaluate method!";
            }

            var info = document.getElementById ("info");
            info.innerHTML = message;
        }
    </script>
</head>
<body onload="GetSpanElements ()">
    <span class="level1">Span 1</span>
    <div id="container">
        <span class="level2">Span 2</span>
        <div>
            <span class="level3">Span 3</span>
            <span class="level3">Span 4</span>
        </div>
        <span class="level2">Span 5</span>
        <span class="level2">Span 6</span>
    </div>
    <span class="level1">Span 7</span>
    <br /><br />
    <div id="info" style="background-color:#e0b0b0; width:400px"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 3:

This example shows how to get all span elements that are descendants but not immediate children of a given element:

<head>
    <style>
        .level1 {color:red;}
        .level2 {color:blue;}
        .level3 {color:green;}
    </style>
    <script type="text/javascript">
        function GetSpanElements () {
            var message = "";

            if (document.evaluate) {    // Firefox, Opera, Google Chrome and Safari
                var container = document.getElementById ("container");
                var xPathRes = document.evaluate ( '*//span', container, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE, null);

                message += "The contents of the span elements:<br />";
                var actualSpan = xPathRes.iterateNext ();
                while (actualSpan) {
                    message += "<b>" + actualSpan.innerHTML + "</b><br />";
                    actualSpan = xPathRes.iterateNext ()
                }
            }
            else {  // Internet Explorer
                message = "Your browser does not support the evaluate method!";
            }

            var info = document.getElementById ("info");
            info.innerHTML = message;
        }
    </script>
</head>
<body onload="GetSpanElements ()">
    <span class="level1">Span 1</span>
    <div id="container">
        <span class="level2">Span 2</span>
        <div>
            <span class="level3">Span 3</span>
            <span class="level3">Span 4</span>
        </div>
        <span class="level2">Span 5</span>
        <span class="level2">Span 6</span>
    </div>
    <span class="level1">Span 7</span>
    <br /><br />
    <div id="info" style="background-color:#e0b0b0; width:400px"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 4:

This example shows how to get all span elements in the document that are immediate children of an li element:

<head>
    <style>
        .level1 {color:red;}
        .level2 {color:blue;}
        .level3 {color:green;}
    </style>
    <script type="text/javascript">
        function GetSpanElements () {
            var message = "";

            if (document.evaluate) {    // Firefox, Opera, Google Chrome and Safari
                var xPathRes = document.evaluate ( "//li/span", document, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE, null);

                message += "The contents of the span elements:<br />";
                var actualSpan = xPathRes.iterateNext ();
                while (actualSpan) {
                    message += "<b>" + actualSpan.innerHTML + "</b><br />";
                    actualSpan = xPathRes.iterateNext ()
                }
            }
            else {  // Internet Explorer
                message = "Your browser does not support the evaluate method!";
            }

            var info = document.getElementById ("info");
            info.innerHTML = message;
        }
    </script>
</head>
<body onload="GetSpanElements ()">
    <span class="level1">Span 1</span>
    <ul>
        <li>
            <span class="level2">Span 2</span>
        </li>
        <li>
            <div>
                <span class="level3">Span 3</span>
            </div>
        </li>
        <li>
            <span class="level2">Span 4</span>
            <span class="level2">Span 5</span>
        </li>
        <li>
            <div>
                <span class="level3">Span 6</span>
            </div>
            <span class="level2">Span 7</span>
        </li>
    </ul>
    <span class="level1">Span 8</span>
    <br /><br />
    <div id="info" style="background-color:#e0b0b0; width:400px"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 5:

This example shows how to get all span elements in the document that are descendants of an li element:

<head>
    <style>
        .level1 {color:red;}
        .level2 {color:blue;}
        .level3 {color:green;}
    </style>
    <script type="text/javascript">
        function GetSpanElements () {
            var message = "";

            if (document.evaluate) {    // Firefox, Opera, Google Chrome and Safari
                var xPathRes = document.evaluate ( "//li//span", document, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE, null);

                message += "The contents of the span elements:<br />";
                var actualSpan = xPathRes.iterateNext ();
                while (actualSpan) {
                    message += "<b>" + actualSpan.innerHTML + "</b><br />";
                    actualSpan = xPathRes.iterateNext ()
                }
            }
            else {  // Internet Explorer
                message = "Your browser does not support the evaluate method!";
            }

            var info = document.getElementById ("info");
            info.innerHTML = message;
        }
    </script>
</head>
<body onload="GetSpanElements ()">
    <span class="level1">Span 1</span>
    <ul>
        <li>
            <span class="level2">Span 2</span>
        </li>
        <li>
            <div>
                <span class="level3">Span 3</span>
            </div>
        </li>
        <li>
            <span class="level2">Span 4</span>
            <span class="level2">Span 5</span>
        </li>
        <li>
            <div>
                <span class="level3">Span 6</span>
            </div>
            <span class="level2">Span 7</span>
        </li>
    </ul>
    <span class="level1">Span 8</span>
    <br /><br />
    <div id="info" style="background-color:#e0b0b0; width:400px"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 6:

This example shows how to get all span elements in the document that have a 'class' attribute with a value of 'level2':

<head>
    <style>
        .level1 {color:red;}
        .level2 {color:blue;}
        .level3 {color:green;}
    </style>
    <script type="text/javascript">
        function GetSpanElements () {
            var message = "";

            if (document.evaluate) {    // Firefox, Opera, Google Chrome and Safari
                var xPathRes = document.evaluate ( "//span[@class='level2']", document, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE, null);

                message += "The contents of the span elements:<br />";
                var actualSpan = xPathRes.iterateNext ();
                while (actualSpan) {
                    message += "<b>" + actualSpan.innerHTML + "</b><br />";
                    actualSpan = xPathRes.iterateNext ()
                }
            }
            else {  // Internet Explorer
                message = "Your browser does not support the evaluate method!";
            }

            var info = document.getElementById ("info");
            info.innerHTML = message;
        }
    </script>
</head>
<body onload="GetSpanElements ()">
    <span class="level1">Span 1</span>
    <ul>
        <li>
            <span class="level2">Span 2</span>
        </li>
        <li>
            <div>
                <span class="level3">Span 3</span>
            </div>
        </li>
        <li>
            <span class="level2">Span 4</span>
            <span class="level2">Span 5</span>
        </li>
        <li>
            <div>
                <span class="level3">Span 6</span>
            </div>
            <span class="level2">Span 7</span>
        </li>
    </ul>
    <span class="level1">Span 8</span>
    <br /><br />
    <div id="info" style="background-color:#e0b0b0; width:400px"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 7:

This example illustrates the use of the XPathNSResolver object for the evaluate method:

Code

ajax.js

ns.xml

<head>
    <script type="text/javascript" src="ajax.js"></script>
    
    <script type="text/javascript">
        var httpRequest = null;
        
        function SendRequest () {
            if (!httpRequest) {
                httpRequest = CreateHTTPRequestObject ();   // defined in ajax.js
            }
            if (httpRequest) {          
                    // The requested file must be in the same domain that the page is served from.
                var url = "ns.xml";
                httpRequest.open ("GET", url, true);    // async
                httpRequest.onreadystatechange = OnStateChange;
                httpRequest.send (null);
            }
        }

        function OnStateChange () {
            if (httpRequest.readyState == 0 || httpRequest.readyState == 4) {
                if (IsRequestSuccessful (httpRequest)) {    // defined in ajax.js
                    GetParamTags ();
                }
                else {
                    alert ("Operation failed.");
                }
            }
        }

        function NSResolver (nsPrefix) {
            if (nsPrefix == "dotto") {
                return "http://help.dottoro.com/NS";
            }
            return null;
        }

        function GetParamTags () {
            var xmlDoc = ParseHTTPResponse (httpRequest);   // defined in ajax.js
            if (!xmlDoc)
                return;

            if (xmlDoc.createNSResolver) {
                var nsResolver = xmlDoc.createNSResolver (xmlDoc.documentElement);
                var params = xmlDoc.evaluate("//dotto:param", xmlDoc.documentElement, nsResolver, XPathResult.ANY_TYPE, null);
                var param = params.iterateNext();
                while (param) {
                    var paramName = param.getAttribute ("name");
                    var paramValue = param.getAttribute ("value");
                    alert ("<dotto:param name='" + paramName + "' value='" + paramValue + "' />");
                    param = params.iterateNext();
                }
            }
            else {
                alert ("Your browser doesn't support the createNSResolver method!");
            }
        }
    </script>
</head>
<body>
    <button onclick="SendRequest ()">Get param tags with 'dotto' namespaces</button>
</body>


function CreateHTTPRequestObject () {
        // although IE supports the XMLHttpRequest object, but it does not work on local files.
    var forceActiveX = (window.ActiveXObject && location.protocol === "file:");
    if (window.XMLHttpRequest && !forceActiveX) {
        return new XMLHttpRequest();
    }
    else {
        try {
            return new ActiveXObject("Microsoft.XMLHTTP");
        } catch(e) {}
    }
    alert ("Your browser doesn't support XML handling!");
    return null;
}

function CreateMSXMLDocumentObject () {
    if (typeof (ActiveXObject) != "undefined") {
        var progIDs = [
                        "Msxml2.DOMDocument.6.0", 
                        "Msxml2.DOMDocument.5.0", 
                        "Msxml2.DOMDocument.4.0", 
                        "Msxml2.DOMDocument.3.0", 
                        "MSXML2.DOMDocument", 
                        "MSXML.DOMDocument"
                      ];
        for (var i = 0; i < progIDs.length; i++) {
            try { 
                return new ActiveXObject(progIDs[i]); 
            } catch(e) {};
        }
    }
    return null;
}

function CreateXMLDocumentObject (rootName) {
    if (!rootName) {
        rootName = "";
    }
    var xmlDoc = CreateMSXMLDocumentObject ();
    if (xmlDoc) {
        if (rootName) {
            var rootNode = xmlDoc.createElement (rootName);
            xmlDoc.appendChild (rootNode);
        }
    }
    else {
        if (document.implementation.createDocument) {
            xmlDoc = document.implementation.createDocument ("", rootName, null);
        }
    }
    
    return xmlDoc;
}

function ParseHTTPResponse (httpRequest) {
    var xmlDoc = httpRequest.responseXML;

            // if responseXML is not valid, try to create the XML document from the responseText property
    if (!xmlDoc || !xmlDoc.documentElement) {
        if (window.DOMParser) {
            var parser = new DOMParser();
            try {
                xmlDoc = parser.parseFromString (httpRequest.responseText, "text/xml");
            } catch (e) {
                alert ("XML parsing error");
                return null;
            };
        }
        else {
            xmlDoc = CreateMSXMLDocumentObject ();
            if (!xmlDoc) {
                return null;
            }
            xmlDoc.loadXML (httpRequest.responseText);

        }
    }

            // if there was an error while parsing the XML document
    var errorMsg = null;
    if (xmlDoc.parseError && xmlDoc.parseError.errorCode != 0) {
        errorMsg = "XML Parsing Error: " + xmlDoc.parseError.reason
                  + " at line " + xmlDoc.parseError.line
                  + " at position " + xmlDoc.parseError.linepos;
    }
    else {
        if (xmlDoc.documentElement) {
            if (xmlDoc.documentElement.nodeName == "parsererror") {
                errorMsg = xmlDoc.documentElement.childNodes[0].nodeValue;
            }
        }
    }
    if (errorMsg) {
        alert (errorMsg);
        return null;
    }

        // ok, the XML document is valid
    return xmlDoc;
}

    // returns whether the HTTP request was successful
function IsRequestSuccessful (httpRequest) {
        // IE: sometimes 1223 instead of 204
    var success = (httpRequest.status == 0 || 
        (httpRequest.status >= 200 && httpRequest.status < 300) || 
        httpRequest.status == 304 || httpRequest.status == 1223);
    
    return success;
}

<?xml version="1.0" encoding="utf-8"?>
<ns xmlns="http://help.dottoro.com/defaultNS" xmlns:dotto="http://help.dottoro.com/NS">
    <item dotto:color="red">
        <dotto:title>Namespace example</dotto:title>
        <dotto:description>Describes how to use namespaces with tags and attributes.</dotto:description>
        <dotto:pubDate>Wed, 17 Aug 2009 13:58:41 +0200</dotto:pubDate>
        <dotto:link>http://help.dottoro.com</dotto:link>
    </item>
    <order>
        <dotto:param name="sortBy" value="title" />
        <dotto:param name="sortDir" value="ascending" />
    </order>
</ns>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 8:

This example is equivalent to the previous one, but it implements a namespace resolver function for the evaluate method:

Code

ajax.js

ns.xml

<head>
    <script type="text/javascript" src="ajax.js"></script>
    
    <script type="text/javascript">
        var httpRequest = null;
        
        function SendRequest () {
            if (!httpRequest) {
                httpRequest = CreateHTTPRequestObject ();   // defined in ajax.js
            }
            if (httpRequest) {          
                    // The requested file must be in the same domain that the page is served from.
                var url = "ns.xml";
                httpRequest.open ("GET", url, true);    // async
                httpRequest.onreadystatechange = OnStateChange;
                httpRequest.send (null);
            }
        }

        function OnStateChange () {
            if (httpRequest.readyState == 0 || httpRequest.readyState == 4) {
                if (IsRequestSuccessful (httpRequest)) {    // defined in ajax.js
                    GetParamTags ();
                }
                else {
                    alert ("Operation failed.");
                }
            }
        }

        function NSResolver (nsPrefix) {
            if (nsPrefix == "dotto") {
                return "http://help.dottoro.com/NS";
            }
            return null;
        }

        function GetParamTags () {
            var xmlDoc = ParseHTTPResponse (httpRequest);   // defined in ajax.js
            if (!xmlDoc)
                return;

            if (xmlDoc.createNSResolver) {
                var params = xmlDoc.evaluate("//dotto:param", xmlDoc.documentElement, NSResolver, XPathResult.ANY_TYPE, null);
                var param = params.iterateNext();
                while (param) {
                    var paramName = param.getAttribute ("name");
                    var paramValue = param.getAttribute ("value");
                    alert ("<dotto:param name='" + paramName + "' value='" + paramValue + "' />");
                    param = params.iterateNext();
                }
            }
            else {
                alert ("Your browser doesn't support the createNSResolver method!");
            }
        }
    </script>
</head>
<body>
    <button onclick="SendRequest ()">Get param tags with 'dotto' namespaces</button>
</body>


function CreateHTTPRequestObject () {
        // although IE supports the XMLHttpRequest object, but it does not work on local files.
    var forceActiveX = (window.ActiveXObject && location.protocol === "file:");
    if (window.XMLHttpRequest && !forceActiveX) {
        return new XMLHttpRequest();
    }
    else {
        try {
            return new ActiveXObject("Microsoft.XMLHTTP");
        } catch(e) {}
    }
    alert ("Your browser doesn't support XML handling!");
    return null;
}

function CreateMSXMLDocumentObject () {
    if (typeof (ActiveXObject) != "undefined") {
        var progIDs = [
                        "Msxml2.DOMDocument.6.0", 
                        "Msxml2.DOMDocument.5.0", 
                        "Msxml2.DOMDocument.4.0", 
                        "Msxml2.DOMDocument.3.0", 
                        "MSXML2.DOMDocument", 
                        "MSXML.DOMDocument"
                      ];
        for (var i = 0; i < progIDs.length; i++) {
            try { 
                return new ActiveXObject(progIDs[i]); 
            } catch(e) {};
        }
    }
    return null;
}

function CreateXMLDocumentObject (rootName) {
    if (!rootName) {
        rootName = "";
    }
    var xmlDoc = CreateMSXMLDocumentObject ();
    if (xmlDoc) {
        if (rootName) {
            var rootNode = xmlDoc.createElement (rootName);
            xmlDoc.appendChild (rootNode);
        }
    }
    else {
        if (document.implementation.createDocument) {
            xmlDoc = document.implementation.createDocument ("", rootName, null);
        }
    }
    
    return xmlDoc;
}

function ParseHTTPResponse (httpRequest) {
    var xmlDoc = httpRequest.responseXML;

            // if responseXML is not valid, try to create the XML document from the responseText property
    if (!xmlDoc || !xmlDoc.documentElement) {
        if (window.DOMParser) {
            var parser = new DOMParser();
            try {
                xmlDoc = parser.parseFromString (httpRequest.responseText, "text/xml");
            } catch (e) {
                alert ("XML parsing error");
                return null;
            };
        }
        else {
            xmlDoc = CreateMSXMLDocumentObject ();
            if (!xmlDoc) {
                return null;
            }
            xmlDoc.loadXML (httpRequest.responseText);

        }
    }

            // if there was an error while parsing the XML document
    var errorMsg = null;
    if (xmlDoc.parseError && xmlDoc.parseError.errorCode != 0) {
        errorMsg = "XML Parsing Error: " + xmlDoc.parseError.reason
                  + " at line " + xmlDoc.parseError.line
                  + " at position " + xmlDoc.parseError.linepos;
    }
    else {
        if (xmlDoc.documentElement) {
            if (xmlDoc.documentElement.nodeName == "parsererror") {
                errorMsg = xmlDoc.documentElement.childNodes[0].nodeValue;
            }
        }
    }
    if (errorMsg) {
        alert (errorMsg);
        return null;
    }

        // ok, the XML document is valid
    return xmlDoc;
}

    // returns whether the HTTP request was successful
function IsRequestSuccessful (httpRequest) {
        // IE: sometimes 1223 instead of 204
    var success = (httpRequest.status == 0 || 
        (httpRequest.status >= 200 && httpRequest.status < 300) || 
        httpRequest.status == 304 || httpRequest.status == 1223);
    
    return success;
}

<?xml version="1.0" encoding="utf-8"?>
<ns xmlns="http://help.dottoro.com/defaultNS" xmlns:dotto="http://help.dottoro.com/NS">
    <item dotto:color="red">
        <dotto:title>Namespace example</dotto:title>
        <dotto:description>Describes how to use namespaces with tags and attributes.</dotto:description>
        <dotto:pubDate>Wed, 17 Aug 2009 13:58:41 +0200</dotto:pubDate>
        <dotto:link>http://help.dottoro.com</dotto:link>
    </item>
    <order>
        <dotto:param name="sortBy" value="title" />
        <dotto:param name="sortDir" value="ascending" />
    </order>
</ns>