Recipe 20.11. Loading XML

Problem

You want to load XML data from an XML document or a server-side script that generates XML.

Solution

Use the URLLoader.load( ) method with its dataFormat property set to DataFormat.TEXT to load the data as plain text. Use an event handler for the complete event and convert the text into an XML instance.

Discussion

In previous versions of ActionScript, loading an XML file was done by invoking the load( ) method directly on an XML object. In ActionScript 3.0, sending and loading of data has been consolidated into the new URLLoader class and its related classes. There are no special considerations given to loading XML in ActionScript 3.0, leaving it up to you to implement your own solution.

The process of loading an XML file, while multistep, is relatively painless. First, a URLLoader instance must be made to load the data from the URL. To instruct the URLLoader to load the data as plain text, its dataFormat property must be set to DataFormat.Text. An event listener for the complete event needs to be added so you receive notification when the data has finished downloading. In the complete event handler, one of the techniques outlined in Recipe 20.2 should be used to convert the loaded data into an XML object. Finally, the URLLoader.load( ) method must be invoked to kick off the loading process, being passed a URLRequest instance that points to the URL of the XML file. A complete example looks like this:

package {
  import flash.display.*;
  import flash.events.*;
  import flash.net.*;
  import flash.util.*;

  public class LoadXMLExample extends Sprite {
    
    public function LoadXMLExample(  ) {
      var loader:URLLoader = new URLLoader(  );
      loader.dataFormat = DataFormat.TEXT;
      loader.addEventListener( Event.COMPLETE, handleComplete );
      loader.load( new URLRequest( "example.xml" ) );
    }
    
    private function handleComplete( event:Event ):void {
      try {
        // Convert the downlaoded text into an XML instance
        var example:XML = new XML( event.target.data );
        // At this point, example is ready to be used with E4X
        trace( example );
        
      } catch ( e:TypeError ) {
        // If we get here, that means the downloaded text could
        // not be converted into an XML instance, probably because 
        // it is not formatted correctly.
        trace( "Could not parse text into XML" );
        trace( e.message );
      }
    }
  }
}

In the preceding example, note the use of the try...catch block in the handleComplete method. In the event that the XML file did not contain valid XML markup, a TypeError is generated when the downloaded data is converted into an XML instance. The error is caught by the catch block, allowing you to handle the parsing failure gracefully.

For more information about using URLLoader, refer to Chapter 19.