XML in ColdFusion

ColdFusion has built-in support for reading, writing, and manipulating XML data. Low-level functions allow for a more granular level of access, while higher-level functions and tags abstract and simplify common operations.

XML Documents vs. XML Document Objects

An XML document is simply a big string. While this makes moving and storing the XML data easy, it presents problems when it comes to extracting and working with specific elements. An easier way to work with XML is by treating it as a tree: a hierarchical view of the data. In ColdFusion, this hierarchical view is the document objectessentially a big nested ColdFusion structure. The structure contains all the XML document's data stored in arrays and structures that are given the names of the XML tags. This form of representation makes working with XML data very easy indeed.

NOTE

The document object is a structure that contains other arrays and structures. As such, the standard array and structure functions may be used to manipulate XML data.

Reading an XML Document

Reading an XML document is simply a matter of reading the data, perhaps using a <cffile> or some other tag. Once the raw XML content is available, you can create an XML Document Object using the XMLParse() function, as seen here:

 <!--- Read XML file ---> <cffile action="read"         file="menu.xml"         variable="menu_data"> <!--- Parse it ---> <cfset menu=XMLParse(menu_data)> 

In this example, an XML file containing menu data is read using <cffile>. XMLParse() then creates an XML Document Object representation of the data.

TIP

To see the XML Document Object in all its glory, dump it using <cfdump>.

Validating an XML Document

The format of data within an XML document is defined as an XML schema or DTD (Document Type Definition). XML documents may be well formed but still invalid if they do not comply with a set of rules.

To check that an XML document conforms to all specified rules (likely including names of elements, data types, required flags, and more), use the XMLValidate() function, as follows:

 <!--- Read XML file ---> <cffile action="read"         file="menu.xml"         variable="menu_data"> <!--- If valid ---> <cfif XMLValidate(menu_data, schema)>   ... </cfif> 

Validation can also be performed while parsing XML data using XMLParse() (seen previously) by passing optional validator details.

Creating an XML Document

In addition to being able to create XML Document Objects from existing XML data, ColdFusion can also create new, empty XML Document Objects that may be populated as needed. There are two ways to programmatically create an XML Document Object: using a tag or using a function.

<cfxml>

The <cfxml> function creates a new XML Document Object. <cfxml> requires that a variable name be provided for the new object. An optional flag can be used to specify whether the document elements and attributes should be case- sensitive (the default is no).

The following example creates a new XML Document Object named users:

 <cfxml variable="users"> 

XMLNew()

XMLNew() is a function that is equivalent to <cfxml>, and it may be used wherever expressions are used, as well as in a <cfscript> block. XMLNew() does not take the name of a variable like <cfxml> does (since it returns the object); however, it does take the same optional case-sensitive flag. Here is the same example using XMLNew():

 <cfset users=XMLNew()> 

and using <cfscript>:

 <cfscript> users=XMLNew(); </cfscript> 

<cfscript> was reviewed in Chapter 21, "Scripting."

Writing XML

The XML Document Object is perfect for manipulating data within ColdFusion, but outside of ColdFusion it is useless. Because XML data must be shared in its text form, XML Document Objects must be converted back to their text forms when work on them is complete.

The ToString() function handles several forms of data conversions (all to string format), including XML. To convert the previously created XML Document Object to a string, you could use the following code:

 <cfset users_string=ToString(users)> 

Working with XML

XML data in XML Document Object form can be accessed and manipulated just like any other ColdFusion structures can. For example, consider the following XML menu code:

 <menu name="Menu">  <item>  <text>Home</text>  <link>/index.cfm</link>  </item>  <menu name="Products">  <item>  <text>ColdFusion</text>  <link>/products/cf.cfm</link>  </item>  <item>  <text>Flash</text>  <link>/products/flash.cfm</link>  </item>  </menu>  <item>  <text>Search</text>  <link>/search.cfm</link>  </item>  <item>  <text>Login</text>  <link>/logout.cfm</link>  </item> </menu> 

Once this menu data has been read (perhaps using code as shown above) and parsed with XMLParse(), the structure menu would be accessible just like any other ColdFusion structure would be. For example, to access the first set of child tags (the first menu item), you could use the following code:

 #menu.menu.xmlchildren[1]# 

menu.menu.xmlchildren is an array of menu items, with each array element a structure containing the menu item text and link, an array of any submenus, and so on. It is this open-ended structure, so typical of XML, that makes ColdFusion's XML Document Object so invaluable.

Here is another example, this time populating an XML Document Object with the results of a database query:

 <!--- Create XML object ---> <cfxml variable="UserRecs">  <UserRecs>  <!--- Loop through users --->  <cfoutput query="users">  <!--- Write user --->  <user>  <UserID>#UserID#</UserID>  <FName>#FName#</FName>  <LName>#LName#</LName>  </user>  </cfoutput>  </UserRecs> </cfxml> 

In this example, the tags and data are automatically converted into the appropriate XML Document Object elements in a <cfoutput> loop.

Writing specific cells is just as simple and can be performed using <cfset>, as seen here:

 <cfset menu.menu.xmlchildren[1].xmlchildren[1].xmltext="Homepage"> 

In this example, a specific element in the menu structure is being set (Home is being changed to Homepage).