TechNote (Archived)

How to create and submit a form in Flash 4

Use forms to receive and transfer user input
Forms are a method of collecting user input from a Web site. Forms built using HTML are a combination of standard HTML buttons, checkboxes, radio buttons, text fields, lists, images, and menus. The user interacts with each of these interface elements and the information is then sent to a server-side application or client-side script via a "submit" button.

In Flash, forms serve the same function as they do in HTML, but the design and layout of the interface elements can be customized with complete flexibility. When HTML is used to create forms, all the interface elements are visually and functionally identical. In contrast, Flash provides the developer with the ability to create form elements with any aesthetic design or functionality imaginable.

Two common uses for forms are to collect specific information and send it via e-mail, or to submit an order form with a user's personal information, including credit card data, to an e-Commerce application. Flash provides the tools necessary for the designer to create the interface elements and their layout on the page to generate the "front-end" of this process, called a "form." The data inputted into the form fields will ultimately need to be passed to a server-side application (such as a CGI script or an Active Server Page) for processing.

Build a form using editable text fields
In Flash, a form is one or more editable text fields into which a user can enter information. For instruction on creating an editable text field please see the example at the bottom of this TechNote. Each editable text field has a unique variable name whose value is the content of the text field.When a user enters data into a form field, she sets the value of the associated variable equal to the entered text. For example if an editable text field has the variable name "Subject" and a user enters "Catalog," the string passed from Flash would be: Subject=Catalog. For this reason, the variable names in Flash must match the variable names in the CGI or ASP that will process the form information.

The information collected by the interface elements will be submitted to a server-side application (such as a CGI script or an Active Server Page) via either a Get URL or Load Variables action.You don't need to be able to program in Perl or write an ASP to be able to use a form in your Flash movie. There are plenty of resources on the Web that allow you to download a script for free (such as Matt's Script Archive) and chances are your ISP has a ready-made formmail CGI for public use. For a CGI or ASP primer, check out Webmonkey's "CGI Scripts for Fun and Profit" or "Introduction to Active Server Pages."

Match the Flash form field variable names to the CGI variable names
Once you get a back-end script, you will need to make sure that the Flash form can provide it with the information that it's looking for. Whether it's a CGI or an ASP, the script will have a set of named variables. These variables are containers for the user inputted information and need to correspond with the text field variables in the Flash movie. For example, in a formmail CGI which gathers information and sends it as an e-mail to a specified recipient, the variables might be called: $Name, $Address,$Subject, and $Body. In a Perl script the variable names are prefaced by a $. In Flash, however, the variable names do not need to be prefaced by a $ and in fact, the $ is an illegal character in a Flash variable name. In this example, the text fields in the Flash movie would be: Name, Address, Subject, and Body.

Adding hidden form fields to the Flash movie
Back-end scripts frequently require certain hidden variables. For example, a form may contain a hidden variable that sets the email recipient of the data processed by the CGI script. In HTML, this input is written as:
<INPUT TYPE="hidden" name="recipient" value="email@address.com">. This tells the browser to send a variable named "recipient" to the address contained in value, without displaying this field in the HTML page.

Adding hidden fields to a Flash form is simple. Flash does not have to display a variable to know that it is there. Just setting the value of the variable is enough. Flash will submit all variables in the timeline that contains the button or frame action that posts the form data.

So to add a hidden variable, just add a frame script in the first frame of the timeline that does "Set Variable" action setting the value of the variable. For example:

Set Variable: "hiddenVariableName" = "hiddenVariableValue"

Get URL and Load Movie actions send form values to a CGI or other server-side application
Get URL and Load Variables are both Flash actions that send HTTP requests. Both requests are targeted at a particular URL, and may optionally be accompanied by Flash variables sent using either the GET or POST HTTP request methods. There are two decisions when creating a form: whether to use the Get URL or Load Variables action, and whether to use the GET or POST request method.

Let's start with the second question first. The GET method appends the variables to the end of a URL, and is used when a small number of variables are involved. The POST method sends the variables in a separate header, and is capable of sending much longer strings. If the data entered in the form will definitely be less than 255 characters, GET or POST can be used. If the form fields can contain large chunks of text-more than 255 characters-select the POST method.

The answer to question number one depends on what, if anything, the server will return to the browser after processing the form. The Load Movie and Get URL actionsboth send HTTP requests the same way. They differ in how they handle the HTTP server's response to the request. Get URL directs the server's response to the HTML browser. The HTML browser will display the response in the window or frame specified in the request's target window field.

Load Variables expects a text file as the server's response and loads it into a numbered level of the Flash movie, or into a target movie clip of the Flash movie. The response must be formatted like the MIME content type application/x-www-urlform-encoded which is used for CGI scripts and ASP pages. This format consists of name=value pairs separated by & characters. An example might look like: name=John+Smith&company=Macromedia&city=San+Francisco&state=CA.Please note that when using a Load Variables action, the location into which the variables will be returned must be specified in the Location field of the Load Variables action. For example, if all the text fields in the form are in a movie clip on the main timeline with the instance name "formMC," the Location in the Load Variables action dialog should say Target: "/formMC."

Both the Get URL and Load Variable actions will send variables to an external application such as a CGI or an ASP. The decision depends on the desired result.Get URL will open a new window or replace the current window with the result. Load Variables will set variables in the Flash movie as long as the data is in the proper format as mentioned in the paragraph above.

A form example

The following example uses a Get URL action and the POST method.

To create a form in Flash do the following:

1	Select the Text tool and choose the editable text field modifier.
2	Drag a text field onto the stage.
3	Choose Modify > Text Field to set the variable name of the text field.
4	To submit the contents of the text field, first drag a button out onto the stage. Then choose Modify > Instance.
5	Select the Actions tab and choose the Get URL action.
6	Enter the path to the CGI application in the URL field, and choose the method to send the information in the Variables field. The GET method appends the variables to the end of the URL and is used to send a small number of variables. POST sends the variables in a separate header and is capable of sending much longer strings.