Converts XML text into an XML document object.

An XML document object.

Conversion functions, XML functions

XmlParse(xmlText [[, caseSensitive ], validator])

cfxml, IsXML, ToString, XmlFormat, XmlNew, XmlSearch, XmlTransform, XmlValidate; Chapter 35, "Using XML and WDDX" in ColdFusion MX Developer's Guide

ColdFusion MX 7:

• Added the validator parameter.
• Added support for filenames and URLs in the xmlText parameter.
• Added support for relative URLs and path names.

ColdFusion MX: Added this function.

If you specify a relative URL or path name in a parameter, ColdFusion uses the directory (or, for URLs, the logical directory) that contains the current ColdFusion page as the path root.

The caseSensitive parameter value determines whether identifiers whose characters are of varying case, but are otherwise the same, refer to different components; for example:

• If true, the element or attribute names "name" and "NAME" refer to different elements or attributes.
• If false, these names refer to the same elements or attributes.

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. In the following code, the first line will work with a case-sensitive XML object. The second and third lines cause errors:

MyDoc.xmlRoot.XmlAttributes["Version"] = "12b";
MyDoc.xmlRoot.XmlAttributes.Version = "12b";
MyDoc.MyRoot.XmlAttributes["Version"] = "12b";

The optional validator parameter specifies a DTD or Schema to use to validate the document. If the parser encounters a validation error, ColdFusion generates an error and stops parsing the document. You must specify a validator parameter to make the XmlParse function validate your document. If you do not specify a validator parameter, and the XML file specifies a DTD or Schema, ColdFusion ignores the DTD or Schema. If you specify a validator parameter, you must also specify a caseSensitive parameter.

If you do not specify a validator parameter, the xmlText parameter can specify a well-formed XML fragment, and does not have to specify a complete document.

The following example has three parts: an XML file, a DTD file, and a CFML page that parses the XML file and uses the DTD for validation. The CFML file displays the returned XML document object. To show the results of invalid XML, modify the bmenuD.xml.

The custorder.xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE order SYSTEM "C:\CFusionMX7\wwwroot\examples\custorder.dtd">
<order id="4323251">
   <customer firstname="Philip" lastname="Cramer" accountNum="21"/>
   <items>
      <item id="43">
         <name>   Deluxe Carpenter&apos;s Hammer</name>
         <quantity>1</quantity>
         <unitprice>15.95</unitprice>
      </item>
      <item id="54">
         <name>   36&quot; Plastic Rake</name>
         <quantity>2</quantity>
         <unitprice>6.95</unitprice>
      </item>
      <item id="68">
         <name>   Standard paint thinner</name>
         <quantity>3</quantity>
         <unitprice>8.95</unitprice>
      </item>
   </items>
</order>

The custorder.dtd file is as follows:

<!ELEMENT order (customer, items)>
<!ATTLIST order
   id CDATA #REQUIRED>
<!ELEMENT customer EMPTY>
<!ATTLIST customer
   firstname CDATA #REQUIRED
   lastname CDATA #REQUIRED
   accountNum CDATA #REQUIRED>
<!ELEMENT items (item+)>
<!ELEMENT item (name, quantity, unitprice)>
<!ATTLIST item 
   id CDATA #REQUIRED>
<!ELEMENT name (#PCDATA)>
<!ELEMENT quantity (#PCDATA)>
<!ELEMENT unitprice (#PCDATA)>

The CFML file is as follows. It uses a filename for the XML file and a URL for the DTD. Note that the XML and URL paths must be absolute.

<cfset
myDoc=XMLParse("C:\CFusionMX7\wwwroot\examples\custorder.xml",
false, "http://localhost:8500/examples/custorder.dtd")>
Dump of myDoc XML document object<br>
<cfdump var="#myDoc#">