CF_XMLSubset : Tag Reference

CF_XMLSubset

Returns an XMLDatasource containing all of the nodes that match the specified query

Syntax

<CF_XMLSubset NAME="result_datasource_name"
              DATASOURCE="XMLDatasourceObject"
              ROOTNODENAME="root_node_name"
              QUERYTYPE="XPATH/XQuery"
              bTHROWONEMPTY="Yes/No"
              bREMOVENODES="Yes/No"
              CACHEDWITHIN="timespan"> 

Query Statement

</CF_XMLSubset>

NAME

Required. The name you assign to the new XMLDatasource containing the matching nodes.

DATASOURCE

Required. The XMLDatasource object to run the query against.

ROOTNODENAME

Optional. The name of the root node, into which the matching nodes will be placed in the return datasource. The default is 'Results'

QUERYTYPE

Optional. The type of the supplied query.

XPath -- (DEFAULT) the query statement is an XPath query
XQuery -- The query statement is an XQuery query. Until the XQuery spec if finished, this option will throw and exception.

bTHROWONEMPTY

Optional. If no nodes are found for the specified query, this attribute tells the tag what action to take. If this is set to no (Default), the tag returns an empty XMLDatasource. If set to yes, the tag will throw an exception of type XMLSubset.NoNodesFound.

bREMOVENODES

Optional. By default when a subset datasource is created, the source XMLDatasource is untouched. However settings this attributes to true, will remove the nodes in the matched subset from the source XMLDatasource.

CACHEDWITHIN

Optional. Enter a timespan using the ColdFusion CreateTimeSpan function. Cached query data will be used if the original query date falls within the time span you define. The CreateTimeSpan function is used to define a period of time from the present backwards. To use cached data, the current query must use the same statement, and datasource name.

Usage

The tag returns the a copy of all nodes matching the given XPath. The resulting nodes are either returned under the parent node 'Results', or a node with the name specified. For example, with no RootNodeName specified, the XML datasource returned would look as follows:

<results>
   <person age="27" company="Torchbox">Tom Dyson</person> 
   <person age="29" company="Torchbox">olly</person>    
</results>

However if a rootnode name of torchboxemployees was specified, the XMLDatasource would look as follows.

<torchboxemployees>
   <person age="27" company="Torchbox">Tom Dyson</person> 
   <person age="29" company="Torchbox">olly</person>    
</torchboxemployees>

The resulting datasource is a complete XMLDatasource, and can itself be the input into operations, such as XMLQuery, XMLSubset etc.

Example

<!--- Create a simple Datasource --->
<CF_XMLDatasource Name="People">
   <people>
   	<person age="27" company="Torchbox">Tom Dyson</person>
   	<person age="27" company="WildFusion">David Maddison</person>    
   	<person age="23" company="WildFusion">Peter Piper</person>
   	<person age="29" company="Torchbox">olly</person>    
   </people>
</CF_XMLDatasource>


<!--- Find the youngest people --->
<CF_XMLSubset Name="Youngest" Datasource="people" RootNodeName="youngestpeople">
   //person[@age<=27]
</CF_XMLSubset>


<!--- Dump the resulting datasource --->
<CF_XMLDump Datasource="Youngest">


Produced by Tom Dyson of Torchbox, and David Maddison of Wildfusion

ColdFusion XML Toolkit
Tag Reference : CF_XMLSubset