Recipe 19.4 Adding Text Nodes to an XML Object

19.4.1 Problem

You want to add text nodes to an XML object.

19.4.2 Solution

Use the createTextNode( ) and appendChild( ) methods.

19.4.3 Discussion

The createTextNode( ) method is very similar to the createElement( ) method discussed in Recipe 19.3, except that it creates a new text node instead of an XML element. As with the createElement( ) method, the createTextNode( ) method does not insert the node into the XML object hierarchy but returns a reference to the newly created node. You are responsible for inserting the text node into the XML object using the appendChild( ) or insertBefore( ) method.

// Create an XML object.
my_xml = new XML(  );

// Create an element to which to add the text node.
myElement = my_xml.createElement("myFirstElement");

// Create the next node with the value "this is some text".
myTextNode = my_xml.createTextNode("this is some text");

// Add the text node to the element.
myElement.appendChild(myTextNode);

// Add the element to the XML object
my_xml.appendChild(myElement);

// Displays: <myFirstElement>this is some text</myFirstElement>
trace(my_xml);

Generally, text nodes are not of much use in isolation. Remember, XML data is structured. That means that your text nodes should always be nested in XML elements such as the <myFirstElement> node in the preceding example. Therefore, we first create the element using the createElement( ) method (see Recipe 19.3). We then create the text node and assign it a value of "this is some text"—both accomplished using the createTextNode( ) method. Neither of the two nodes (the element nor the text node) has been added to the XML object, so we use the appendChild( ) method to nest these nodes. We nest the text node in the element, and we nest the element in the XML object as the root node.

The appendChild( ) method is valid for all XMLNode objects, including text nodes. However, text nodes cannot contain nested nodes; therefore, calling appendChild( ) from a text node has no effect.

It might seem strange to have to create a text node as a separate node from its parent element. After all, you may wonder why we don't just assign the text value to a property of the element instead. The answer is that XML can be more complex than that solution would allow. Consider, for a moment, a mixed element, which is an element that contains not only a child text node or child elements, but both. For example:

<article>
<title>XML: It's Not Just for Geeks</title>
<author>Samuel R. Shimowitz</author>
My friends couldn't believe it when I started working with XML. I became an
outcast, confined to my dark office illuminated only by the glow of my trusty CRT.
Blah blah blah.
</article>

In this example, <article> is a mixed element because it contains not only nested elements (<title> and <author>) but also a nested text node. This is perfectly valid XML, and for this reason, we want to be able to treat each nested item as its own node.

When working with text nodes, it can be convenient to create the text node and the parent element all in one step. You can automate this process with a short and simple custom method, createElementWithText( ). Add this method to the XMLNode class by placing the following code in a custom XML.as file that you place in your Flash Include directory for easy inclusion in future projects. The method accepts two parameters: the name of the element and the value to add to the nested text node.

XMLNode.prototype.createElementWithText = function (name, text) {

  // Create the element.
  var elem = this.createElement(name);

  // Create the text node.
  var txtNode = this.createTextNode(text);

  // Add the text node to the element.
  elem.appendChild(txtNode);

  // Return the element.
  return elem;
};

Here is an example of the createElementWithText( ) method in use:

#include "XML.as"

my_xml = new XML(  );
myElement = my_xml.createElementWithText("where", "here");
my_xml.appendChild(myElement);
trace(my_xml);  // Displays: <where>here</where>

Notice that the createElementWithText( ) method returns a new XMLNode object just like the createElement( ) and createTextNode( ) methods. This means that you need to add it to an XML object using a method such as appendChild( ).

19.4.4 See Also

Recipe 19.3