cfxml

Description

Creates a ColdFusion XML document object that contains the markup in the tag body. This tag can include XML and CFML tags. ColdFusion processes the CFML code in the tag body, and then assigns the resulting text to an XML document object variable, which is always stored in Unicode.

Category

Extensibility tags

Syntax

<cfxml 
    variable="xmlVarName"  
    caseSensitive="yes|no">
Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

See also

IsXmlDoc, IsXmlElem, IsXmlRoot, ToString, XmlChildPos, XmlNew, XmlParse, XmlSearch, XmlTransform; Using XML and WDDX in the Developing ColdFusion Applications

History

ColdFusion MX 7: Added support for using an XML declaration at the start of the text.

ColdFusion MX: Added this tag.

Attributes

Attribute

Req/Opt

Default

Description

variable

 

Name of the document object.

caseSensitive

Optional

no

  • yes: maintains the case of document elements and attributes.

  • no

Usage

If your XML object is case sensitive, you cannot use dot notation to reference an element or attribute name. Use the name in associative array (bracket) notation, or a reference that does not use the case-sensitive name (such as xmlChildren[1]) instead. In the following code, the first line works with a case-sensitive XML object. The second and third lines cause errors:

MyDoc.xmlRoot.XmlAttributes["Version"] = "12b"; 
MyDoc.xmlRoot.XmlAttributes.Version = "12b"; 
MyDoc.MyRoot.XmlAttributes["Version"] = "12b";

Use the XmlFormat function to escape special characters such as &, > and <.

To convert an XML document object back into a string, use the ToString function, at which time ColdFusion automatically prepends the <?xml version="1.0" encoding="UTF-8" ?> XML declaration.

To change the declaration to specify another encoding, use the Replace function. To specify the encoding of the text that is returned to a browser or other application, use the cfcontent tag.

The following example illustrates this process:

<cfprocessingdirective suppresswhitespace="Yes"> 
<cfcontent type="text/xml; charset=utf-16"> 
<cfxml variable="xmlobject"> 
<breakfast_menu> 
    <food> 
        <name quantity="50">Belgian Waffles</name> 
        <description>Our famous Belgian Waffles</description> 
    </food> 
</breakfast_menu> 
</cfxml> 
 
<!--- <cfdump var="#xmlobject#">---> 
 
<cfset myvar=toString(xmlobject)> 
<cfset mynewvar=replace(myvar, "UTF-8", "utf-16")> 
 
<!---<cfdump var="#mynewvar#">---> 
 
<cfoutput>#mynewvar#</cfoutput> 
</cfprocessingdirective>

The cfprocessingdirective tag prevents ColdFusion from putting white space characters in front of the XML declaration.

Example

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

<cfset testVar = True> 
<cfxml variable="MyDoc"> 
    <?xml version='1.0' encoding='utf-8' ?> 
    <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#>