ColdFusion represents an XML document as an object, called an XML document object, that is much like a standard ColdFusion structure. In fact, most ColdFusion structure functions, such as StructInsert
, work with XML document objects. For a full list of ColdFusion functions that work on XML document objects, see "Functions for XML object management".
You can look at the overall structure of an XML document in two ways: a basic view and a DOM (Document Object Model)-based node view. The basic view presents all the information in the document, but does not separate the data into as fine-grained units as the node view. ColdFusion can access XML document contents using either view.
The next sections describe the basic and node views of the following simple XML document. This document is used in many of the examples in this chapter.
<?xml version="1.0" encoding="UTF-8"?>
<employee> <!-- A list of employees --> <name EmpType="Regular"> <first>Almanzo</first> <last>Wilder</last> </name> <name EmpType="Contract"> <first>Laura</first> <last>Ingalls</last> </name> </employee>
The basic view of an XML document object presents the object as a container that holds one root element structure. The root element can have any number of nested element structures. Each element structure represents an XML tag (start tag/end tag set) and all its contents; it can contain additional element structures. A basic view of the simple XML document looks like the following:
The DOM node view presents the XML document object using the same format as the document's XML Document Object Model (DOM). In fact, an XML document object is a representation of a DOM object.
The DOM is a World Wide Web Consortium (W3C) recommendation (specification) for a platform- and language-neutral interface to dynamically access and update the content, structure, and style of documents. ColdFusion conforms to the DOM Level 2 Core specification, available at http://www.w3.org/TR/DOM-Level-2-Core.
In the DOM node view, the document consists of a hierarchical tree of nodes. Each node has a DOM node type, a node name, and a node value. Node types include Element, Comment, Text, and so on. The DOM structures the document object and each of the elements it contains into multiple nodes of different types, providing a finer-grained view of the document structure than the basic view. For example, if an XML comment is in the middle of a block of text, the DOM node view represents its position in the text while the basic view does not.
ColdFusion also allows you to use the DOM objects, methods, and properties defined in the W3C DOM Level 2 Core specification to manipulate the XML document object.
For more information on referencing DOM nodes, see "XML DOM node structure". This document does not cover the node view and using DOM methods and properties in detail.
An XML document object is a structure that contains a set of nested XML element structures. The following figure shows the output of a cfdump
tag that displays the document object for the XML in "A simple XML document". The following figure shows the output of the cfdump
tag:
The following code displays this output. It assumes that you save the code in a file under your web root, such as C:\Inetpub\wwwroot\testdocs\employeesimple.xml
<cffile action="read" file="C:\Inetpub\wwwroot\testdocs\employeesimple.xml" variable="xmldoc">
<cfset mydoc = XmlParse(xmldoc)> <cfdump var="#mydoc#">
At the top level, the XML document object has the following three entries:
Each XML element has the following entries:
The following table lists the contents of an XML DOM node structure:
Note: The cfdump
tag does not display XmlNode structures. If you try to dump an XmlNode structure, the cfdump
tag displays "Empty Structure".
The following table lists the contents of the XmlName and XmlValue fields for each node type that is valid in the XmlType entry. The node types correspond to the objects types in the XML DOM hierarchy.
Note: Although XML attributes are nodes on the DOM tree, ColdFusion does not expose them as XML DOM node data structures. To view an element's attributes, use the element structure's XMLAttributes structure.
The XML document object and all its elements are exposed as DOM node structures. For example, you can use the following variable names to reference nodes in the DOM tree created from the XML example in "A simple XML document":
mydoc.XmlName
mydoc.XmlValue mydoc.XmlRoot.XmlName mydoc.employee.XmlType mydoc.employee.XmlNodes[1].XmlType