Recipe 20.3.
Adding Elements to an XML Object
Problem
You want to construct an XML object
and add elements to it.
Solution
Use E4X syntax to create child elements and add
them to an XML tree. Additionally, use the insertChildBefore( ) and
insertChildAfter( )
methods for more control over how new elements are added.
Discussion
You might want to add elements to an XML object
to construct an XML data structure to pass to another application.
There are several ways to accomplish this, as discussed in
Recipe
20.2.
Adding elements to an existing XML object is
simple with E4X syntax. Use
the dot operator (.) on the XML
instance and add the element much the same way a generic property
is added to a regular Object:
// Create an XML instance to add elements to
var example:XML = <example />;
// Create a new XML node named newElement and add it to the
// example instance
example.newElement = <newElement />;
/* Displays:
<example>
<newElement/>
</example>
*/
trace( example );
In the preceding example, an XML literal is
created for an empty newElement node. This is then added
to the example instance by using the dot operator and
assigning a newElement property to the newElement
node. In this situation, the property name and the element name do
not need to be the same. However, it would be confusing if they
were not. The element name overrides the property name when adding
an XML node to an existing XML object.
You can also create a new element by creating a
property on the XML instance and assigning it a value, as
follows:
// Create an XML instance to work with
var example:XML = <example />;
// Create a new property emptyElement and assign it an empty
// string value
example.emptyElement = "";
/* Displays:
<example>
<emptyElement/>
</example>
*/
trace( example );
The preceding example demonstrates that you can
create child elements on an XML object without actually adding XML
nodes, like in the first example. Assigning an empty string value
to a new emptyElement property creates an empty element
node named emptyElement.
If you don't know the name of the element you'd
like to add, or if you want it based off of the value of a
variable, you can use the alternative bracket notation. Instead of
using the dot operator, place a string inside of brackets
([ and ]). The string is evaluated and the value
is used as the property name. This allows you to build a property
name and, consequently, an element name, dynamically:
// Create an XML instance to work with
var example:XML = <example />;
var id:int = 10;
// Create a string to incorporate the value of id in the node name
example[ "user" + id ] = "";
/* Displays:
<example>
<user10/>
</example>
*/
trace( example );
There are some cases when using the bracket
syntax is required. For example, it is perfectly legal XML to have
an element node name with a hyphen in it. Trying to create an
element name with a hyphen by using the dot operator gives a
compiler error:
example.some-element = ""; // Generates a compiler error
The hyphen has a special meaning to the
compiler; it is used to for subtraction. The preceding code snippet
is interpreted as a subtraction statement, attempting to subtract
the variable element from example.some, and then
assigning the empty string to that value. This subtraction
statement is not syntactically valid, which explains the compiler
error. Furthermore, even if the statement above would compile as
valid use of subtraction, it is not the intended behavior of
creating an element node. Using bracket notation fixes this:
example[ "some-element" ] = "";
One problem with the simplicity of E4X is that
any time a new element is added, it is always added at the end of
the XML tree. To solve this, use the insertChildBefore( )
and insertChildAfter( ) methods to have more control over
how new element nodes are added. The insertChildBefore( )
method inserts a new element before an existing element in the XML
tree, while insertChildAfter( ) inserts a new element after
an existing element. Each method takes the same two parameters: the
node marking the inserting point and the data to insert. The
following code snippet shows how to use both of these methods to
modify an XML tree:
// Create an XML instance to work with
var example:XML = <example/>;
// Create an empty two element node
example.two = "";
// Before the two element node, add a one element node
example = example.insertChildBefore( example.two, <one /> );
// After the two element node, add a three element node
example = example.insertChildAfter( example.two, <three /> );
/* Displays:
<example>
<one/>
<two/>
<three/>
</example>
*/
trace( example );
In the preceding example, note that the
insertChildBefore( ) and insertChildAfter( ) methods
do not modify the XML instance in which they are called. Instead,
they return a new instance containing the modifications. To capture
the modifications, assign the result of the method call to the XML
instance again, as the previous example shows.
See Also
Recipes 20.2
and 20.4
|