Working with SWX: The Native Data Format for the Flash Platform (Open Source Flash Development) Part 2

Writing your first custom service

Now that you have SWX PHP installed, let’s create a simple custom service.

SWX is most useful when connected to data (either a database or an API), but for this example I’ll show how to build a simple but complete web application with SWX PHP. You’ll create both the client side and the server side of the application, and by the end of the following sections, you should have a clear conceptual understanding of how SWX PHP works.

The application you’re building is a simple calculator that uses a server-side method to add two numbers together.

Creating the calculator service class in PHP

To start, you’ll create a PHP service class. In SWXyou place service classes in the php/services folder. Those classes are then available for testing with the SWX Service Explorer, as discussed earlier.

So, create a new file using your text editor of choice under php/services/, and call it Calculator. php. Add the following code to Calculator.php, and save the file:

This is a very simple server-side service class that has a single method called addNumbers(). This method takes two numbers as arguments and returns their sum.

Can you use a folder other than /php/services to hold your SWX PHP service classes?

You sure can. All you need to do is change a setting in the SWX configuration file (swx_config.php). You can find the file in the php folder. In it, just change the $servicesPath variable to point to where your services are, relative to the SWX gateway.

At this point, it would be nice if you could test the server-side method you just created without having to create a Flash client. The SWX Service Explorer lets you do just that.

Testing the calculator service with the SWX Service Explorer

Return to the SWX Service Explorer (or open it if you did not earlier), and you will see the Calculator class you just created.

Click it, and you will see the addNumbers() method. Enter two numbers in the $n1 and $n2 fields, and click the call button to test the method. You should then see the sum returned in the results area.

Consuming your calculator service in Flash

You’ve verified that your server-side service method is working correctly by using the SWX Service Explorer. Now let’s call this method from Flash using SWX AS, the ActionScript API:

1. Open Flash, and create a new FLA (ActionScript 2). You can set the publish setting to Flash 7 or 8. Save your FLA in the flash/ folder (the one that has the org and com folders) before continuing. Or, add that folder to your ActionScript classpath in the Flash IDE and save your FLA anywhere.

2. On frame 1 of the new FLA, create a single-line dynamic text field instance, and give it the instance name status.

3.Create a new layer, and call it actions. On the actions layer, add the following code, being sure to update the gateway URL to match your own server settings:

That’s all the code you need to call the addNumbers method on the Calculator service class in PHP and pass it the numbers 35 and 7 as arguments. The swx.call() method calls the SWX gateway and passes to it any of the properties you set in your callParameters object. In this case, since you are sending a small number of arguments, you use the GET HTTP encoding method. You could just as easily have used POST by changing the encoding property to POST instead of GET.

Instead of putting call-related parameters directly into a MovieClip like you did with the Moo MiniCard example previously (and thus having to poll for the data using onEnterFrame()), you created a callParameters object and specified the serviceClass, method, and args properties.

Using SWX AS also allows you to specify handlers, which are functions that are called when certain actions occur with SWX, such as when data is returned or when the call times out.

Using a result handler

As you did previously, you can specify a result handler that will get called once the data has loaded. The result handler is set in the result property of the callParameters object, and it receives an event object as an argument. That event object has a result property that points to the loaded data.

Using a timeout handler

The SWX ActionScript library also provides an additional event listener: a timeout handler for your SWX instance to handle calls that take too long to return a result.

To set a timeout handler, modify your code to match the following:

The default timeout duration is 30 seconds, but you can override that, as shown earlier, where it’s set to two seconds.

To make the call actually time out, modify the Calculator class in PHP too to make it sleep for ten seconds before returning the result. The Calculator class should now read as follows:

Now test your Flash movie, and after two seconds, you should see the SWX call time out. Timed-out calls are canceled and will not trigger the result handler at any point in the future.

Using a fault handler

The SWX ActionScript library also provides one last event listener: a fault handler for handling errors during SWX RPC calls. To test the fault handler, modify your code to match the following:

You also need to modify your service so that it generates an error:

Test your FLA, and you should get an error similar to the following in the status text field in Flash:

The fault handler also returns API-specific fault codes (for example, Flickr API error codes) back to Flash should they occur, making this useful for all APIs as well as custom classes.

At this point, you should have a clear understanding of how SWX PHP and the SWX ActionScript API work. In addition, you have all the knowledge you need to test and deploy your SWX applications.

With that in mind, let’s take a moment to see what SWX is capable of when connected to a custom content management system (CMS) and when utilizing several custom service classes.

Case study: p.i.n.k. Spirits

SWX is capable of much more than just receiving an answer to a simple math equation as you did in the previous section. When deployed on your own server and combined with custom service classes, it can be used to develop a high-profile consumer site, such as the one JonnyMac Design (http:// www.jonnymac.com) recently built for p.i.n.k. Spirits (see Figure 8-6).

Figure 8-6. The p.i.n.k. Spirits home page

The p.i.n.k. Spiritswebsite (http://www.pinkspirits.com) uses a total of eight custom service classes, comprising forty-four custom methods.

Those methods each handle a specific task such as retrieving images and text for Flash to display throughout the site (see Figure 8-7) and interacting with Constant Contact (an e-mail newsletter service) to allow users to sign up for the p.i.n.k. Spirits newsletter (for more details or to download the open source Constant Contact service API, visit http://swxformat.org/159).

Figure 8-7. The p.i.n.k. Spirits mixology section, showing a few of the available drink recipes available to site visitors

However, the functionality I’d like to focus on is the product locator (see Figure 8-8), which you can view on the p.i.n.k. Spirits site at http://www.pinkspirits.com/#/buy/locate/. In the next section, I’ll show how to use the same custom service written for the website and consume it in a Flash Lite application for mobile deployment.

So, I’ll pause here so you can take a moment to review the p.i.n.k. Spirits site, especially the “find p.i.n.k.” section at http://www.pinkspirits.com/#/buy/locate/. Once you have an understanding of how the product locator works from a user standpoint, continue to the next section where I’ll discuss the specifics of the service and show how to create the Flash Lite application.

Figure 8-8. The p.i.n.k. Spirits product locator, where site visitors can search by city/state or ZIP code for restaurants/bars and retailers offering p.i.n.k. Spirits products