ColdFusion 9.0 Resources

Using an XML object

Contents [Hide]

Referencing the contents of an XML object
Assigning data to an XML object
- Referencing the last element on the left side of an expression
- Assigning and retrieving CDATA values

Because an XML document object is represented as a structure, you can access XML document contents using either, or a combination of both, of the following ways:

Using the element names, such as mydoc.employee.name[1]
Using the corresponding structure entry names (that is, XmlChildren array entries), such as mydoc.employee.XmlChildren[1]

Similarly, you can use either, or a combination of both, of the following notation methods:

Structure (dot) notation, such as mydoc.employee
Associative array (bracket) notation, such as mydoc["employee"]

Referencing the contents of an XML object

Use the following rules when you reference the contents of an XML document object on the right side of an assignment or as a function argument:

By default, ColdFusion ignores element name case. As a result, it considers the element name MyElement and the element name myELement to be equivalent. To make element name matching case-sensitive, specify CaseSensitive="True" in the cfxml tag, or specify True as a second argument in the XmlParse or XmlNew function that creates the document object.
If your XML object is case sensitive, do not 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. For example, do not use names such as the following:
```
MyDoc.employee.name[1] 
 
MyDoc.employee.XmlAttributes.Version
```
Instead, use names such as the following:
```
MyDoc.xmlRoot.XmlChildren[1] 
MyDoc.xmlRoot["name"][1] 
MyDoc.["employee"]["name"][1] 
 
MyDoc.xmlRoot.XmlAttributes["Version"] 
MyDoc["employee"].XmlAttributes["Version"]
```
Important: Because ColdFusion always treats variable names as case-insensitive, using dot notation for element and attribute names in a case-sensitive XML document can generate unexpected results (such as all-uppercase variable names), exceptions, or both.
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.
Use an array index to specify one of multiple elements with the same name; for example, #mydoc.employee.name[1] and #mydoc.employee.name[2].

If you omit the array index on the last component of an element identifier, ColdFusion treats the reference as the array of all elements with the specified name. For example, mydoc.employee.name refers to an array of two name elements.
Use an array index into the XmlChildren array to specify an element without using its name; for example, mydoc.XmlRoot.XmlChildren[1].
Use associative array (bracket) notation to specify an element name that contains a period or colon; for example, myotherdoc.XmlRoot["Type1.Case1"].
You can use DOM methods in place of structure entry names.

For example, the following variables all reference the XmlText value “Almanzo” in the XML document created in A simple XML document:

mydoc.XmlRoot.XmlChildren[1].XmlChildren[1].XmlText 
mydoc.employee.name[1].first.XmlText 
mydoc.employee.name[1]["first"].XmlText 
mydoc["employee"].name[1]["first"].XmlText 
mydoc.XmlRoot.name[1].XmlChildren[1]["XmlText"]

The following variables all reference the EmpType attribute of the first name element in the XML document created in A simple XML document:

mydoc.employee.name[1].XmlAttributes.EmpType 
mydoc.employee.name[1].XmlAttributes["EmpType"] 
mydoc.employee.XmlChildren[1].XmlAttributes.EmpType 
mydoc.XmlRoot.name[1].XmlAttributes["EmpType"] 
mydoc.XmlRoot.XmlChildren[1].XmlAttributes.EmpType

Neither of these lists contains a complete set of the possible combinations that can make up a reference to the value or attribute.

Assigning data to an XML object

When you use an XML object reference on the left side of an expression, most of the preceding rules apply to the reference up to the last element in the reference string.

For example, the rules in Referencing the contents of an XML object apply to mydoc.employee.name[1].first in the following expression:

mydoc.employee.name[1].first.MyNewElement = XmlElemNew(mydoc, NewElement);

The rule for naming in case correct document objects, however, applies to the full reference string, as indicated by the following caution:

Important: Because ColdFusion always treats variable names as case-insensitive, using dot notation for element and attribute names in a case-sensitive XML document can generate unexpected results (such as all-uppercase variable names), exceptions, or both. In case-sensitive XML documents, use associative array notation or DOM notation names (such as XmlRoot or XmlChldren[2]).

Referencing the last element on the left side of an expression

The following rules apply to the meaning of the last component on the left side of an expression:

The component name is an element structure key name (XML property name), such as XmlComment, ColdFusion sets the value of the specified element structure entry to the value of the right side of the expression. For example, the following line sets the XML comment in the mydoc.employee.name[1].first element to “This is a comment”:
```
mydoc.employee.name[1].first.XmlComment = "This is a comment";
```
If the component name specifies an element name and does not end with a numeric index, for example mydoc.employee.name, ColdFusion assigns the value on the right of the expression to the first matching element.

For example, if both mydoc.employee.name[1] and mydoc.employee.name[2] exist, the following expression replaces mydoc.employee.name[1] with a new element named address, not an element named name:
```
mydoc.employee.name = XmlElemNew(mydoc, "address");
```
After executing this line, if there had been both mydoc.employee.name[1] and mydoc.employee.name[2], now only one mydoc.employee.name element exists with the contents of the original mydoc.employee.name[2].
If the component name does not match an existing element, the element names on the left and right sides of the expression must match. ColdFusion creates an element with the name of the element on the left of the expression. If the element names do not match, it generates an error.

For example if a, mydoc.employee.name.phoneNumber element does not exist, the following expression creates an mydoc.employee.name.phoneNumber element:
```
mydoc.employee.name.phoneNumber = XmlElemNew(mydoc, "phoneNumber");
```
The following expression causes an error:
```
mydoc.employee.name.phoneNumber = XmlElemNew(mydoc, "address");
```
If the component name does not match an existing element and the component’s parent or parents also do not exist, ColdFusion creates any parent nodes as specified on the left side and use the previous rule for the last element. For example, no mydoc.employee.phoneNumber element exists, the following expression creates a phoneNumber element containing an AreaCode element:
```
mydoc.employee.name.phoneNumber.AreaCode = XmlElemNew(mydoc, "AreaCode");
```

Assigning and retrieving CDATA values

To identify that element text is CDATA by placing it inside CDATA start and end marker information items, assign the text to the XmlCdata element, not the XmlText element. Specify CDATA because ColdFusion escapes the < and > symbols in the element text when you assign it to an XmlText entry. You can assign a value to an element’s XmlText entry or its XmlCdata entry, but not to both, as each assignment overwrites the other.

When you retrieve data from the document object, references to XmlCdata and XmlText return the same string.

The following example shows how ColdFusion handles CDATA text:

<cfscript> 
    myCDATA = "This is CDATA text"; 
    MyDoc = XmlNew(); 
    MyDoc.xmlRoot = XmlElemNew(MyDoc,"myRoot"); 
    MyDoc.myRoot.XmlChildren[1] = XmlElemNew(MyDoc,"myChildNodeCDATA"); 
    MyDoc.myRoot.XmlChildren[1].XmlCData = "#myCDATA#"; 
</cfscript> 
 
<h3>Assigning a value to MyDoc.myRoot.XmlChildren[1].XmlCdata.</h3> 
<cfoutput> 
    The type of element MyDoc.myRoot.XmlChildren[1] is: #MyDoc.myRoot.XmlChildren[1].XmlType#<br> 
    The value when output using XmlCdata is: #MyDoc.myRoot.XmlChildren[1].XmlCData#<br> 
    The value when output using XmlText is: #MyDoc.myRoot.XmlChildren[1].XmlText#<br> 
</cfoutput> 
<br> 
The XML text representation of Mydoc is: 
<cfoutput><XMP>#tostring(MyDoc)#</XMP></cfoutput> 
 
<h3>Assigning a value to MyDoc.myRoot.XmlChildren[1].XmlText.</h3> 
<cfset MyDoc.myRoot.XmlChildren[1].XmlText = "This is XML plain text"> 
<cfoutput> 
    The value when output using XmlCdata is: #MyDoc.myRoot.XmlChildren[1].XmlCData#<br> 
    The value when output using XmlText is: #MyDoc.myRoot.XmlChildren[1].XmlText#<br> 
</cfoutput> 
<br> 
The XML text representation of Mydoc is: 
<cfoutput><XMP>#tostring(MyDoc)#</XMP></cfoutput>