Creating a Flash Fill-in Form (ActionScript: The Definitive Guide)

17.2. Creating a Flash Fill-in Form

Our example includes all of the necessary components of a Flash form, cited earlier, but stripped down to the simplest level. This tutorial demonstrates how to send a single text field variable from Flash to a Perl script, named echo.pl, and how to receive a response in Flash back from echo.pl. Functioning versions of the example files are available from the online Code Depot. Let's get to it, shall we?

17.2.1. Building the Frontend

Unlike HTML, Flash does not have an integrated mechanism for the creation of forms. In HTML, creating pull-down menus and radio buttons is simply a matter of using the <SELECT>, <OPTION>, and <INPUT TYPE="RADIO"> tags. In Flash, those devices must be built by hand. Flash's only built-in form device is the user-input text field (the equivalent of HTML's <INPUT TYPE="TEXT"> or <INPUT TYPE="TEXTAREA">).

TIP

Though form widgets are not built directly into the Flash authoring tool, radio buttons, checkboxes, and pull-down menus are available as Smart Clips included with the product. To access the form-widget Smart Clips, choose Window Common Libraries Smart Clips.

In our form, we'll have a user-input text field and a Submit button. We'll place these two elements into a movie clip so that we can easily identify the variables to send to the server. First, we'll create a new document and the formClip movie clip, as follows:

Start a new Flash document.
Select Insert New Symbol. The Symbol Properties dialog box appears.
In the Name box, type formClip.
Click OK.
From the Library, drag an instance of formClip onto the main Stage.

Next, we'll add a user-input text field to formClip by following these steps:

In the Library, double-click the formClip symbol to edit the clip.
Select the Text tool.
On the clip canvas, drag a rectangle big enough for a user to enter a single line of text.
Select Window Panels Text Options.
For Text Type, select Input Text.
For Line Display, select Single Line.
In the Variable box, type input.
Select Border/Bg.

Now we'll assign our input text field a default value, ensuring that it will be sent to the server even if the user doesn't enter any data:

In the formClip timeline, select frame 1.
In the Actions panel, enter the following code: input = "";.

Finally, we add a Submit button to formClip by following these steps:

Select Window Common Libraries Buttons.
From the Buttons.fla library, drag an instance of the Push Bar button onto the formClip stage.

17.2.2. Sending Data to the Server

There are many ways to send data from Flash to a server application, including the loadVariables( ), getURL( ), loadMovie( ), XML.load( ), XML.sendAndLoad( ), and XMLSocket.send( ) methods. In our example, we'll use the loadVariables( ) method. For information on the others, see Part III, "Language Reference".

In the previous section, we placed a user-input text field and a Submit button in the movie clip formClip. To make that Submit button send formClip's variables to echo.pl when clicked, follow these steps:

In the Library, double-click the formClip symbol (this edits the clip).
Select the Push Bar button instance.
Select Window Actions.

Enter the following code in the Actions panel:

on (release, keyPress "<Enter>") {
  loadVariables ("http://www.yourserver.com/cgi-bin/echo.pl", 
                 "_root.response", 
                 "GET");

  _root.response.gotoAndStop("loading");
}

The code on our Submit button uses loadVariables( ) to send the variables of formClip to echo.pl, and it causes our response clip to display a loading message. We'll build the response clip a little later. For now, let's examine how the loadVariables( ) invocation works.

The first parameter of the loadVariables( ) invocation should specify the location of echo.pl on your server (server-side scripts are typically stored in a folder named cgi-bin). Be sure to set the location correctly according to your server's domain name and directory structure. When loadVariables( ) executes, all the variables in formClip are sent to that location.

The second parameter of the loadVariables( ) invocation indicates the path to the clip in which we will store the return value sent by echo.pl, namely "_root.response".

The third parameter of the loadVariables( ) invocation specifies the HTTP method we're using to submit formClip's variables to the server -- the GET method in this case. ActionScript supports both GET and POST operations, as described under loadVariables( ) in Part III, "Language Reference".

17.2.3. The Perl Script, echo.pl

When the user clicks the Submit button in our movie's formClip, Flash initiates an HTTP GET request. This request executes the Perl script echo.pl. In order for our form to work, echo.pl must be placed in a CGI-enabled directory of a web server and configured by the server's administrator as follows:

The script must be executable (typically, this means setting the file permissions to 755).
On Unix, the path to the Perl interpreter must be set in the script.

Example 17-1 shows the source code for echo.pl. Note that the # character indicates a comment in Perl.

Example 17-1. The Source Code of echo.pl

#! /usr/local/bin/perl       
#-------------------------------------------------------------------------------
#  Name:      Simple Flash Echo 
#  Version:   1.2.0
#  Author:    Derek Clayton  derek_clayton@iceinc.com
#  Description:  Echoes back name/value pairs received from a Flash GET or POST.  
#-------------------------------------------------------------------------------
# MAIN
#-------------------------------------------------------------------------------
use CGI;                    # Use the CGI.pm for easy parsing
$query = new CGI;           # Query object 
$echoString = "output=";    # Initialize our output string
&getInput;                  # Get the input received from Flash
&writeResponse;             # Write the response back to Flash
exit;                       # Exit the script
#-------------------------------------------------------------------------------
sub getInput {
  # For each key get the associated value and add to the echo string
  foreach $key ($query->param) {
    $value = $query->param($key);
    $echoString .= "$key:$value\n";  
  }  
  # Remove the trailing newline (\n) before writing response
  chomp($echoString);
}

sub writeResponse {
  # Set content type for Flash
  print "Content-type: application/x-www-urlform-encoded\n\n";
  # Write the output
  print $echoString;
}

The echo.pl script performs three general tasks:

It accepts data sent by Flash and parses that data into a series of variable names and values.
It assembles those variable names and values into a string to return to Flash. The string has the following format:
```
output=name1:value1\nname2:value2\n...namen:valuen
```

It returns the string to Flash.

Upon receiving the string returned by echo.pl, Flash automatically interprets it as a series of URL-encoded variables (as described in the entry for loadVariables( ) in Part III, "Language Reference"). Hence, output becomes a variable on the response clip's timeline. By examining the value of output in our Flash movie, we can see which variable names and values were originally sent to echo.pl.

Obviously echo.pl is not the most interesting web application in the world. It is only a proof of concept. When applied, however, the concept can have interesting and powerful results. For an example of a more fully developed Perl system, see the flat file database sample available at the online Code Depot under "Server Communication."

17.2.4. Receiving Results from the Server

Recall that when we sent the variables of formClip to echo.pl, we requested that echo.pl 's return value be stored in the movie clip response:

loadVariables ("http://www.yourserver.com/cgi-bin/echo.pl", 
               "_root.response", 
               "GET");

We'll now build that response clip; it has three states: idle, loading, and done loading. In the idle state, response is invisible to the user, waiting for data to begin loading. In the loading state, response indicates to the user that data has been submitted to the server and that Flash is waiting for a reply. In the done loading state, response has received the server's reply and displays that reply to the user via a text field. The three states of response govern its timeline structure. Each state is represented by a labeled keyframe: idle, loading, and doneLoading. The frame displayed is dictated as follows:

When the movie loads, response displays the idle frame.
When variables are submitted, the Submit button sends response to the loading frame.
When variables are received, response's data event handler (which we'll create) sends response to the doneLoadingframe.

To build response, we follow these steps:

Select Insert New Symbol. The Symbol Properties dialog box appears.
In the Name box, type responseClip.
Click OK.
From the Library, drag an instance of responseClip onto the main Stage.
Name the responseClip instance response.
In the Library, double-click the responseClip symbol (this edits the clip).
Create four timeline layers named, from top to bottom, scripts, labels, loading, and outputField.
Create three keyframes on each layer.
On the labels layer, for frames 1, 2, and 3, add the labels idle, loading, and doneLoading, respectively.
On the scripts layer, at frame 1, add the following code: stop( );.
On the loading layer, at frame 2, add the static text, "loading, please wait".
Select the Text tool.
On the outputField layer, at frame 3, draw a text box.
Select Window Panels Text Options.
For Text Type, select Dynamic Text.
For Line Display, select Multiline.
In the Variable box, type outputField.

Now let's add the data event handler that will be triggered when the server has finished sending its data to Flash. Follow these steps:

On the main Stage, select the response instance.
Select Window Actions.

Enter the following code in the Actions panel:

onClipEvent (data) {
  this.gotoAndStop("doneLoading");
  outputField = output;
}

When Flash receives the content sent by echo.pl, response's data event handler executes automatically. In the data handler, we move response's playhead to the doneLoading frame, and then we display the value of output (supplied by echo.pl ) in outputField. Our use of the data event handler ensures that the output variable will always be loaded before we attempt to display its value in the outputField text field.

All that's left to do is try your form out! Export your movie, enter some text in the input text field, and click the Submit button. If the form doesn't work the first time, make sure your server script is configured properly. And remember, you can study the functional version posted at the online Code Depot.

Reader Exercise: Try adding a Reset button to your form that clears the value of its input field. Create a new button in the formClip and attach the following code to it:

on (release) {
  input = "";
}

Also, try adding more than one input field to your form; the Perl script will faithfully return as many variables as you send it. Can you split them up and display each one's value separately?