Adding, deleting, and modifying XML elements
The following sections describe the basic techniques for adding, deleting, and modifying XML elements. The example code uses the XML document described in A simple XML document.
Counting and finding the position of child elements
Often, an XML element has several children with the same name. For example, in the XML document defined in the simple XML document, the employee root element has multiple name elements.
To manipulate such an object, you often need to know the number of children of the same name, and you might need to know the position in the XmlChildren array of a specific child name that is used for multiple children. The following sections describe how to get this information.
The following user-defined function determines the number of child elements with a specific name in an element:
<cfscript>
function NodeCount (xmlElement, nodeName)
{
nodesFound = 0;
for (i = 1; i LTE ArrayLen(xmlElement.XmlChildren); i = i+1)
{
if (xmlElement.XmlChildren[i].XmlName IS nodeName)
nodesFound = nodesFound + 1;
}
return nodesFound;
}
</cfscript>
The following lines use this function to display the number of nodes named "name" in the mydoc.employee element:
<cfoutput> Nodes Found: #NodeCount(mydoc.employee, "name")# </cfoutput>
Determining the position of a child element with a common name
The XmlChildPos function determines the location in the XmlChildren array of a specific element with a common name. You use this index when you need to tell ColdFusion where to insert or delete child elements. For example, if there are several name elements in mydoc.employee, use the following code to locate name[2] in the XmlChildren array:
<cfset nameIndex = XmlChildPos(mydoc.employee, "name", 2)>
You can add an element by creating a new element or by using an existing element.
Use the XmlElemNew function to create a new, empty element. This function has the following form:
XmlElemNew(docObject, elementName)
where docObject is the name of the XML document object in which you are creating the element, and elementName is the name you are giving the new element.
Use an assignment statement with an existing element on the right side to create a new element using an existing element. See Copying an existing element for more information on adding elements using existing elements.
Adding an element using a function
You can use the ArrayInsertAt or the ArrayAppend function to add an element to an XML document object. For example, the following line adds a phoneNumber element after the last element for employee.name[2]:
<cfset ArrayAppend(mydoc.employee.name[2].XmlChildren, XmlElemNew(mydoc,
"phoneNumber"))>
The following line adds a new department element as the first element in employee. The name elements become the second and third elements.
<cfset ArrayInsertAt(mydoc.employee.XmlChildren, 1, XmlElemNew(mydoc,
"department"))>
You must use the format parentElement.XmlChildren to specify the array of elements to which you are adding the new element. For example, the following line causes an error:
<cfset ArrayInsertAt(mydoc.employee.name, 2, XmlElemNew(mydoc, "PhoneNumber")>
If you have multiple child elements with the same name, and you want to insert a new element in a specific position, use the function to determine the location in the XmlChildren array where you want to insert the new element. For example, the following code determines the location of mydoc.employee.name[1] and inserts a new name element as the second name element:
<cfscript>
nameIndex = XmlChildPos(mydoc.employee, "name", 1);
ArrayInsertAt(mydoc.employee.XmlChildren, nameIndex + 1, XmlElemNew(mydoc,
"name"));
</cfscript>
Using a namespace: When you use a function to add an element, you can assign the element to a namespace by including the namespace prefix in the element name. If you have not yet associated the prefix with a namespace URI, you must also include a parameter with the namespace URI in the XmlElemNew function. This parameter must be the second parameter in the method, and the element name must be the third parameter. ColdFusion then associates the namespace prefix with the URI, and you can omit the URI parameter in further xmlElemNew functions.
The following example adds two to the supplies document root two elements in the Prod namespace. The first XmlElemNew function use sets the association between the Prod namespace prefix and the URI; the second use only needs to specify the prefix on the element name.
<cfscript>
mydoc.supplies.XmlChildren[1] = XmlElemNew(mydoc,
"http://www.foo.com/Products", "Prod:soap");
mydoc.supplies.XmlChildren[2] = XmlElemNew(mydoc, "Prod:shampoo");
</cfscript>
Adding an element using direct assignment
You can use direct assignment to append a new element to an array of elements. You cannot use direct assignment to insert an element into an array of elements.
When you use direct assignment, you can specify on the left side an index into the XmlChildren array greater than the last child in the array. For example, if there are two elements in mydoc.employee, you can specify any number greater than two, such as mydoc.employee.XmlChildren[6]. The element is always added as the last (in this case, third) child.
For example, the following line appends a name element to the end of the child elements of mydoc.employee:
<cfset mydoc.employee.XmlChildren[9] = XmlElemNew(mydoc, "name")>
If the parent element does not have any children with the same name as the new child, you can specify the name of the new node or the left side of the assignment. For example, the following line appends a phoneNumber element to the children of the first name element in mydoc.employee:
<cfset mydoc.employee.name[1].phoneNumber = XmlElemNew(mydoc, "phoneNumber")>
You cannot use the node name on the left to add an element with the same name as an existing element in the parent. For example, if mydoc.employee has two name nodes, the following line causes an error:
<cfset mydoc.employee.name[3] = XmlElemNew(mydoc, "name")>
However, the following line does work:
<cfset mydoc.employee.XmlChilren[3] = XmlElemNew(mydoc, "name")>
You can add a copy of an existing element elsewhere in the document. For example, if there is a mydoc.employee.name[1].phoneNumber element, but no mydoc.employee. name[2].phoneNumber, the following line creates a new mydoc.employee. name[2]. phoneNumber element with the same value as the original element. This assignment copies the original element. Unlike with standard ColdFusion structures, you get a true copy, not a reference to the original structure. You can change the copy without changing the original.
<cfset mydoc.employee.name[2].phoneNumber = mydoc.employee.name[1].phoneNumber>
When you copy an element, the new element must have the same name as the existing element. If you specify the new element by name on the left side of an assignment, the element name must be the same as the name on the right side. For example, the following expression causes an error:
<cfset mydoc.employee.name[2].telephne = mydoc.employee.name[1].phoneNumber>
There are many ways to delete individual or multiple elements.
Use the ArrayDeleteAt function to delete a specific element from an XML document object. For example, the following line deletes the second child element in the mydoc.employee element:
<cfset ArrayDeleteAt(mydoc.employee.XmlChildren, 2)>
If an element has only one child element with a specific name, you can also use the StructDelete function to delete the child element. For example, the following line deletes the phoneNumber element named in the second employee.name element:
<cfset StructDelete(mydoc.employee.name[2], "phoneNumber")>
When there are multiple child elements of the same name, you must specify the element position, either among the elements of the same name, or among all child elements. Fore example, you can use the following line to delete the second name element in mydoc.employee:
<cfset ArrayDeleteAt(mydoc.employee.name, 2)>
You can also determine the position in the XmlChildren array of the element you want to delete and use that position. To do so, use the XmlChildPos function. For example, the following lines determine the location of mydoc.employee.name[2] and delete the element:
<cfset idx = XmlChildPos(mydoc.employee, "name", 2)> <cfset ArrayDeleteAt(mydoc.employee.XmlChildren, idx)>
If an element has multiple children with the same name, use the StructDelete function or ArrayClear function with an element name to delete all of an element's child elements with that name. For example, both of the following lines delete all name elements from the employee structure:
<cfset StructDelete(mydoc.employee, "name")> <cfset ArrayClear(mydoc.employee.name)>
Use the StructDelete or ArrayClear function with XmlChildren to delete all of an element's child elements. For example, each of the following lines deletes all child elements of the mydoc.employee.name[2] element:
<cfset StructDelete(mydoc.employee.name[2], "XmlChildren")> <cfset ArrayClear(mydoc.employee.name[2].XmlChildren)>
Adding, changing, and deleting element attributes
You modify an element's attributes the same way you change the contents of any structure. For example, each of the following lines adds a Status attribute the second mydoc.employee.name element:
<cfset mydoc.employee.name[2].XmlAttributes.Status="Inactive"> <cfset StructInsert(mydoc.employee.name[2].XmlAttributes, "Status", "Inactive")>
To change an attribute, use a standard assignment statement; for example:
<cfset mydoc.employee.name[2].XmlAttributs.Status="Active">
To delete an attribute, use StructDelete; for example:
<cfset StructDelete(mydoc.employee.name[1].XmlAttributes, "Status")>
To change an element's properties, including its text and comment, use a standard assignment expression. For example, use the following line to add "in the MyCompany Documentation Department" to the mydoc.employee XML comment:
<cfset mydoc.employee.XmlComment = mydoc.employee.XmlComment & "in the MyCompany Documentation Department">
The XML DOM does not support changing an element name directly. To change the name of an element, you must create a new element with the new name, insert it into the XML document object before or after the original element, copy all the original element's contents to the new element, and then delete the original element.
Clearing an element property value
To clear an element property value, either assign the empty string to the property or use the StructDelete function. For example, each of the following lines clears the comment string from mydoc.employee:
<cfset mydoc.employee.XmlComment = ""> <cfset StructDelete(mydoc.employee, "XmlComment")>
Replacing or moving an element
To replace an element with a new element, use a standard replacement expression. For example, to replace the mydoc.employee.department element with a new element named organization, use either of the following lines:
<cfset mydoc.employee.department = XmlElemNew(mydoc, "Organization")> <cfset mydoc.employee.XmlChildren[1] = XmlElemNew(mydoc, "Organization")>
To replace an element with a copy of an existing element, use the existing element on the right side of an expression. For example, the following line replaces the phoneNumber element for mydoc.employee.name[2] with the phoneNumber element from mydoc.employee.name[1]:
<cfset mydoc.employee.name[2].phoneNumber=mydoc.employee.name[1].phoneNumber>
This creates a true copy of the name[1].phoneNumber element as name[2].phoneNumber.
To move an element, you must assign it to its new location, then delete it from its old location. For example, the following lines move the phoneNumber element from mydoc.employee.name[1] to mydoc.employee.name[2]:
<cfset mydoc.employee.name[2].phoneNumber=mydoc.employee.name[1].phoneNumber> <cfset StructDelete(mydoc.employee.name[1], "phoneNumber")>