SWX: SWF Data Format

Flash is getting a new data exchange format today! It's my pleasure to introduce you to SWX (previously known as project codename The Tangent.)

SWX stands for SWF Data Exchange Format. It's a new way of working with data in Flash that uses simple SWF files to exchange data. SWX is the natural, native way to get data into Flash: You loadMovie() your data!

SWX is easy!

This quick example demonstrates how simple it is to use. (Updated to reflect the new API in SWX Alpha 0.2.0 and above.)

import org.swxformat.*;
 
// A complex data object to send.
var myData:Array = ['data', 'to', 'send'];
 
// Assuming that dataHolder is a movie clip on Stage...
dataHolder.serviceClass = "Simple";
dataHolder.method = "echoData";
 
// myData will be sent as the first argument
// to the server-side method.
dataHolder.arguments = [myData];
 
// Prepare arguments array for transfer
// (serializes them in JSON format).
SWX.prepare(dataHolder);
 
// Call the SWX gateway
dataHolder.loadMovie("http://a.com/path/to/swx.php", "POST");
 
// A very simple check for returned data.
function onEnterFrame()
{
      // Results are returned in the result property.
	debug_txt.text = "Data: " + dataHolder.result;
}
 

That's all there is to it! SWX will create an instance of the Simple class in PHP and call its echoData() method, passing the arguments specified in the arguments array. It will then return the results in a variable called result wrapped in a SWX SWF file. (In this case, the echoData() method simply sends back the data object you sent it.)

You can either trace out the results of your data call or, a much better solution is to set debug mode on and view the results in the provided SWX Analyzer. The SWX Analyzer is a Flex app that shows you the returned data in a convenient tree view. Open the SWX Analyzer now (or just click on the image below) so you can see the results of the following example.

Here's a live example that contains a slightly modified version of the above code sample. Click the button to get the data from the server and view the results in the SWX Analyzer.

Since the SWX SWF file you receive contains your data in native SWF bytecode, you don't have to worry about deserializing the data once you received it: You can just use it!

Another advantage is that you can use getBytesLoaded() and getBytesTotal() to show a determinate preloader for your data! The SWF Data Exchange Format (SWX) is a very limited subset of the SWF specification -- it's a SWF that only contains data.

Before sending data from Flash to the back-end, you must serialize the data you're sending in JSON format. You do this by asking SWX to prepare it using SWX.prepare(dataHolder);.

When you request data from PHP, you get a SWX SWF with the data inside it in native SWF bytecode (there is no deserialization involved.) The moment your data SWF has loaded, the data is available for you to access without delay.

So what does the back-end look like? Like everything else in SWX, it's very simple.

You simply create classes with public methods that return data and you place these classes in the /services folder. You can then call these public methods from Flash by doing a loadMovie() on the SWX gateway. You specify the serviceClass, method and an arguments array to pass to the method as properties in the movie clip you're loading the data into (see the Flash section, above).

class Simple
{
	 // Echo the passed data
	public function echoData($data)
	{
		return $data;
	}
}
 

That's it! The SWX gateway (swx.php) handles everything else, including parsing any arguments that you sent over, security checks to make sure that only public methods of classes in the /services folder can be used, the instantiation of the class and, of course, the serialization of the data returned by the class into SWX format using the SWX SWF Compiler. You don't have to worry about any of these things. As far as you're concerned, you're calling a method on a PHP class and receiving its return value as a native data structure inside a SWF.

The current alpha version of SWX only supports PHP but there's no reason for other programming languages and application servers to not be supported. Porting SWX to other languages is not a huge task as the most complicated bit, the generated SWF bytecode, is made up of chunks of constants that will not change. I expect that we will see Python, Ruby, Java and .Net versions of SWX contributed by members of the community in coming days.

Known issues and limitations

SWX is currently in very early alpha form: It may creak, break, or throw its toys. This is to be expected and I highly encourage you to test it out and report any issues you’re having to me so I can fix them.

It will be invaluable to me if you can send me the ActionScript and/or PHP data structures that are causing the issues.

There are several known issues and limitation with this alpha release. The main one is performance: SWX is currently not optimized in any way.

This means that neither the PHP code nor the SWF bytecode is optimized and that SWX is currently slower in serializing its data than other alternative technologies (Remoting, XML, etc.)

I expect that we will see a huge improvement in this area once both the PHP code and SWF bytecode is optimized. However, this will come later as my priority right now is making SWX as robust as possible before undertaking any sort of optimization work that will make the codebase harder to work with in the future.

If you have any optimization hints and tips, please do send them to me but realize that I will not implement them until later in the development cycle.

SWX is for you to play with, provide feedback on and create cool little apps with. Please do not use this alpha version in mission-critical applications: It's for experimenting with only at this point.

See the roadmap in the documentation section to see which issues I’m aware of and will be implementing in the coming days.

SWX is under heavy development and things may change drastically from day to day. I don't promise any sort of backwards compatibility during the alpha stage so please be prepared to have to update your experiments from release to release.

System requirements

SWX currently works with Flash 7+ SWFs and has been tested to work on the following PHP versions: 4.4.2, 4.4.4, 5.1.4, 5.1.6, and 5.2.1. It is *not* supported on the PHP 4.3 branch and is known not to work with PHP 4.3.10.

SWX only supports ActionScript 1 and ActionScript 2 at the moment. You can use SWX with Flex 2 and AS3 by creating a debug SWX SWF and making use of the LocalConnection. More native support may be added in the future. For an example of how to do this, see the Flex 2 source code for the SWX Analyzer.

Download

Get the latest SWX release from the download page.

Installation

To install SWX, unzip the file into a folder that is under the web root of the web server on your development machine.

Future releases of SWX will include installers that install a complete dev environment on your machine, including the necessary web server, PHP, MySQL, etc. If you don't have a dev environment on your machine currently, you can download and install MAMP (for OS X) or XAMPP (for Windows, Linux, etc.)

The sample files are hardcoded to work with the default MAMP installation (running on localhost, port 8888). Modify the sample FLA files if your setup is different.

In conclusion (or "Let's start having some fun!")

It's not everyday that a new data exchange format is created so I'm very excited about SWX and what it will mean for Flash developers. I created it because I feel that creating data-driven applications should be much easier than it is. In order for that to happen, however, we need easy to use APIs as well as a workflow and toolset that supports the entire experience of building a data-driven application. SWX will be just this.

SWX will make it easy for you create data-driven applications with Flash from the moment you arrive on swxformat.org.

I hope you're as excited about SWX as I am and I hope that it leads to more of you experimenting with mashups, mobile apps and other things I haven't even thought of yet in Flash. Above all, I hope it makes your lives easier and that you have more fun while building cool Flash applications. Because it really should be (and can be) fun!