Sending Data from Flash Movies to CGI Scripts and Back

Before you begin, you should download FLASHFORM.ZIP which contains FLASHFORM.FLA (the example .FLA file with Flash email form, in Flash MX format) and FLASHFORM.CGI (the example CGI script written in Perl, used together with the included Flash form).

INTRODUCTION

CGI can be used for many purposes in Flash sites. The most common use is making a form in Flash for your visitors to fill out. The contents of the form are then sent to a CGI script which in turn sends them to you as an email message. All of it is done without visitors having to open their email client. Alternatively, the contents of the Flash form can be sent to a CGI script which adds them as a new comment in your guestbook, or makes a new entry into a database.

You can also find uses for CGI scripts that send data to a Flash movie. For example, a CGI script could be used when loading a text file data into a Flash movie. It could check whether the file in question in fact exists, and if it does, whether it has a read permission enabled on the server. After these checks, the CGI script then could retrieve the file contents and send them back to the Flash movie, or set off an error flag and send the according error messages the Flash movie.

So how can you hook your Flash movie to a CGI script? You can send data to the script and retrieve data from the script with a single action - loadVariables.

I should note that after Flash MX came out there are now alternative, more versatile, ways of doing this - such as using LoadVars() object. For the purposes of this guide I'm sticking with the old and simple LoadVariables().

location of loadVariables action in the actions menu

loadVariables action is used to read data from static external text files and, more importantly to us in this guide, from the text output dynamically generated by a CGI, ASP, and PHP scripts. loadvariables is also used to send data to the script using GET and POST methods. Thus, you can tell Flash to send some arguments for a script to work on and then to retrieve the script's output - all with a single action.

loadVariables has the following parameters/options:

URL - absolute URL or location of the script on a server relative to the HTML file that contains our Flash movie
Location - level # or path to the target movie clip that is supposed to receive the received variables.
Variables - optional parameter, tells Flash to send variables using GET method, POST method, or not to send them at all.

An important thing to remember is that when you choose to send variables to a CGI script, the script gets sent ALL of the variables present on the current timeline (the timeline which loadVariables action is run from). So you have to make sure that all the necessary variables for the script to work on are present on the current timeline.

FLASH FORM

OK, now let's look at the provided example. Open FLASHFORM.FLA in Flash. It's the most basic email form that allows users to send feedback to the site's owner, using a very simple CGI script. Look at the main timeline of the movie. You can see the input fields called nameITF_txt, addressITF_txt, and messageITF_txt:

Sample Flash form for sending email contains 3 input text fields: nameITF_txt, addressITF_txt, and messageITF_txt

Each input field instance has its value kept in a .text property. We will take the values of this property and save them into variables - one for each input field instance. Then, when we use loadVariables from the main timeline and choose to send variables to the script, these variables (and thus, the contents of the input fields) will be sent to the script..

Now, have a look at the actions for our SEND button (send_btn):

When a visitor clicks the SEND button, we save the contents of the input fields into variables, then Flash sends variables to the CGI script and retrieves the script output.

As you can see, when a visitor clicks and releases the button after filling out the form, the contents of the input text fields are saved into variables on the current timeline (main timeline in our case). Then all the variables on the current timeline are sent to the script at the specified URL using POST method. The data returned by the script (if any) will be loaded into Level 0, as we specified. Also, after telling Flash to send and load variables, we tell the MC (short for "movie clip") called checker_mc to start playing at the frame labeled "check". Here are the actions for that frame:

In the "check" frame, we keep checking whether the value of "email_sent" variable on _root is changed to "1"

The MC starts looping through the "check" frame and checks whether the value of "email_sent" variable on the main timeline has been changed to 1 (that happens when the script sends data back to our Flash movie, as you'll see a bit later). When "email_sent" has a value of 1, we change the contents of messageITF_txt input field to show a success message.

There are also other ways to check whether the data had been received from a CGI script, such as using onClipEvent(data) handler or properties and methods of the LoadVars() - check the ActionScript Dictionary in Flash Help for more information on these.

This concludes the examination of the Flash side of things. You have now seen how you can tell Flash to send variables to the CGI script and to retrieve data from the CGI script, and what exactly gets sent to the script. You also know how you can make an MC that checks for for the data arrival.

CGI SCRIPT

Let's now have a look at the CGI script itself. Open FLASHFORM.CGI file with your favorite text editor (it's also very helpful if your favorite text editor has syntax highlighting). The script is written in Perl, and is easy to understand even if you only know the basics of Perl (I'm no Perl expert myself either). Green lines are comments, black lines are actual code statements:

#!/usr/bin/perl -w

# specify sendmail program location on the server:
$sendmail = '/dir/dir/dir/dir/bin/sendmail';

# specify address of the email recipient:
$recipient = 'user@domain.net';

# initialize the CGI module and make new CGI object:
use CGI;
$query = new CGI;

# get contents of the variables into which we saved the contents
# of our input fields from the Flash movie (CGI object):
$sender_name = $query->param('nameITF');
$sender_address = $query->param('addressITF');
$message_body = $query->param('messageITF');

# combine name and address into one variable:
$sender = "\"$sender_name\" <$sender_address>";

# fix new lines and carriage returns in the message:
$message_body =~ s/\r\n?/\n/g;

# open the pipe to sendmail program:
open (MAILPROG,"|$sendmail -t -oi") or die "Can't open pipe to $sendmail - $!\n";

# and "print" the new email contents into the pipe:
print MAILPROG "To: $recipient\n";
print MAILPROG "From: $sender\n";
print MAILPROG "Subject: Flash form submission\n";
print MAILPROG "$message_body\n";

# close the pipe to sendmail:
close MAILPROG or die "Couldn't close the pipe to sendmail - $!\n";

# print the plain text content-type header, to tell Perl that we are
# going to output plain text to our Flash movie (CGI object):
print "Content-type: text/plain\n\n";
# output a KEY=VALUE pair we need, setting variable
# "email_sent" inside our Flash movie to "1":
print "email_sent=1";

# end the script:
exit;

The parts that interest us the most are marked in bold. First bold section shows how we GET information from the Flash movie. Our new CGI object contains all the variables that were sent from the Flash movie. These variables are in the KEY=VALUE format, where KEY is the name of the variable in Flash, and VALUE is its value. We need to retrieve the contents of the variables which we saved our input fields' contents into, named "nameITF", "addressITF", and "messageITF". We retrieve them from the CGI object the same way we do it with normal HTML form items, using their names as the keys, like so:

# get contents of input fields from the Flash movie (CGI object):
$sender_name = $query->param('nameITF');
$sender_address = $query->param('addressITF');
$message_body = $query->param('messageITF');

Now we have the contents of the input fields retrieved from the Flash movie and saved as new variables in our script. We do some formatting and cleaning on their contents, build and send a new email - nothing really difficult there. But after we've done what we wanted with them, we have to send some data BACK to the Flash movie - to confirm that email had been sent successfully. So how do we do it? Simple - we just output, or "print", the data as plain-text KEY=VALUE pairs. If we have to return several variables, we separate the pairs with &'s, like so:

variable1=value1&variable2=value2&variable3=value3... and so on

In our case we only have to change the value of a single variable "email_sent" in our Flash movie to 1 - because our checker_mc MC is checking for this to happen, to serve as a confirmation of the email sent successfully. When this happens, checker_mc MC shows the success message in the messageITF_txt input field. So here's what we have to do to update the value of this variable inside our Flash movie:

# print the plain text content-type header, to tell Perl that
# we're going to output PLAIN TEXT to our Flash movie (CGI object):
print "Content-type: text/plain\n\n";
# output the "email_sent=1" key-value pair, setting
# "email_sent" variable to "1" in our Flash movie:
print "email_sent=1";

And THAT, my friends, is it! We're now done. We have successfully done the following things:

sent data from a Flash movie to a CGI script
retrieved the values of the variables we needed from the data received by the CGI script
updated a variable in our Flash movie by sending data back from our CGI script

As you can see, this whole thing is much simpler than it might seem at first.

This concludes the guide. I hope that this guide was helpful in your understanding of the way data is sent between Flash movies and CGI scripts. Before I tried making it work myself, it all seemed incredibly confusing, but once you make it work once it gets a lot less complicated all of a sudden. Main thing for you is to understand the basic mechanics of passing the data between Flash and CGI. Once you get that down, you can build more complex things. CGI can be very useful in Flash sites.

Go back to Flash Guides Main Index

© 2001-2005 Roman Litvinov	Site Map