Description

Uses an XPath language expression to search an XML document object.

Returns

The results of the XPath search. For details, see Usage.

Category

XML functions

Function syntax

XmlSearch(xmlNode, xpath, params)

See also

cfxmlIsXMLXmlChildPosXmlParseXmlTransformUsing XML and WDDX in the Developing ColdFusion Applications

History

ColdFusion 10: Added support for XPath 2.0 syntax and for passing variables to XPath expressions.

ColdFusion 8: Added support for returning any valid XPath result, not just arrays of XML object nodes.

ColdFusion MX 7: Added support for attribute searches.

ColdFusion MX: Added this function.

Parameters

Parameter

Description

params

Optional. A struct that contains key-value pairs (variable name and value) document object as shown in the following example:

<cfscript>
params = structNew();
params["test"] = "food";
</cfscript>
<!--- find all nodes with element name as passed by variable test --->
<cfset result = xmlSearch(xmldoc,"/breakfast_menu/*[local-name() eq $test]", params)>

 

xmlNode

XML document object

xpath

XPath expression

Usage

The XmlSearch function attempts to return the values returned by the search whenever possible. For example, if the XPath expression returns a Boolean, the CFML variable is assigned a true or false value.The following table lists XPath expression result data types and how they are represented in the CFML return value.

XPath return type

ColdFusion representation

Boolean

Boolean

Null

"" (empty string)

Number

Number

String

String

NodeSet

Array of XML nodes

Result Tree Fragment

Array of XML nodes

Results that are Unknown or have an unresolved variable in the expression throw an error.XPath is specified by the World Wide Web Consortium (W3C). For detailed information on XPath, including XPath expression syntax, see the W3C website at www.w3.org/TR/xpath.

Example

The following example extracts the elements named last, which contain employee last names, from an XML file, and displays the names.The employeesimple.xml file contains the following XML:

<?xml version="1.0" encoding="UTF-8"?> 
<employee> 
<!-- A list of employees --> 
<name EmpType="Regular"> 
<first>Almanzo</first> 
<last>Wilder</last> 
</name> 
<name EmpType="Contract"> 
<first>Laura</first> 
<last>Ingalls</last> 
</name> 
</employee>

The CFML file contains the following lines:

<cfscript> 
myxmldoc = XmlParse("C:\CFusionMX7\wwwroot\examples\employeesimple.xml"); 
selectedElements = XmlSearch(myxmldoc, "/employee/name/last"); 
for (i = 1; i LTE ArrayLen(selectedElements); i = i + 1) 
writeoutput(selectedElements[i].XmlText & "<br>"); 
</cfscript>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy