| XML.parseXML( ) Method | Flash 5 |
| parse a string of XML source code |
A string of XML source code.
The parseXML( ) method reads and parses the XML source contained by string, converts that source into an object hierarchy, and then places the resulting hierarchy into xmlDoc. Any previous contents of xmlDoc are replaced by the new hierarchy. The specified xmlDoc must be the top-level node in an XML object hierarchy (i.e., an instance of the XML class, not the XMLnode class). Once parsing is complete, the success of the operation can be determined via xmlDoc.status.
To include raw HTML or XML source code in a text node without parsing it, use a CDATA section as follows:
<![CDATA[ source ]]>
For example, the following code creates a MESSAGE element with a single child text node containing the text "<B>Welcome</B> to my site" (the <B> tag is not interpreted as an XML tag and does not become part of the XML object hierarchy):
myDoc = new XML();
myDoc.parseXML("<MESSAGE><![CDATA[<B>Welcome</B> to my site]]></MESSAGE>");
Note that a CDATA section is interpreted as a node, so the following <P> element actually has three child nodes � a text node, a CDATA node, and another text node:
<P>The following source: <![CDATA[<B>Welcome</B> to my site]]> adds bold.</P>
However, in ActionScript, only text nodes and element nodes are supported, so this CDATA section is converted to a text node with a nodeType of 3 (text node), not 4 (CDATA section node). Once the original CDATA source code is parsed, it is not recoverable from the XML object hierarchy.
Regarding the use of the characters & and < in character data, the W3C XML 1.0 specification states:
"The ampersand character (&) and the left angle bracket (<) may appear in their literal form only when used as markup delimiters, or within a comment, a processing instruction, or a CDATA section. If they are needed elsewhere, they must be escaped using either numeric character references or the strings `&' and `<' respectively."[13]
[13] From "2.4 Character Data and Markup,"http://www.w3.org/TR/2000/REC-xml-20001006#syntax
For example, to include the code "<P>We know that (10<11) is true.</P>" in an XML document, we must use the < entity:
<P>We know that (10<11) is true.</P>
or a CDATA section:
<P>We know that<![CDATA[ (10<11) ]]>is true.</P>
As of version 5.0.41.0 (5.0.42.0 on Internet Explorer), when Flash parses XML source containing a text node with the characters >, ", ', or &, it automatically converts them to the predefined entities >, ", ', and &. For example, in the following sample, the ' character becomes ':
// Apostrophe character is automatically converted to an entity
var doc = new XML("<p>don't worry</p>");
// Displays: "don't worry"
trace(doc.firstChild.firstChild.toString());
In contrast, a predefined entity in a text node is not changed during parsing. For example, when & is parsed it stays & � it is not converted to & or even &amp;. However, when a predefined entity appears in a CDATA section, the initial ampersand is converted (that is, & does become &amp;). Therefore, literal characters, not entities, should always be used in CDATA.
The less-than character (<) is converted to < only when it appears in a CDATA section. Elsewhere, it must be written as < to prevent a parsing error.
When the nodeValue of a text node is read, the predefined entities <, >, ", ', and & are automatically converted back to their corresponding characters:
var doc = new XML("<p>don't worry</p>");
// Displays: "don't worry"
trace(doc.firstChild.firstChild.nodeValue);
Note the difference: XML.toString( ) of a text node returns the raw XML source of the node, with entities left in entity form; XML.nodeValue returns interpreted text suitable for output, with predefined entities converted to literal characters. For example:
doc = new XML("<P><![CDATA[what a 'nice' day]]></P>");
// Displays: "what a 'nice' day"
trace(doc.firstChild.firstChild.toString());
// Displays: "what a 'nice' day"
trace(doc.firstChild.firstChild.nodeValue);
Note that in Flash 6, a carriage return in an attribute value causes a parsing error of status -8 (attribute not terminated). For loaded XML, offending returns can be replaced manually inside the onData( ) handler.
We can use parseXML( ) as a means of replacing the current object hierarchy in an XML object with a new hierarchy based on internally composed XML source code (for example, some user input). In the following example, we create a simple XML message by combining markup with input from text fields named username_txt and content_txt:
myDoc = new XML();
myXMLsource = "<MESSAGE><USER>" + username_txt + "</USER><CONTENT>"
+ content_txt + "</CONTENT></MESSAGE>";
myDoc.parseXML(myXMLsource);
XML.ignoreWhite, XML.load( ), XML.nodeValue, XML.onData( ), XML.status, XML.toString( )