ColdFusion XML Toolkit
Tag Reference : CF_XMLDatasource

CF_XMLDatasource

CF_XMLDatasource, creates an XMLDatasource object from an XML document. This object encapsulates the XML document so that it can be used and manipulated with other tags in the toolkit.

Syntax

<CF_XMLDatasource NAME="datasource_name"
                  TYPE="Text/URL/File"
                  FILENAME="XMLFilename"
                  URL="XMLFileURL"
                  PROXYSERVER="proxy_server_name"
                  PROXYPORT="proxy_server_port"
                  CACHEDWITHIN="timespan"
                  CACHENAME="UniqueCacheName">


XMLDocument

</CF_XMLDatasource>

NAME

Required. The name you assign to the XMLDatasource. XMLDatasource names must begin with a letter and may consist of letters, numbers, and the underscore character (spaces are not allowed). The XMLDatasource name is used later in the page to reference the XMLDatasource.

TYPE

Optional. The type of the XML file source:

• TEXT -- The XML is supplied in line between the tags, this is the default.
• FILE -- The XML is supplied from a file, the FileName attribute must be specified when type=file
• URL -- The XML is supplied from a URL, the URL attribute must be specified when type=URL. The ProxyServer and ProxyPort attributes are also available when using this type.

FILENAME

Optional. The full path to the file containing the XML document. Required if TYPE="FILE"

URL

Optional. The full URL to the document containing the XML. Required if TYPE="URL"

PROXYSERVER

Optional. The name of the proxy server, if required when TYPE="URL".

PROXYPORT

Optional. The port to use on the proxy server, if required when TYPE="URL".

CACHEDWITHIN

Optional. Enter a timespan using the ColdFusion CreateTimeSpan function. Cached XML data will be used if the original XMLDatasource date falls within the time span you define. The CreateTimeSpan function is used to define a period of time from the present backwards.

CACHENAME

Optional, however Required if the attribute CachedWithin is used. This attribute specifies the name under which the datasource will be cached. This name must be unique throughout all the XMLDatasource's used in the application. It specifies the name

Usage

There are three ways in which to use the CF_XMLDatasource tag:

• With Type="Text" the XML document is specified, in the ColdFusion template between the start and end tags of CF_XMLDatasource.
• With Type="File" the XML document is loaded from a file, specified by the FileName attribute, for example c:\xml\myFile.xml
• With Type="URL" the xml document is loaded from an HTTP URL. If the ColdFusion servers access to the web server referenced in the URL, is through an HTTP proxy server, this can also be specied using the ProxyServer, and ProxyPort attributes.

Caching is also provided by using the CachedWithin attribute. This tells the server to only reload the XML document if the time it was last used, falls outside the timespan provided. This can give significant performance results, when the ColdFusion template is under heavy use, and the XML document doesn't change much.

To use caching, you also have to specify a cachename. This tells the XML toolkit, what application wide, unique name, to store the datasource object under. This allows the XMLDatasource object to be available in several different templates.

The tag will throw exceptions, such as XML Parsing exceptions if the XML is in an invalid format.

Example

<!--- Using an In-Line Document --->
<CF_XMLDatasource Name="MyDatasource">
    <people>
        <person age="27" company="Torchbox">Tom Dyson</person>
        <person age="27" company="WildFusion">David Maddison</person>
    </people>
</CF_XMLDatasource>

   
<!--- Loading from a file --->
<CF_XMLDatasource Name="MyDatasource" Type="File" FileName="c:\xml\myFile.xml">

   
<!--- Loading from a URL --->
<CF_XMLDatasource Name="MyDatasource" Type="URL" URL="http://www.mycompany.com/myFile.xml">

<!--- Loading from a URL through an HTTP proxy server --->
<CF_XMLDatasource Name="MyDatasource" 
                  Type="URL" 
                  URL="http://www.mycompany.com/myFile.xml" 
                  ProxyServer="myProxyServer" 
                  ProxyPort="80">
   
<!--- Loading from a file, and caching the datasource so it's only reloaded every 5 minutes ---->
<CF_XMLDatasource Name="MyDatasource" 
                  Type="File" 
                  FileName="c:\xml\myFile.xml"
                  CachedWithin="#CreateTimeSpan(0,0,5,0)#"
                  CacheName="MyCachedDatasource">
  
<!--- Once any of these tags have run, the datasource is available to other tags --->
<CF_XMLDump Datasource="MyDatasource">

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