Adobe ColdFusion 8

Creating and saving an XML document object

The following sections show the ways you can create and save an XML document object. The specific technique that you use will depend on the application and your coding style.

Creating a new XML document object using the cfxml tag

The cfxml tag creates an XML document object that consists of the XML markup in the tag body. The tag body can include CFML code. ColdFusion processes the CFML code and includes the resulting output in the XML. The following example shows a simple cfxml tag:

<cfset testVar = True>
<cfxml variable="MyDoc">
    <MyDoc>
        <cfif testVar IS True>
            <cfoutput>The value of testVar is True.</cfoutput>
        <cfelse>
            <cfoutput>The value of testVar is False.</cfoutput>
        </cfif>
        <cfloop index = "LoopCount" from = "1" to = "4">
            <childNode>
                This is Child node <cfoutput>#LoopCount#.</cfoutput>
            </childNode>
        </cfloop>
    </MyDoc>
</cfxml>
<cfdump var=#MyDoc#>

This example creates a document object with a root element MyDoc, which includes text that displays the value of the ColdFusion variable testVar. MyDoc has four nested child elements, which are generated by an indexed cfloop tag. The cfdump tag displays the resulting XML document object.

Note: When you use the cfxml tag, do not include an <?xml ?> processing directive in the tag body. This directive is not required, and causes an error. To process XML text that includes the <?xml ?> directive, use the function.

Creating a new XML document object using the XmlNew function

The XmlNew function creates a new XML document object, which you must then populate. For information on how to populate a new XML document, see Adding, deleting, and modifying XML elements.

Note: You cannot set the XmlDocType property for an XML document object that you create with the XmlNew function.

The following example creates and displays the same ColdFusion document object as in Creating a new XML document object using the cfxml tag. 

<cfset testVar = True>
<cfscript>
    MyDoc = XmlNew();
    MyDoc.xmlRoot = XmlElemNew(MyDoc,"MyRoot");
    if (testVar IS TRUE)
        MyDoc.MyRoot.XmlText = "The value of testVar is True.";
    else 
        MyDoc.MyRoot.XmlText = "The value of testVar is False.";
    for (i = 1; i LTE 4; i = i + 1)
        {
        MyDoc.MyRoot.XmlChildren[i] = XmlElemNew(MyDoc,"childNode");
        MyDoc.MyRoot.XmlChildren[i].XmlText = "This is Child node " & i &".";
        }
</cfscript>
<cfdump var=#MyDoc#>

Creating an XML document object from existing XML

The XmlParse function converts an XML document or document fragment represented as text into a ColdFusion document object. You can use a string variable containing the XML or the name or URL of a file that contains the text. For example, if your application uses cfhttp action="get" to get the XML document, use the following line to create the XML document object:

<cfset myXMLDocument = XmlParse(cfhttp.fileContent)>

The following example converts an XML text document in a file to an XML document object:

<cfset myXMLDocument=XmlParse("C:\temp\myxmldoc.xml" variable="XMLFileText")>

The XmlParse function takes a second, optional, attribute that specifies whether to maintain the case of the elements and attributes in the document object. The default is to have the document object be case-insensitive. For more information on case-sensitivity, see Referencing the contents of an XML object.

The XmlParse function also lets you specify a DTD or Schema to validate the XML text; if the XML is not valid, ColdFusion generates an error. You can specify the filename or URL of the validator, or the DTD or Schema can be in a CFML variable. You can also tell ColdFusion to use a DTD or Schema that is identified in the XML text. If you specify validation, you must also specify whether the document is be case-sensitive. The following example validates an XML document on file using a DTD that it specifies using a URL:

myDoc=XMLParse("C:\CFusion\wwwroot\examples\custorder.xml", false,
        "http://localhost:8500/examples/custorder.dtd")>

Saving and exporting an XML document object

The ToString function converts an XML document object to a text string. You can then use the string variable in any ColdFusion tag or function.

To save the XML document in a file, use the ToString function to convert the document object to a string variable, then use the cffile tag to save the string as a file. For example, use the following code to save the XML document myXMLDocument in the file C:\temp\myxmldoc.xml:

<cfset XMLText=ToString(myXMLDocument)>
<cffile action="write" file="C:\temp\myxmldoc.xml" output="#XMLText#">