Recipe 13.17. Submitting Form Data to the Server

Problem

You want to submit the form data to a server-side script for further processing.

Solution

Use the FormController component. Alternatively, you may write ActionScript code to retrieve the form data and submit it to the server using an ActionScript LoadVars object.

Discussion

Working with forms in Flash has been simplified by many of the components that Macromedia includes in the product. However, it is still a fairly ActionScript-inten-sive process to retrieve the form data and submit it to a script on the server.

Although the required ActionScript is not particularly difficult, it can appear somewhat daunting to those who are new to writing code. And many may prefer a simplified alternative even if they are comfortable writing ActionScript code. Thus the FormController component exists, a custom component that you'll find in the Flash 8 Cookbook components (downloadable from http://www.rightactionscript/fcb).

The FormController component works in the following manner: you create your form using the form controls discussed in the earlier recipes in this chapter, making sure to give each an instance name. Then create an instance of the form controller and, using the graphical user interface, provide the component instance with information about the elements of the form you want it to control. Additionally, you can assign a URL to which the information should be submitted and a button component instance that will be the submit button. The form controller handles the rest (although you'll still need to configure the server-side script).

If you've installed the Flash 8 Cookbook components, you can find the FormController component listed within the Flash Cookbook folder in the Components panel. Drag an instance of the form controller from the panel onto the stage. The component contains artwork that is visible during authoring time so that you can locate the instance on stage in order to set the parameters. However, during runtime the artwork is invisible. Therefore you can place the instance anywhere on stage and it still will not interfere with any other artwork when you view the .swf file.

The form controller has three parameters, all of which must have values for the component to operate correctly. The elements parameter is the way in which you tell the form controller which form controls (text inputs, combo boxes, etc.) it should control. You can specify the values by double-clicking on the Values column to open the Values dialog box. After you have opened the dialog box, click the plus sign to add a new element for each form control that should be managed by the form controller. For each element, you need to set at least one value: the InstanceName value. The InstanceName is the name of the instance of the form control. For all form controls you should specify the instance name of the actual component or text field instance, with the exception of radio buttons. For radio buttons you should specify the name of the radio button group, and just once for the entire group of radio buttons. By default, the data for each form control is submitted to the server with a variable name that corresponds to the form control's instance name. For example, if you have a form control named ccbProducts, the value for that control will be submitted with the variable named ccbProducts. However, because the server-side script may expect very specific values other than what you have named the form controls, you can also specify a FieldName value. The FieldName value determines the variable name by which the value is submitted to the server. Therefore, if you want the value from ccbProducts to be submitted with the variable name PRODUCT_ID, you can specify PRODUCT_ID as the FieldName value for that element. The Message and Validator values are also optional, and they are used for validating form data. The Type parameter defaults to Regular. For any form element that references a standard form control (e.g., text input, combo box), you should leave Type set to Regular. However, you can also create hidden form elements by setting Type to Hidden. A hidden form field does not require any form control on the stage. Rather, it is a way of passing extra values to a server-side script when the form is submitted. If you set Type to Hidden, you should also specify a Value. The Value is what gets passed to the server-side script when the form is submitted. For example, in the program you create in this chapter, the email subject line is passed to the server-side script by way of a hidden form element.

You should include each form control in the elements parameter value, with the exception of the submit button. The submitButton parameter is where you specify the instance name of the button component that you want to use to submit the form data to the server. All you need to do is create the button instance, give it an instance name, and assign that name to the form controller's submitButton parameter. The form controller will handle all the ActionScript code automaticallywithout you having to write any of it.

Additionally, you need to specify a value for the url parameter. The url parameter determines where you are going to submit the form data when the user clicks on the submit button. The value can be either a relative or an absolute URL.

After you've set up the form controls and the form controller, Flash will handle the details for you. Make sure you have the server-side script properly configured and that you are submitting the correct information. The FormController component submits the form data using HTTP POST as URL-encoded name-value pairs. That is the standard way in which form data is submitted on the Web with HTML pages, so scripts that are configured to accept form input from an HTML page should work with the form controller.

If you prefer to write your own ActionScript to submit your Flash form data, you can do so without too much complicated code. In fact, the code is really quite simple. However, depending on how much data you are sending you may find it can get a little lengthy.

The first thing you will want to do is to retrieve the form data. After you've retrieved the form values, you should next construct an ActionScript LoadVars object, assign the values to the object, and call the send( ) method to send the data to the server.

You can construct a LoadVars object using the LoadVars constructor as part of a new statement and assigning the value to a variable. The following example creates a new LoadVars object and assigns it to a variable named lvFormData:

 var lvFormData:LoadVars = new LoadVars(); 

After you've constructed the LoadVars object, you should next assign all the values to custom properties of the LoadVars object. Each property should have the name under which you want the data to be submitted to the server-side script. For example, if you want a particular piece of information to be submitted to the server with the variable name of PRODUCT_ID, you should use the PRODUCT_ID property name:

 lvFormData.PRODUCT_ID = 10; 

After you've assigned all the values to custom properties, tell Flash to send the data to the server by calling the send( ) method. The send( ) method requires that you pass it a parameter indicating the URL to which to submit the data. The following code tells Flash to submit the data to a script named updateData.php on the same server (and same directory) as the SWF:

 lvFormData.send("updateData.php"); 

The following code contains a complete example of the ActionScript code to handle submitting a sample Flash form to a script named updateData.php. The form has three form controls: a combo box named ccbProduct, a text area named ctaComments, and a numeric stepper named cnsQuantity. The values are submitted using variable names of PRODUCT_ID, COMMENTS, and QUANTITY, respectively. The form data is retrieved and sent after the user clicks on a button component instance named cbtSubmit:

 var oListener:Object = new Object( ); oListener.click = function(oEvent:Object):Void {   // First, retrieve the form data and store it to three variables.   var nProductId:Number = ccbProducts.value;   var sComments:String = ctaComments.text;   var nQuantity:Number = cnsQuantity.value;      // Next create the LoadVars object.   var lvFormData:LoadVars = new LoadVars( );   // Add the properties and values.   lvFormData.PRODUCT_ID = nProductId;   lvFormData.COMMENTS = sComments;   lvFormData.QUANTITY = nQuantity;   // Send the data to the script.   lvFormData.send("updateData.php"); }; cbtSubmit.addEventListener("click", oListener); 

The preceding code could be simplified somewhat. The values could be retrieved from the form controls and assigned to the properties of the LoadVars object in one step instead of the intermediate step of assigning the values to variables. The extra step is added in the preceding code merely to clarify the process.