How to use the ActionScript API

The SWX ActionScript library is allows your Flash application to communicate with the SWX gateway.

The AS3 API was written to be as close to the AS2 API as possible.

The Simple and Custom Calls

There are two ways to exchange data with the server: using a Simple Call or a Custom Call.

While the Simple Call is easy for beginners and for simple usage, the Custom Call allows more flexibility.

Making a Simple Call

Simple Call goes straight to the point and make use of all SWX default settings.

You can change any default settings if you want, but only the gateway is demanded.

When you are making the call, you can only define the resultHandler to be called when your data is returned, and if you'd like to activate the debug mode.

Step 1 - Import the swxformat API

import org.swxformat.*;

Step 2 - Create a SWX instance and configure it to point to your server gateway, or the public gateway as shown here

var swx:SWX = new SWX();
swx.gateway = "http://www.swxformat.org/php/swx.php";

Step 3 - Create the result handler function, which will be called when your data is returned from the server

function resultHandler(e:Object) : void
{
	trace("The result is: " + e.result);
}

Step 4 - Make the call (the addNumbers service is shown here)

//Usage:
//swx.serviceClass.method(args:Array, [resultHandler:Function], [debug:Boolean])

swx.Simple.addNumbers([1,4], resultHandler);

Important Notes

When using the AS2 version of the SWX ActionScript API, if you want a "this" reference on your handlers you must use Delegate.

import mx.utils.Delegate;
swx.Simple.addNumbers([1,4], Delegate.create(this, resultHandler));

You can even define a default result handler property, and then omit it from the Simple Call:

swx.resultHandler = Delegate.create(this, resultHandler));
swx.Simple.addNumbers([1,4]);

Making a Custom Call

For more control over SWX you may wish to use a Custom Call.

With a Custom Call you can define on each call, all available SWX options.

For instance, you can define default timeout and fault handlers for your project. And then make SWX calls with different result and progress handlers, timeout lengths, debug mode... etc.

Step 1 - Import the swxformat API

import org.swxformat.*;

Step 2 - Create a SWX instance and configure it to point to your server gateway

var swx:SWX = new SWX();
swx.gateway = "http://www.swxformat.org/php/swx.php";

// Default SWX options and handlers (optional)
swx.encoding = "POST";
swx.timeout = 30;
swx.debug = false;
swx.resultHandler = resultHandler;
swx.progressHandler = progressHandler;
swx.timeoutHandler = timeoutHandler;
swx.faultHandler = faultHandler;

Step 3 - Create your handler functions

function resultHandler(e:Object) : void
{
	trace("The result is: " + e.result);
}
function progressHandler(e:Object) : void
{
	trace("Loading: " + e.bytesLoaded + " of " + e.bytesTotal);
}
function timeoutHandler(e:Object) : void
{
	trace("ERROR: operation timed out");
}
function faultHandler(e:Object) : void
{
	trace("ERROR: " + e.fault.message);
}

Step 4 - Prepare your request parameters object (the addNumbers service is shown here)

var callDetails:Object =
{
	// Required Parameters
	serviceClass: "Simple",
	method: "addNumbers",
	args: [10, 15],
	// Optional Parameters
	gateway: "http://www.swxformat.org/php/swx.php",
	encoding: "POST",
	timeout: 5,
	resultHandler: resultHandler,
	progressHandler: progressHandler,
	timeoutHandler: timeoutHandler,
	faultHandler: faultHandler,
	debug: true
}

Step 5 - Make the call

swx.call(callDetails);

If everything is setup correctly the call to addNumbers(1,4) should show the following in your trace log

The result is: 5

Extras

Debugging / Analyzer

To debug your SWX calls, you can use the SWX Analyzer (located in /php/analyzer in your SWX server deployment directory or at http://www.swxformat.org/php/analyzer for the public gateway).

To enable debugging in your requests you must set the debug state to true. This can be done either on the SWX object or in the SWX call parameters.

At the SWX object level:

var swx:SWX = new SWX();
swx.gateway = "http://www.swxformat.org/php/swx.php";
swx.encoding = "POST";
swx.debug = true;
swx.timeout = 10;

At the request parameters object level:

var callParameters:Object =
{
	serviceClass: "Simple",
	method: "addNumbers",
	debug:true,
	args: [1,4]
}

Additional tools

We would also recommend using an HTTP debugging proxy application to observe the requests and responses sent across to the server.

A couple of popular HTTP debugging proxy applications are:

Charles

Fiddler

Queue completion event

You can also add one additional event listener to the SWX LoadManager. This event is triggered when the current load queue is completed:

LoadManager.getInstance().addEventListener(SWXLoadManagerCompleteEvent.LOADMANAGER_COMPLETE, onLoadManagerComplete);

function onLoadManagerComplete(e:SWXLoadManagerCompleteEvent) : void
{
	trace("Queue complete");
}

Cross domain access

To be able to access a gateway through a cross domain call, an extra step is required.

Call the initializeCrossDomain method on the SWX object, passing the URL of the current movie clip as a parameter.

This will allow SWX to return additional cross domain security instruction in the response to authorize the calling script to access the data.

swx.initializeCrossDomain(stage.loaderInfo.url);