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.
You can use the ArrayInsertAt or ArrayAppend functions 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 XmlChildPos 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>
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>