WDDXXML and Flash | Inside Flash MX (2nd Edition) (Inside (New Riders))

WDDX/XML and Flash

As you have seen, Flash requires incoming data to be in either name /value pairs or XML. Most programming languages don't output their data in either of those two formats, so if you're going to use Flash in conjunction with another back-end program, you'll need to figure out how to handle the data that is returned.

For example, many programs output data in structures or arrays. You can pass the information from the structure or array into a delimited list and send that to Flash. But you'd have to parse it and rebuild the array in Flash, and that isn't very efficient. So how do you effectively exchange complex chunks of data? That's where WDDX comes in.

Web Distributed Data Exchange (WDDX) is an XML technology that enables programmers to send complex data from any Web programming language that supports XML and WDDX. For instance, Java, ColdFusion, ASP, and PhP all support WDDX technology. So, if you want to write an application that requires Flash to have certain data structures from your Java code, you could use WDDX and XML to send those data structures to Flash for use in your ActionScript code.

WDDX is a way to "exchange" data between two unrelated Web programming languages. WDDX converts objects native to one language to objects native to another language. For example, if you had an object in Java that you need to use in Flash, WDDX can convert that native Java object into a native Flash object that is nearly identical. The only things lost in conversion are the Java-only properties or methods, but the object gains Flash object properties and methods . After it's converted, the object behaves just like any other object created in Flash, allowing for easy integration into any ActionScript code.

One of the best things about using WDDX is that it doesn't require the programmer to have any knowledge of how to use and implement XML. WDDX converts the object to XML, which can then be passed easily over HTTP and easily accepted by Flash. Then WDDX converts this XML object into a native Flash object. Converting XML back and forth is much easier than converting Java to Flash, or any Web programming language to another.

When Should You Use WDDX?

WDDX is not something that should be used in every cross-language application. When you need to send only one or two simple variables to Flash from another language, there is no need for WDDXusing it would be overkill. When the situation calls for only a small number of simple variables, such as integers or characters , it's usually easier to pass these variables with the URL string or write them to a text file that Flash can read them from. When using WDDX, be careful of overkill.

WDDX is very practical for complex data types such as arrays, record sets, and data/time objects. Any time you need to transfer data structures, such as associative arrays or structs, WDDX could be your best bet.

How Does WDDX Work?

WDDX stores data from one language in an XML format, which allows it to be sent via HTTP. The programmer has to write only simple serialization and deserialization "modules" that encode and decode the XML format, respectively. Looking at a simple example will help clarify the inner workings of WDDX.

Imagine that you want to send a complex data structuresay, an array of strings that you will call Afrom Java to Flash. You have already decided that WDDX is the best solution for this problem. Both Java and Flashand most other Web languages, for that matterhave a WDDX object or class already packaged with them; if it isn't already present, it can be easily downloaded from the Web. This package includes the serialization and deserialization "modules." This makes your job as the programmer or designer very easy because all you have to do is tell the respective language that you want to serialize or deserialize , whichever the case may be. For your example, you need Java to serialize A, converting it to an XML format. Here's what you do:

Create an instance of the WDDX object.
Create an instance of an XML object.
Call the serialize method of the WDDX object, passing the object that you want to serialize as the parameter (in this case, A). This function will return an XML object whose content is A.

So, your code might look something like this pseudocode:

 myXMLObject = new XML();  myWDDXObject = new WDDX();  myXMLObject = myWDDXObject.serialize(A);

Now you have an XML object consisting of the contents of A that is ready to be sent to Flash for deserialization and use in ActionScript.

Once in Flash, you tell Flash that you want to deserialize the XML object that just came in. This is rather simple because a WDDX object is already available for Flash. The steps are as follows :

Retrieve the XML that you want to convert.
Create an instance of the WDDX object.
Call the deserialize method of the WDDX object and pass it the XML that you received as a parameter. This function will return a native Flash object.

Your code will look something like this:

 receivedXML = new XML();  .  .  .  {Your XML is loaded here}  .  .  .  myWDDXObject = new WDDX();  myNewObject = myWDDXObject.deserialize(receivedXML);

Now you can use myNewObject in your ActionScript code just as you would any other Flash object.

In the case of some Web languages, no WDDX objects/classes are available. However, the serialization and deserialization "modules" are easy to program. Check out www.wddx.com for more details on WDDX.

As a point of fact, Flash doesn't have an internal WDDX object. But never fearwe've taken care of that for you. Branden Hall and Dave Gallerizo of Fig Leaf Software have written a WDDX object for Flash. All you need to do is include the wddx.as in your file from Chapter_23/Assets folder on the CD, and you're good to go.

Now that you know a bit about how WDDX works with Flash, it's time to try to use it in an example. In this exercise, you have a persisting XML file that consists of a WDDX encoded recordset. That recordset contains three columns :

name
url
color

Your Flash movie will load the XML, deserialize it, and then display a link for each row of the recordset.

Exercise 23.4 Using WDDX and Flash

In your code, you'll be taking advantage of the special WDDXRecordset object that is included with the wddx.as file. This object is used for representing recordsets inside Flash. The WDDXRecordset object includes a number of methods for inspecting and manipulating a recordset's data. In this case, you'll be using getRowCount, which returns the number of rows in the recordset, and getField, which, given a row and column, returns the value of that field. If you want to know more about the other methods of the WDDXRecordset object, take a peek inside the wddx.as file. Now, enough about how you'd make it workget to it.

Create a new Flash movie, name it wddxExample.fla, and save it on your hard drive.
Browse out to the Chapter_23/Assets folder on the CD, and copy both the wddx.as and wddxExample.xml files into the same directory where you saved your wddxExample.fla file.
Back inside wddxExample.fla, select the Text tool and draw a new text field on the Stage.
With the text field selected, open the Text Options panel (Window > Panels > Text Options). Change the following settings:

Text Type: Dynamic Text

HTML: Selected

Variable: links
Launch the Actions panel and select the first frame of the timeline. Add the following line to the Actions list:
```
 #include "wddx.as" 
```
Make sure that you do not place a semicolon on this line.
Now create an instance of the WDDX object so that you can use it later to do your deserializing. Add another line to your Actions list:
```
 converter = new WDDX(); 
```
Next, you'll need to create the XML object that will actually load and parse the XML file. Add the following line of code:
```
 myXML = new XML(); 
```
You need to define what will happen when your XML object has fully loaded and parsed. For this you'll override the existing XML object's onLoad method with your own function. If the XML was parsed successfully, you'll want to deserialize the XML received and place the result into the serverData object. You have to specify _root here because any code inside the onLoad method actually lives inside the XML object, not the main timeline. After you deserialize the XML, you call a function on the main timeline, drawLinks, and pass it serverData. Add a new line to the Actions list and enter the following function:
```
 myXML.onLoad = function(valid){     if (valid){         var serverData = _root.converter.deserialize(this);          _root.drawLinks(serverData);      }  } 
```
Now go ahead and add the line that will actually load the XML:
```
 myXML.load("wddxExample.xml"); 
```
It should be obvious that you're missing one final chunk , the drawLinks function. It's a good idea to add functions close to the top of your code, just to make sure that they've loaded before you call them. You'll add this function just beneath the #include.

The data that you receive, when deserialized, will form a WDDXRecordset object. In your drawLinks function, you need to pull each row of data outside the object and use it to add a new line to a list of links. The code that does this is very straightforward. In pseudocode, you need to do this:
- Find out how many rows are in the recordset. This is easy to do using the getRowCount() method.
- Initialize a variable to hold your data.
- Use a for loop to loop through the recordset and extract the data. For each row, you create name, url, and color variables by pulling that data from the recordset via a getField() method.
- Format your data. Use HTML tags and add it to your _root.links variable, which, as you remember, is being displayed by the textbox that you created earlier.

Okay, enough said. Start coding. Add a blank line just beneath the #include, and enter the following code:

 function drawLinks(recordset){ // How many rows?      var max = recordset.getRowCount();  // Initialize variables      _root.links = "";  // Loop over the recordset, extract and format data      for (var i=0;i<max;++i){         var name = recordset.getField(i, "name");          var url = recordset.getField(i, "url");          var color = recordset.getField(i, "color");          root.links += "<font color="#"+color+"'><u><a          href='"+url+"'>"+name+"</a></u></font><br>";      }  }

Save and test your file. You should see a list of HTML-formatted links to our three favorite Web sites!

Remember that although the recordset is just in a static XML file, you could just as easily have loaded it from the CFM file that is pulling that data from a database. The loadXML() method doesn't care what the file extension is, as long as the actual data is in XML format.