Flash CS3 Documentation

Learning ActionScript 2.0 in Adobe Flash > Working with External Data > About XML > Using the XML class

Using the XML class

The methods of the ActionScript XML class (for example, appendChild(), removeNode(), and insertBefore()) let you structure XML data in Flash to send to a server and manipulate and interpret downloaded XML data.

The following XML class methods send and load XML data to a server by using the HTTP POST method:

• The load() method downloads XML from a URL and places it in an ActionScript XML object.
• The send()method encodes the XML object into an XML document and sends it to a specified URL using the POST method. If specified, a browser window displays returned data.
• The sendAndLoad() method sends an XML object to a URL. Any returned information is placed in an ActionScript XML object.

For example, you could create a brokerage system that stores all its information (user names, passwords, session IDs, portfolio holdings, and transaction information) in a database.

The server-side script that passes information between Flash and the database reads and writes the data in XML format. You can use ActionScript to convert information collected in the SWF file (for example, a user name and password) to an XML object and then send the data to the server-side script as an XML document. You can also use ActionScript to load the XML document that the server returns into an XML object to be used in the SWF file.

The flow and conversion of data between a SWF file, a server-side script, and a database

The password validation for the brokerage system requires two scripts: a function defined on Frame 1, and a script that creates and then sends the XML objects created in the document.

When a user enters information into text fields in the SWF file with the variables username and password, the variables must be converted to XML before being passed to the server. The first section of the script loads the variables into a newly created XML object called loginXML. When a user clicks a button to log in, the loginXML object is converted to a string of XML and sent to the server.

The following ActionScript is placed on the timeline and is used to send XML-formatted data to the server. To understand this script, read the commented lines (indicated by the characters //):

// ignore XML white space
XML.prototype.ignoreWhite = true;
// Construct an XML object to hold the server's reply
var loginReplyXML:XML = new XML();
// this function triggers when an XML packet is received from the server.
loginReplyXML.onLoad = function(success:Boolean) {
    if (success) {
        // (optional) Create two text fields for status/debugging
        // status_txt.text = this.firstChild.attributes.status;
        // debug_txt.text = this.firstChild;
        switch (this.firstChild.attributes.STATUS) {
        case 'OK' :
            _global.session = this.firstChild.attributes.SESSION;
            trace(_global.session);
            gotoAndStop("welcome");
            break;
        case 'FAILURE' :
            gotoAndStop("loginfailure");
            break;
        default :
            // this should never happen
            trace("Unexpected value received for STATUS.");
        }
    } else {
        trace("an error occurred.");
    }
};
// this function triggers when the login_btn is clicked
login_btn.onRelease = function() {
    var loginXML:XML = new XML();
    // create XML formatted data to send to the server
    var loginElement:XMLNode = loginXML.createElement("login");
    loginElement.attributes.username = username_txt.text;
    loginElement.attributes.password = password_txt.text;
    loginXML.appendChild(loginElement);
    // send the XML formatted data to the server
    loginXML.sendAndLoad("http://www.flash-mx.com/mm/main.cfm", loginReplyXML);
};

You can test this code by using a user name of JeanSmith and the password VerySecret. The first section of the script generates the following XML when the user clicks the login button:

<login username="JeanSmith" password="VerySecret" />

The server receives the XML, generates an XML response, and sends it back to the SWF file. If the password is accepted, the server responds with the following:

<LOGINREPLY STATUS="OK" SESSION="4D968511" />

This XML includes a session attribute that contains a unique, randomly generated session ID, which is used in all communications between the client and server for the rest of the session. If the password is rejected, the server responds with the following message:

<LOGINREPLY STATUS="FAILURE" />

The loginreply XML node must load into a blank XML object in the SWF file. The following statement creates the XML object loginreplyXML to receive the XML node:

// Construct an XML object to hold the server's reply
var loginReplyXML:XML = new XML();
loginReplyXML.onLoad = function(success:Boolean) {

The second statement in this ActionScript defines an anonymous (inline) function, which is called when the onLoad event triggers.

The login button (login_btn instance) is used to send the user name and password as XML to the server and to load an XML response back into the SWF file. You can use the sendAndLoad() method to do this, as shown in the following example:

loginXML.sendAndLoad("http://www.flash-mx.com/mm/main.cfm", loginReplyXML);

First, the XML-formatted data is created, using the values that the user inputs in the SWF file, and that XML object is sent using the sendAndLoad method. Similar to data from a loadVariables() function, the loginreply XML element arrives asynchronously (that is, it doesn't wait for results before being returned) and loads into the loginReplyXML object. When the data arrives, the onLoad handler of the loginReplyXML object is called. You must define the loginReplyXML function, which is called when the onLoad handler triggers, so it can process the loginreply element.

If the login is successful, the SWF file progresses to the welcome frame label. If the login is not successful, then the playhead moves to the loginfailure frame label. This is processed using a condition and case statement.

The CFM file contains the following code:

<cfif (Compare(Form.username, "Herbert") EQ 0) AND (Compare(Form.password, "glasses") EQ 0)>
<cfoutput>&isValidLogin=1&session=#URLEncodedFormat(CreateUUID())#</cfoutput>
<cfelse>
<cfoutput>&isValidLogin=0</cfoutput>
</cfif> 

For more information on case and break statements, see case statement and break statement in the ActionScript 2.0 Language Reference. For more information on conditions, see if statement and else statement in the ActionScript 2.0 Language Reference.

For more information, see Integrating XML and Flash in a Web Application at http://www.adobe.com/support/flash/applications/xml/ and the XML entry in the ActionScript 2.0 Language Reference. For more information on local file security, see About local file security and Flash Player.

For a sample source file, login.fla, that shows how to add simple login functionality to your websites using ActionScript 2.0, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download the Samples zip file and navigate to the ActionScript2.0/Login folder to access this sample. The sample uses ActionScript and components to create a small form in which you enter a user name and password and then click a button to enter a site.

Flash Player 8 and later supports the onHTTPStatus event handler for the XML class, LoadVars class, and MovieClipLoader class to allow users to access the status code from an HTTP request. This allows developers to determine why a particular load operation may have failed instead of only being able to determine that a load operation already has failed.

The following example shows how you can use the XML class's onHTTPStatus event handler to check whether an XML file successfully downloaded from the server and what the status code returned from the HTTP request was.

Checking HTTP status codes using the XML class:

1. Create a new Flash document and save it as xmlhttp.fla.
2. Add the following ActionScript to Frame 1 of the main Timeline:

   var my_xml:XML = new XML();
   my_xml.ignoreWhite = true;
   my_xml.onHTTPStatus = function(httpStatus:Number) {
       trace("HTTP status is: " + httpStatus);
   };
   my_xml.onLoad = function(success:Boolean) {
       if (success) {
           trace("XML successfully loaded");
           // 0 (No error; parse was completed successfully.)
           trace("XML status is: " + my_xml.status);
       } else {
           trace("unable to load XML");
       }
   };
   my_xml.load("http://www.helpexamples.com/crossdomain.xml");
   

   The previous code defines a new XML object with the variable name my_xml, defines two event handlers (onHTTPStatus and onLoad), and loads an external XML file. The onLoad event handler checks to see whether the XML file was successfully loaded and if so sends a message to the Output panel as well as traces the XML object's status property. It is important to remember that the onHTTPStatus event listener returns the status code returned from the web server, whereas the XML.status property contains a numeric value that indicates whether the XML object was able to be parsed successfully.

3. Select Control > Test Movie to test the Flash document.

   WARNING

   Don't confuse the HTTP httpStatus codes with the XML class's status property. The onHTTPStatus event handler returns the server's status code from an HTTP request and the status property automatically sets and returns a numeric value that indicates whether an XML document was successfully parsed into an XML object.

   CAUTION

   If a web server does not return a status code to the Flash Player, the number 0 is returned to the onHTTPStatus event handler.

For a source sample file that demonstrates how to create a web log tracker by loading, parsing, and manipulating XML data, xml_blogTracker.fla, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download the Samples zip file and navigate to the ActionScript2.0/XML_BlogTracker folder to access this sample.

For a source sample file that demonstrates how to use XML and nested arrays to select strings of different languages to populate text fields, xml_languagePicker.fla, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download the Samples zip file and navigate to the ActionScript2.0/XML_LanguagePicker folder to access this sample.

For a source sample file that demonstrates how to create a dynamic menu with XML data, xmlmenu.fla, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download the Samples zip file and navigate to the ActionScript2.0/XML_Menu folder to access this sample. The sample calls the ActionScript XmlMenu() constructor and passes it two parameters: the path to the XML menu file and a reference to the current timeline. The rest of the functionality resides in a custom class file, XmlMenu.as.

Flash CS3