Adobe ColdFusion 8

Modifying a ColdFusion XML object

As with all ColdFusion structured objects, you can often use a number of methods to change the contents of an XML document object. For example, you often have the choice of using an assignment statement or a function to update the contents of a structure or an array. The following section describes the array and structure functions that you can use to modify an XML document object. The section XML document object management reference provides a quick reference to modifying XML document object contents. Later sections describe these methods for changing document content in detail.

Functions for XML object management

The following table lists the ColdFusion array and structure functions that you can use to manage XML document objects and their functions, and describes their common uses. In several cases you can use either an array function or a structure function for a purpose, such as for deleting all of an element's attributes or children.

Function

Use

ArrayLen

Determines the number of child elements in an element, that is, the number of elements in an element's XmlChildren array.

ArrayIsEmpty

Determines whether an element has any elements in its XmlChildren array.

StructCount

Determines the number of attributes in an element's XmlAttributes structure.

StructIsEmpty

Determines whether an element has any attributes in its XmlAttributes structure.

Returns True if the specified structure, including the XML document object or an element, exists and is empty.

StructKeyArray

StructKeyList

Gets an array or list with the names of all of the attributes in an element's XmlAttributes structure. Returns the names of the children of an XML element.

ArrayInsertAt

Adds a new element at a specific location in an element's XmlChildren array.

ArrayAppend

ArrayPrepend

Adds a new element at the end or beginning of an element's XmlChildren array.

ArraySwap

Swaps the children in the XmlChildren array at the specified position.

ArraySet

Sets a range of entries in an XmlChildren array to equal the contents of a specified element structure. Each entry in the array range will be a copy of the structure. Can be used to set a single element by specifying the same index as the beginning and end of the range.

ArrayDeleteAt

Deletes a specific element from an element's XmlChildren array.

ArrayClear

Deletes all child elements from an element's XmlChildren array.

StructDelete

Deletes a selected attribute from an element's XMLAttributes structure.

Deletes all children with a specific element name from an element's XmlChildren array.

Deletes all attributes of an element.

Deletes all children of an element.

Deletes a selected property value.

StructClear

Deletes all attributes from an element's XMLAttributes structure.

Duplicate

Copies an XML document object, element, or node structure.

IsArray

Returns True for the XmlChildren array. Returns false if you specify an element name, such as mydoc.XmlRoot.name, even if there are multiple name elements in XmlRoot.

IsStruct

Returns False for XML document objects, elements, and nodes. Returns True for XmlAttributes structures.

StructGet

Returns the specified structure, including XML document objects, elements, nodes, and XmlAttributes structures.

StructAppend

Appends a document fragment XML document object to another XML document object.

StructInsert

Adds a new entry to an XmlAttributes structure.

StructUpdate

Sets or replaces the value of a document object property such as XmlName, or of a specified attribute in an XmlAttributes structure.

Note: Array and structure functions not in the preceding or table or the table in the next section, do not work with XML document objects, XML elements, or XML node structures.

Treating elements with the same name as an array

In many cases an XML element has multiple children with the same name. For example, the example document used in this chapter has multiple name elements in the employee elements. In many cases, you can treat the child elements with identical names as an array. For example, to reference the second name element in mydoc.employee, you can specify mydoc.employee.name[2]. However, you can only use a limited set of Array functions when you use this notation. The following table lists the array functions that are valid for such references:

Array function

Result

IsArray(elemPath.elemName)

Always returns False.
ArrayClear(elemPath.elemName)

Removes all the elements with name elemName from the elemPath element.

ArrayLen(elemPath.elemName)

Returns the number of elements named elemName in the elemPath element.

ArrayDeleteAt(elemPath.elemName, n)

Deletes the nth child named elemlName from the elemPath element.
ArrayIsEmpty(elemPath.elemName)

Always returns False.

ArrayToList(elemPath.elemName, n)

Returns a comma separated list of all the XmlText properties of all the children of elemPath named elemName.