XML- it's here, and you have to deal with it. Whether you need to generate XML files to share data with your business partners, extract content from XML files, or transform XML into some other format...

...the ability to deal with XML has become a common requirement for ColdFusion developers in the past couple of years.

Prior to the release of ColdFusion MX, the <CFObject> tag gave developers a way to integrate ColdFusion with existing XML parsers, including COM objects from Microsoft (also known as MSXML) and Java-based libraries from Apache and other vendors. These components have powerful APIs, but their complexity has discouraged some from joining the XML "revolution." And while third-party solutions have made the processing of XML easier, CFMX now includes XML parsing and creation tools that deliver the ease of use and simplicity we expect from ColdFusion development.

This is the first of three articles describing the new functionality. In this article I'll describe the tools for parsing, extracting, and searching for data from XML. The next two articles will cover the creation of XML files and the use of XSLT (Extensible Stylesheet Language Transformation) to turn XML-formatted content into other text formats. One caveat: this article is based on prerelease software, and there may be minor changes in the final version. For complete details click on the Documentation link in the CFMX Administrator. Click on "Developing ColdFusion MX Applications with CFML," then see Chapter 30, "Using XML and WDDX."

Reading a File
XML parsing technologies can be divided into two categories: event-driven parsers such as SAX (Simple API for XML) and tree-style parsers such as DOM (Document Object Model) and JDOM. The new CFMX tools are modeled on the latter. With these parsers the entire XML file is first read into memory. The text version of the XML is then converted to an in-memory object model, which is navigable through the parser's object structure. Most tree-based parsers require you to learn the names and methods of various software objects to find and retrieve data. In CFMX the XML document is exposed as a variable that behaves in many ways like existing ColdFusion variable types. If you know how to use structures and arrays, you already know most of what you need to deal with XML.

The first step is to read the contents of the XML file into a variable. For this purpose you'll use familiar tools. If the file is available through the local file system, read it with <CFFile>:

<CFFile action="READ" variable="xml"
file="#ExpandPath('.')#\beans.xml">

If the file is on a remote server, read it with <CFHTTP>:

<CFHttp url="http://localhost/beans.xml"
method="get">
<CFSet xml=CFHTTP.FileContent>

Beans.xml is an XML version of the Beans table from Macromedia's Fast Track to ColdFusion class (www.macromedia.com/support/training). See Listing 1 for its contents.

The XML Document Object
Now comes the fun part: turning the XML file's contents into an object structure takes just one line of code. CFMX introduces a new complex variable type called an XML document object and a new function called XMLParse(), which knows how to create these new XML objects from text variables. XMLParse() takes the text value of an XML document or document fragment as its only argument and returns the resulting object. Here's the code:

<CFSet xmlDoc = XMLParse(xml)>

That's it. Now you're ready to retrieve your data. If you want to see the resulting XML document's structure, dump it to the screen with the <CFDump> tag. This debugging utility tag has been in ColdFusion since version 5.0, and has been enhanced to deal with the XML variable type. Use this code to view the structure of your XML document:

<CFDump var="#xmlDoc#">

See Figure 1 for an example of the output. Note that the CFDump output header says "xml document [short version]." There are two ways of addressing XML content. By default, <CFDump> presents the structure in shorthand (known as the "Basic" structure), the version you'll be most interested in. To see the longhand (or "DOM") model, click the <CFDump> header and the output expands significantly. Click a third time to collapse the tree completely, and again to return to the shorthand presentation.

Retrieving Data
There are two ways to address the parts of an XML document object. The first is the DOM approach. In this version the document object has a child object called XmlRoot, which references the root element of the XML file. This and every other element has a set of child objects with fixed names. The most commonly used child objects are those found in Table 1.

Examine this simple XML fragment:

<Software>
<ColdFusion version="6">J2EE
Server</ColdFusion>
</Software>

To retrieve the value of the "ColdFusion" element from the resulting xmlDoc object, the long form address would be:

xmlDoc.XmlRoot.XmlChildren[1].XmlText

To retrieve the value of the "version" attribute, the syntax would be:

xmlDoc.XmlRoot.XmlChildren[1].XmlAttributes.version

This syntax is a bit heavy, though, and presents some problems. For instance, if the XmlChildren array contains elements with different names, you'd have to loop through the array to find the element you're looking for. So CFMX also provides the shorthand (Basic) addressing system. The Basic syntax for addressing content is similar to that for getting information from a ColdFusion structure or array.

Each uniquely named element within its parent is addressed by its name, just like a structure item. If you want to get the value of the text in the uniquely named "ColdFusion" element, and you know the name of the element in advance, the value's address becomes:

xmlDoc.Software.ColdFusion.XmlText

And reading an attribute be-comes:

xmlDoc.Software.ColdFusion.XmlAttributes.version

If you don't know the names of elements or attributes in advance, replace the dot notation with array syntax, like this:

xmlDoc.Software[softwarename].XmlAttributes[attributename]

Note: While XML is a case-sensitive technology, ColdFusion follows its usual practice and exposes all element and attribute names as case-insensitive variable names.

Looping Through Elements
If there's more than one child element of the same name within a parent element, you can address them as an array of elements, where the array name matches the element name. For the Beans.xml file, output a list of coffee bean names like this:

<cfset aBean=xmlDoc.Beans.Bean>
<cfloop from="1" to="#ArrayLen(aBean)#" index="i">
<cfoutput>#aBean[i].Bean_Name.XmlText#<br></cfoutput>
</cfloop>

See Listing 2 for the CF code to output the complete XML file as a list, and Figure 2 for its output.

Searching for XML Data
Just as with relational databases, you may want to query a particular element or set of elements based on the values of their attributes or text nodes. For this purpose CFMX adds a new function called XMLSearch(), which takes two arguments: an XML document object and an XPath expression. XPath, a powerful querying language for XML structures, is implemented in many XML technologies, including XSLT, XPointer, and many XML databases.

Here's a sample XPath query that extracts a single Bean element from our beans.xml file based on the Bean element's ID attribute:

<cfset aBeans=XMLSearch(xmlBeans, "//BEAN[@ID=1]")>

This XPath pattern means: find elements named "BEAN" where the element's ID attribute value equals 1. The double-slash ("//") means the element may be anywhere in the XML hierarchy, so we don't have to drill down one level at a time. XMLSearch() returns an array of elements that match the pattern. In this example, assuming that each Bean's ID is unique, we'd get back an array with a single item: the Bean element with the ID of 1.

There's a lot more to XPath, and it's a language worthy of study. We'll cover it more thoroughly in the third article, as it's a key part of XSLT.

Once we've retrieved the array, it's a simple matter to address the name of the one bean we found:

#aBeans[1].Bean_Name.XmlText#

See Listing 3 for the CF code to output the details of a single Bean element.

Completing the Application
The two files described above, bean_list.cfm and bean_detail.cfm, display, respectively, a list of all XML elements and the detail information about a single element. The last file in the set, beans.cfm, is a control file that calls either the list or the detail view, depending on whether the user has provided a Bean ID in the URL. See Listing 4 for the code.

Limitations
The new ColdFusion XML parsing tools have some limitations:

• Figure 1
• Figure 2
• Source Code
• Figure 3