On line 31 we are setting a local variable xnItem to each item of the XmlChildren Array. As you may have noticed, XML notation can get long. You can use variables like this to shorten references to your XML Elements. This makes the code a little more human-readable and a lot easier to maintain.

Lines 33-36 use the same techniques as above to reference the information in the XML Document. Note that the Item ID is an attribute, while the other pieces of information are Child elements. These child elements refer to a variable called XmlText. All XML Elements have two property variables: XmlName and XmlText. XmlName always contains the name of the element (or tag), while XmlText is the text between the opening and closing tags that isn't inside any other elements. So for an Xml Element like "<material>wood</material>," XmlName would be "material" and XmlText would be "wood." Applying this to our example, XmlOrder.xmlroot.XmlName would be "order."

Creating New XML Documents
So far the only XML-specific ColdFusion tag we've used is XmlParse(). I highlight this to emphasize the point that once you parse your XML into an XML Object, it is basically a ColdFusion structure of arrays and structures, and you don't really need any more XML-specific tags or functions to read the data.

Now, let's move on to creating new XML documents. There are a few ways to do this. The first way - which some consider to be "cheating" - is fast and easy.

You can simply hand-code your XML in a CFML document and wrap <cfsavecontent> tags around it (see Listing 4). This is extremely easy because you can drop in your own variables and any other CFML you want right inline with your XML. Note that with this method, you're basically hand-creating a string, which has to be parsed in an XML Object.

You can also use the <cfxml> tag, which works pretty much the same, except that instead of ending up with a string, you get the XML Object without having to call XmlParse() (see Listing 5).

Functionally there's not too much difference between these methods, both are quick and dirty and get the job done.

Now, here's the programmatic way to create a new XML Document:

   <cfset myXml = XmlNew()>
   <cfset myXml.xmlroot = XmlElemNew(myXml,"collection")>

The first line creates a new empty XML Object. The second line creates a new XML Element and assigns it to the xmlroot of your XML Object. Note that XmlElemNew() takes two parameters: the first is the XML Object, and the second is the name of the element you're creating. Try doing a <cfdump var="#myXml#"> and look at the results. Note that when the XML Object is created, it's already a ColdFusion object, not a plain text format. If you want to see what the XML looks like in its text format, try doing a <cfdump var="#toString(myXml)#">.

Now lets add an attribute to our new XML Element.

   <cfset myXml.xmlroot.XmlAttributes.name = "My CDs">

Remember that XmlAttributes is a struct, so you can also use any of ColdFusion's struct functions here, such as StructInsert or StructUpdate.

Now let's create a new element for our CD Collection and give it some attributes:

   <cfset xnCD = XmlElemNew(myXml,"cd")>

Here we're creating an XML Element that isn't attached to the XML Document right now. If you did a <cfdump var="#myXml#">, you wouldn't see this new element appear in myXml anywhere.

The technique of creating "unattached" XML elements is an important technique to understand. When we create an XML Element, we can refer to it with its short variable name and manipulate it as much as we want, including adding attributes and child elements to its XmlChildren array.

Let's add a few attributes to our xnCD element:

   <cfset xnCD.XmlAttributes.title = "The best of Billy Joel">
   <cfset xnCD.XmlAttributes.cover = "billjoel_best.jpg">
   <cfset xnCD.XmlAttributes.genre = "Easy Listening">

Now that we have added some attributes, take a look at your XML Element by doing a <cfdump var="#xnCD#"> and make sure that the values you expected show up properly.

Once you're happy with this element, let's plug it into the XML Document. If you remember, I mentioned earlier that each XML Element has a property called XmlChildren, which is an array of XML Elements. Since it's an array, let's use ColdFusion's ArrayAppend() function to add our new element to the XML Document.

   <cfset ArrayAppend(myXml.xmlroot.XmlChildren,xnCD)>

Now let's take a look at the XML Object by doing a <cfdump var="#myXml#"> and see that our xnCD Element has been added to our XML Document, and now appears in XMLChildren under collection. This technique of assembling XML elements and then "plugging them into" the XML Document is a structured and reliable way for you to programmatically build XML Documents. You can use queries and loop constructs to build XML from database results or from FORM data and ensure that the resulting XML is well formed. As an exercise, try adding some "audio track" XML elements to the above CD by creating new XML elements and appending them to xnCD.XmlChildren before adding it to your XML Document.

Now that we're done creating our XML Document, getting the actual XML Text is as simple as calling ColdFusion's toString() function. So to write the XML to a local file we could do:

<cffile action="write" file="#ExpandPath(".")
#/collection.xml" output="#tostring(myXml)#">

Validating XML Documents
The examples we worked with so far are very basic, and most of us will work with much more complex data. So what happens when we have XML data that may not be valid (see the definition earlier), or even worse, what if it's not well formed? (again reference above).

When you try to parse an XML document, occasionally there will be problems, specifically if the document itself is not well formed. Unfortunately the error you receive is not always very user-friendly such as "An error occurred while parsing an XML document."