Creating and saving an XML document object



You can use several methods to create and save an XML document object. The specific technique that you use depends on the application and your coding style.

Creating an 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 XmlParse function.

Creating an XML document object using the XmlNew function

The XmlNew function creates an 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 an 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, also specify whether the document is 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#">