Using the XML Parser

One of more powerful features of ASDK is a very easy to use XML parser that also includes support for XML namespaces, a feature absent from the standard XML API that ships with Flash. Working with XML using ASDK provides a more natural experience by surfacing a clean object oriented API of an XML document. This API includes common classes such as Document, Element, and Attribute along with several supporting classes within the asdk.xml package. More details regarding ASDKs support for XML is discussed in the XML Parser section of the guide.

Loading and Parsing an XML document

ASDK provides a single class for parsing XML documents: asdk.xml.Document. To parse an XML document use the following API:

var doc:Document = new asdk.xml.Document( doc );

where the doc argument can be either a string or native ActionScript XML document. To load and parse a document from a URL use the following API:

var doc:Document = asdk.xml.Document.load( docURL:String, callBack:Function );

where the docURL argument is a URL where the document is loaded from, and the callback argument is a reference to an ActionScript function to be called when the document is parsed.

Navigating XML object model

To navigate through the ASDK Document object model it is necessary to obtain the document root element using the following API:

var rootElement = doc.getRoot();

where the doc object is an instance of the asdk.xml.Document class. The object returned by the getRoot() function is an instance of asdk.xml.Element. The Element class is the core of the ASDK XML parser. It represents a node in a document and provides access to the data contained in the node, its attributes and children elements. Consider the following XML document:

<?xml version="1.0" ?>
<Employee>
   <EmployeeName>James Bond</EmployeeName>
   <EmployeeID>007</EmployeeID>
   <Title>VP of Intelligence<Title>
</Employee>

The example below demonstrates how to use the API to parse the document shown above:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import asdk.*;
import asdk.xml.*;

var xmlUrl = "http://www.themidnightcoders.com/asdk/jamesbond.xml";
Document.load( xmlUrl, documentLoaded );

function documentLoaded( document )
{
   var element:Element = document.getRoot();
   trace( "root element name is - " + element.getName() );

   trace( "employee name is - " + element.getString( "EmployeeName" ) );
   trace( "employee id is - " + element.getString( "EmployeeID" ) );
   trace( "employee title is - " + element.getString( "Title" ) );
}

Flash movie with source code

The getString function (lines 12, 13, 14) is an example of the ease-of-use APIs ASDK offers. The function retrieves text contained in a node with the given name. Alternatively, the same text can be obtained using the API below:

element.getElement( elementName ).getString()

Where element is an instance of the asdk.xml.Element class and elementName is the name of an element. The example above can be rewritten to use the getElement function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import asdk.*;
import asdk.xml.*;

var xmlUrl = "http://www.themidnightcoders.com/asdk/jamesbond.xml";
Document.load( xmlUrl, documentLoaded );

function documentLoaded( document )
{
   var element:Element = document.getRoot();
   trace( "root element name is - " + element.getName() );

   var nameElement = element.getElement( "EmployeeName" );
   trace( "employee name is - " + nameElement.getString() );

   var idElement = element.getElement( "EmployeeID" );
   trace( "employee id is - " + idElement.getString() );

   var titleElement = element.getElement( "Title" );
   trace( "employee title is - " + titleElement.getString() );
}

Flash movie with source code

Both examples produce the following output:

root element name is - Employee
employee name is - James Bond
employee id is - 007
employee title is - VP of Intelligence

Element iterator

ASDK also provides a convenient method for iterating over a collection of elements. An Element can provide an iterator for all child elements or all child elements with a given name. Consider the following XML document:

<?xml version="1.0" ?>
<Contacts>
   <Email>JamesBond@007.com</Email>
   <Email>JamesBond@yahoo.com</Email>
   <Email>JamesBond@gmail.com</Email>
   <Phone>(888)SPYS-R-US<Phone>
   <Phone>(972)555-1212<Phone>
</Contacts>

The example below loads the document, obtains an iterator for all Email elements and prints them out:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import asdk.*;
import asdk.xml.*;

var xmlUrl = "http://www.themidnightcoders.com/asdk/contacts.xml";
Document.load( xmlUrl, documentLoaded );

function documentLoaded( document )
{
   var element:Element = document.getRoot();
   var emailIterator:Elements = element.getElements( "Email" );

   while( emailIterator.hasNext() )
   {
      var emailElement = emailIterator.getNext();
      trace( "email - " + emailElement.getString() );
   }
}

Flash movie with source code

The code obtains an iterator for all Email elements on line 10. The code on lines 12-16 uses the iterator and prints out text for each element (line 15).

Complete example

The example below demonstrates how to use the API to parse the purchase order XML document that is available here.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
import asdk.*;
import asdk.xml.*;
var xmlUrl = "http://www.themidnightcoders.com/asdk/purchaseorder.xml";
Document.load( xmlUrl, documentLoaded );

function documentLoaded( document )
{
  var root = document.getRoot();
  var elements = root.getElements();

  while( elements.hasNext() )
  {
     var element = elements.getNext();
     var name = element.getName();
     trace( "element name = " + name );

     switch( name )
     {
       case "billTo":
         processAddress( element );
         break;
       case "shipTo":
         processAddress( element );
         break;
       case "comment":
         trace( "comment = " + element.getString() );
         break;
       case "items":
         processItems( element );
         break;
     }
  }
}

function processAddress( address )
{
  trace( "***** processing address *****" );
  var country = address.getAttribute( "country" );
  trace( "attribute " + country.getName() + " has value " + country.getValue() );
  var elements = address.getElements();

  while( elements.hasNext() )
  {
    var element = elements.getNext();
    trace( "element " + element.getName() + " has value of " + element.getString() );
  }
}

function processItems( itemsElement )
{
  trace( "***** processing items *****" );
  var items = itemsElement.getElements();

  while( items.hasNext() )
  {
    var item = items.getNext();
    var partNum = item.getAttribute( "partNum" );
    trace( "attribute " + partNum.getName() + " has value " + partNum.getValue() );
    var elements = item.getElements();

      while( elements.hasNext() )
      {
        var element = elements.getNext();
        trace( "element " + element.getName() + " has value of " + element.getString() );
      }
  }
}

Flash movie with source code

Note on line one that the asdk.xml package is imported into the script; this allows Flash access to all the classes that ASDK uses to provide XML support. The action here begins on line 4 when the static load method of the Document class is called. This method takes a string (the path to an XML document) and a callback function as parameters. The Document is then parsed and the callback function is invoked by ASDK to pass the document back to your application. It is then a simple matter to traverse the document by iterating over the elements of the document. In this particular example, the root element of the document is retrieved (line 8) and all of its children are returned from the call to root.getElements (line 9). This returns an asdk.xml.Elements object which conforms to the asdk.Iterator interface. This object allows for easy traversal of series of children elements using the while hasNext, getNext idiom (lines 11/13, 42/44, 52/54, and 61/63).

Also note that the attributes for an element are available by using the getAttribute method (lines 38 and 57) by passing in the name of the attribute. Assuming the attribute exists, this call returns an instance of asdk.xml.Attribute that surfaces two primary methods: getName and getValue that returns the name and the value of the attribute respectively.

Lastly observe that getting the data from an XML element is as simple as calling getString on the element (lines 45 and 64).

Running the example above within the Flash IDE will yield the following lines in the Output window:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
element name = shipTo
***** processing address *****
attribute country has value US
element name has value of Alice Smith
element street has value of 123 Maple Street
element city has value of Mill Valley
element state has value of CA
element zip has value of 90952
element name = billTo
***** processing address *****
attribute country has value US
element name has value of Robert Smith
element street has value of 8 Oak Avenue
element city has value of Old Town
element state has value of PA
element zip has value of 95819
element name = comment
comment = Hurry, my lawn is going wild
element name = items
***** processing items *****
attribute partNum has value 872-AA
element productName has value of Lawnmower
element quantity has value of 1
element USPrice has value of 148.95
element comment has value of Confirm this is electric
attribute partNum has value 926-AA
element productName has value of Baby Monitor
element quantity has value of 1
element USPrice has value of 39.98
element shipDate has value of 1999-05-21