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

Project: utilizing a custom service in Flash Lite

While SWX makes developing and consuming custom back-ends for full Flash websites much easier and simpler to interface with, SWX really shines when used to develop for mobile phones and devices (see “Supported platforms and technologies” in this topic for more information).

Goal: a product locator

In this section, I’ll walk you through building a Flash Lite 3.0 application that will allow users to find the nearest restaurants/bars and retail locations selling the p.i.n.k. Sprits line of liquors using their Flash Lite-supported mobile phones.

Just like on the p.i.n.k. Spirits website in the earlier case study, the user will be able to enter a city and state or U.S. ZIP code, and the service will return the closest locations selling p.i.n.k. Spirits to the city/state or ZIP code entered. Note that this service will function only with U.S. cities, states, and ZIP codes.

The PHP service class

Because this topic is focusing on SWX and not PHP and because the logic and database to set up a product locator is beyond the scope for this topic, you won’t be writing the necessary PHP service class. Instead, you will utilize the one already written that is currently being used on the p.i.n.k. Sprits website for the “find p.i.n.k.” section. As is the case with all SWX service classes (APIs), the same service can be used for deployments of both Flash and Flash Lite projects.

The specific service class you will be using is entitled PinkBuy, and it contains a method called SearchLocations. SearchLocations handles all the logic of searching the ZIP code and p.i.n.k. Spirits locations database. It returns a native Array of objects for each location found matching the user entry, and it accepts four arguments, as shown in Table 8-2.

Table 8-2. Arguments Accepted by Search Locations

Argument	Description
city	Data type: String. Optional. The city in which the user wants to locate the product. If a city argument is provided, a state argument must also be provided. If a city and state are provided, the zip argument can be left as an empty string.
state	Data type: String. Optional. The state in which the user wants to locate the product. If a state argument is provided, a city argument must also be provided. If a city and state are provided, the zip argument can be left as an empty string.
zip	Data type: Number. Optional. The five-digit U.S. ZIP code in which the user wants to locate the product. If a zip argument is provided, the city and state arguments can be left as empty strings.
type	Data type: String. Required. A String representing on-site or off-site consumption sales (in other words, a bar vs. a grocery store). Valid arguments are ON, OFF, and ON,OFF.

Downloading the SWX ActionScript library

The first step in building the Flash Lite application is to download the SWX ActionScript library, SWX AS. Visit http://www.swxformat.org/download, and click the Download SWX ActionScript Library link. Once you have downloaded the file, unzip and note the location of the new folder containing the necessary ActionScript libraries. For simplicity, this is also where you will save your Flash source file, or FLA.

Setting up the Flash Lite application FLA

To set up the Flash Lite application FLA, follow these steps:

1. Open Flash CS3 and create a new file, choosing Flash File (Mobile) as the type from the New Document window. This launches the Adobe Device Central window where you can choose the publish settings for your application.

2. For Player Version, choose Flash Lite 3.0; also set ActionScript Version to ActionScript 2.0. In the bottom of the Adobe Device Central window, check the Custom Size for All Selected Devices box (see Figure 8-9). You can leave the stage size set to the default of 176X208, an appropriate safe area for viewing on the widest range of Flash Lite mobile phones.

Figure 8-9. Adobe Device Central window showing the settings you’ll use for the example Flash Lite application

3.    Click Create, and you will be taken back to Flash CS3 with the stage all set up and ready to begin creating your application.

4.    Save your FLA file into the same folder as the SWX ActionScript library files, which you previously noted. To avoid issues with the FLA finding the SWX ActionScript library files, be sure that the org folder is in the same folder as your FLA. If you want to store your FLA in a separate directory, you can alternatively add the folder containing the SWX ActionScript library to your FLA’s classpath.

Establishing an initial service connection

To establish an initial service connection, follow these steps:

1.    Create a second layer in your timeline, and name it actions. Lock the actions layer so it can contain code only. Label the other layer content. The content layer is where you’ll put all your assets.

2.    Create two keyframes on each layer. Frame 1 will be your search state; frame 2 will be your results state.

3.    On the content layer of frame 1, create a dynamic text field across the width of the stage, and give it an instance name of status_txt. You’ll use this text field to test your initial connection to your service on the p.i.n.k. Spirits web server.

4.    On frame I of the actions layer, enter the following code.

First, import the necessary SWX ActionScript library and tell Flash to stop() on the current state until you tell it to go forward:

import org.swxformat.SWX; stop();

Next, create an instance of the SWX ActionScript library and then set some of its properties, including the gateway URL, encoding type, and number of seconds to wait before timing out. Because you will not be sending large amounts of data to the service, GET encoding works well. The timeout should be set to 5 seconds, knowing that you are building a mobile application and the connection speeds will be slower than in the normal Flash Player.

Then, set up the callParameters object, which contains all the information you want to send to your service, as well as letting SWX know which additional options you want to use. As mentioned earlier, the service class you will be using is called PinkBuy, and the method you will be using is SearchLocations.

I have already discussed the arguments the SearchLocations method accepts (see Table 8-2). To test the initial connection to the SWX service class, you will hard-code the arguments. In this case, you are leaving the city and state arguments as empty strings, entering a known valid number for the zip argument, and setting ON,OFF as the type. For ease of use on mobile devices, you will not offer users a choice for type and will always set the type to the string ON,OFF.

You also set the result, timeout, and fault event handlers, assigning them a function to call when/if the events should occur.

Since you chose to define the result, timeout, and fault event handler options in the callParameters object, you must also define the functions that will be called when the events occur:

In the resultHandler, you will set the status_txt text field to display the first result from the returned object. In the timeoutHandler, you will set status_txt to display a message letting you know the call has timed out. In the faultHandler, you will set status_txt to display the error message returned by SWX.

Once everything is set up for the call, you can make the call to the SWX service using the call() method of the SWX instance. The call() method accepts one parameter, the callParameters object:

At this point, you are ready to test your service. Select Control > Test Movie. The Adobe Device Central window will launch, and you will see the name of the first location returned from the SWX service for the ZIP code entered (97209 for Portland, Oregon), as shown in Figure 8-10.

Figure 8-10. Adobe Device Central window with the initial testing results displayed

Notice how you did not have to do any complex parsing to retrieve your data? You simply needed to know what the property name of the returned object was that you wanted to access. No complex firstChild.node, lastChild.node XML parsing—the data was available in a native data format (in this case, an object) immediately after it was loaded into the Flash Lite application.

The PinkLocation method of the PinkBuy service returns several pieces of information about each location found matching the search parameters. Each of these pieces of information is stored as a property of an object, with each result being contained with its own object. Table 8-3 shows all the properties contained within each returned result object.

Table 8-3. Properties Included in Each Result Object Returned by PinkBuy.PinkLocation()

Property	Description
account	The name of the location, such as “Portland City Grill”
address	The physical street address of the location
city	The U.S. city of the location
state	The U.S. state of the location
zip	The five-digit U.S. ZIP code of the location
phone	The ten-digit phone number of the location
distance	The distance, in miles, from the center of the city/state or ZIP code entered to the location
type	Either ON or OFF, denoting whether on-site or off-site consumption sales are provided

Now that you have established an initial connection to your service, let’s continue by building the assets you will need for the two states of the application, search and results.

Creating assets for search and results states

To create assets for search and results states, follow these steps:

1. Begin by creating three single-line input text fields with the border set to show around the text on the content layer of frame I. To save on file size, you can use _sans as the font face. Arrange the text fields so they are stacked vertically on top of one another, adding a static text header above each one. The static text headers should read City, and State, and or ZIP.

2. For the top text field, assign it an instance name of city_txt, and set the maximum characters limit to 30. For the middle text field, assign it an instance name of state_txt, and allow only two maximum characters. Assign the bottom text field an instance name of zip_txt, and set the maximum characters limit to 5.

3. Next, you need to create a way for the user to submit the data to the service. Create a rectangle with rounded corners below the text fields. Select it, and hit F8 to create a MovieClip of the shape. Give the new MovieClip an instance name of submit_mc, and then double-click it to open it. Once inside the MovieClip, add a static text field over the rounded rectangle with the word Submit. Now double-click any unoccupied space on the stage to return to the main timeline.

At this point, frame 1 of your stage should look similar to Figure 8-11.

Figure 8-11. The Adobe Flash stage showing the application layout for the search state

You now have the initial state, or search state, completed. Click frame 2 of the content layer in the main timeline. On this frame, you’ll build your results state.

4.    Create two dynamic text fields on the stage, stacked on top of one another vertically. Assign an instance name of numResults_txt to the top text field, and set it to be a single line, with center text alignment. Again, to save file size, set the font face to _sans. You will use this text field to display the total number of results returned.

5.    The bottom text field is where you will display the results returned from the SWX service class. Set this bottom text field to have an instance name of results_txt, to be multiline, to be HTML enabled, and to have left text alignment. Set the font face to _sans. You will want to resize the text field to have ample room to display about six or so lines of text while leaving enough room at the bottom of the stage for three buttons: Prev, New Search, and Next.

6.    Below the bottom text field, add three new MovieClips similar to the submit_mc MovieClip you previously created for the search state. These three MovieClips should contain, from left to right, a static text field with the text Prev, New Search, and Next and should be lined up horizontally across the bottom of the stage. Assign instance names to the MovieClips— previous_mc, newSearch_mc, and next_mc—according to the text labels within them. These buttons will allow users to navigate between each of the results received from the PinkBuy service.

Frame 2 of your FLA should now look similar to Figure 8-12.

Figure 8-12. The Adobe Flash stage showing the application layout for the results state