Creating a User Comment Form

In this section, you create a Flash form that submits user-entered information to a server-side ColdFusion script that e-mails the data to an e-mail address that you specify in the script. By accessing a remote ColdFusion script, you make a Flash movie with five data exchange states: input, send, wait, output, and error. You learn how to submit name/value pairs from Flash to remote URLs and learn how to check the receipt of variables from the ColdFusion script using the LoadVars object. The LoadVars object can detect the loading of the external variable data.

On the CD-ROM 

You can find the ColdFusion script (sendmail.cfm) and supporting Flash documents for this section in the ch29/form folder of this book's CD-ROM. Note that you need a ColdFusion-enabled Web server to configure and use the sendmail.cfm script. We have also included the sendmail.asp script (Microsoft ASP version) and the sendmail.pl script (Perl 5) that we included with previous editions of the Flash Bible, as well as a new sendmail.php script for PHP 4 or higher. The ASP script requires the installation of the free w3 JMail Personal ASP component, available at

• http://tech.dimac.net/

Web Resource 

You can download a trial version of ColdFusion MX 7 at

• www.macromedia.com/software/coldfusion

You can also find installation instructions on the Web site. For a list of preferred ColdFusion hosting providers, check the "ColdFusion Hosting Providers" section of the www.flashsupport.com/links page.

Flash forms are user data entry forms (just like HTML forms) created in Flash 8 using Input text fields. When a user types information in these text fields, the information is stored as a property of the text field instance (text). The values of these properties are assigned to variable names and are then sent to a specified Web server using standard GET or POST communication. These variables are available to the Web server and can be processed there by a server-side program or script. Server-side programs can be written to e-mail this information, manipulate it, store it in a database, or perform many other applications. The same serverside script can also return values to the Flash movie — these can then be displayed or used by the originating Flash movie.

In this exercise, the Flash form solicits feedback from visitors, giving them an opportunity to submit comments, report bugs, or make suggestions for improvement. As each form is submitted, it's e-mailed directly to the e-mail address that you specify in the ColdFusion script.

1. Open a new Flash document (Ctrl+N or z+N), and save it as sendmail_cfm.fla.

2. Rename Layer 1 to labels. Select frame 1 of this layer and assign a frame label of input in the Property inspector.

3. On the labels layer, create keyframes (F6) on frames 10, 20, and 30. Give these keyframes the labels wait, output, and error, respectively. Select frame 40 and press F5 to insert more empty frames at the end of the layer.

4. Create a new layer and name it actions. Select frame 1 of the actions layer, and open the Actions panel. In the Script pane, add a stop(); action. In the Property inspector, add a comment of //setup form in the <Frame Label> field.

5. Create a new layer, and name it text fields. Insert keyframes on frames 10, 20, and 30.

6. On frame 1 of the text fields layer, insert three separate Input text fields. From top to bottom, assign the following instance names to the Input text fields (in the Property inspector): tFromName, tFromEmail, and tComments. The tFromName and tFromEmail text fields should accommodate one line of text, while the tComment field should be set to Multiline in order to hold multiple lines of text. All of the Input text fields should have the Show Border option selected, unless you plan to create your own background graphics. Make each text field long enough to accommodate about 45 characters of text. The comments field should be able to show between five and ten lines of text (see Figure 29-3).

7. Create a new layer, and name it static text. Insert keyframes on frames 10, 20, and 30. On frame 1, add Static text blocks to the left of the text fields, indicating the purpose of each field, as shown in Figure 29-3.

   Note 

   For our example, the Flash movie background color is black, and the Static text is white. You can change the movie's background color by choosing Modify ð Document.

8. On frame 10 of the static text layer (underneath the wait label), insert a Static text block indicating that the information is being sent to the server and that the movie is waiting for confirmation. In our example, we used the text "Checking the server.…"

9. On frame 20 of the static text layer (underneath the output label), insert a Static text block containing a successful receipt of the visitor's information. In our example, we used the text "Thank you. Your feedback was received at:."

10. You can see that you are setting up the output state to display the time that the server received the data (Figure 29-4). The ColdFusion script returns the time and date of the receipt to the Flash movie. On frame 20 of the text fields layer, create a Dynamic text field with an instance name of tReceipt and place it underneath the Static text you just made.

11. On frame 30 of the static text layer (underneath the error label), insert Static text that indicates the data was not successfully received. In our example, we used the text "Sorry, there was an error processing your form."

12. Save your Flash document.

    Now you have all your states defined with placeholder artwork. You can go back later and refine the text and graphics to suit your particular needs. Next, you need to add a function to transfer the data from the text fields to a LoadVars object and send the data to the Web server.

    These actions need to put on the appropriate Flash event handlers. Start by defining a function named sendComments() that creates two LoadVars objects: one to send the data and another to receive the data. The data from the Input text fields is then copied to variables within the sending LoadVars object. The data is then sent to the ColdFusion script using the sendAndLoad() method of the LoadVars object. When the data is received by the ColdFusion script, the Web server will return some confirmation data to the Flash movie, including the time and date the user's comments were received. When this data loads completely into the Flash movie, the movie will then go to and stop on the output frame label.

    Before you define these functions, however, let's add a Button component to the Stage. This component button will initiate the sendComments() function.

13. Create a new layer and name it button. Insert an empty keyframe on frame 10 of this layer.

14. On frame 1 of the button layer, drag an instance of the Button component from the User Interface grouping of the Components panel to the document's Stage.

15. With the component selected, open the Property inspector. Name the instance cbtSend. In the Parameters tab, type Send Comments in the label field. You may need to stretch the width of the Button instance to accommodate the label text.

16. Select frame 1 of the actions layer, and open the Actions panel (F9, or Option+F9 on Mac). In the Script pane, add the code shown in Listing 29-1. This code defines the sendComments() function used by the cbtSend instance.

    Listing 29-1: The sendComments() Function

     1.  import mx.utils.Delegate; 2. 3.  var cbtSend:mx.controls.Button; 4.  var tFromEmail:TextField; 5.  var tFromName:TextField; 6.  var tComments:TextField; 7.  var lvSend:LoadVars; 8.  var lvReceive:LoadVars; 9. 10. var sUrl:String = "http://www.flashsupport.com/sendmail.cfm"; 11. 12. function sendComments(oEvent:Object):Void  { 13.    lvSend = new LoadVars(); 14.    lvReceive = new LoadVars(); 15.    lvReceive.onLoad = function(bSuccess:Boolean):Void { 16.       if (bSuccess && this.success == "1") { 17.          gotoAndStop("output"); 18.       } else { 19.          gotoAndStop("error"); 20.       } 21.    }; 22.    lvSend.fromEmail = tFromEmail.text; 23.    lvSend.fromName = tFromName.text; 24.    lvSend.body = tComments.text; 25.    lvSend.sendAndLoad(sUrl, lvReceive, "POST"); 26.    gotoAndStop("wait"); 27. } 28. 29. cbtSend.addEventListener("click", Delegate.create(this, this.sendComments)); 30. focusManager.defaultPushButton = cbtSend; 31. 32. stop(); 

    This script declares all of the objects present on the stage as variables, in lines 3–6. (Note that the import statement on line 1 utilizes the Delegate class in the script. We'll discuss that class in just a moment.) Lines 7 and 8 declare two LoadVars variables, one to send (lvSend) and one to receive (lvReceive).

    On line 10, the URL of the ColdFusion script is defined using a live server URL we specifically set up for this exercise. If you have installed the ColdFusion script on your local machine or Web server, change the path of this variable to reflect the new location.

    Lines 12 through 27 define the sendComments() function. This function establishes all of the data that the sendmail.cfm script requires for successful operation. Line 12 declares the function and its name, sendComments. The function starts by creating two LoadVars objects, named lvSend (line 13) and lvReceive (line 14). The lvSend object will send the data from the Flash movie, while the lvReceive object will handle the data received from the server.

    Lines 15–21 define an onLoad() handler for the lvReceive object. Here, an anonymous function will be executed when the lvReceive object receives any external data from the Web server script. In this example, if the data is successfully received and the server-side script doesn't encounter any errors (line 16), the Main Timeline will go to and stop on the output frame label. If the data is not received or there is an error in sending the data (line 18), the Main Timeline will go to and stop on the error frame label (line 19).

    Lines 22–24 establish the variables that the ColdFusion script expects to see in the data transmission: fromEmail, fromName, and body. These variables retrieve their values from the appropriate TextField objects in the Flash movie.

    Note 

    You can change the values of the Form.toEmail and Form.subject variables in the sendmail.cfm script to change where the server sends the data from the Flash movie. If you use the live script located on the www.flashsupport.com site, Mr. Reinhardt will receive all of your test e-mails, so please be careful. For security measures, don't include private information such as your own e-mail address inside of an .swf file, including ActionScript code. SWF decompiler utilities can extract any data, including code, from .swf files delivered over the Web.

    Line 25 executes the sendAndLoad() method of the lvSend object that sends the fromEmail, fromName, and body variables to the sendmail.cfm script on our Web server. The lvReceive reference indicates that any output from the sendmail.cfm script should be directed to the lvReceive.onLoad() method.

    After the sendAndLoad() method is executed, the Main Timeline will jump to the wait frame label (line 26).

    In line 29, the sendComments() function is added as a listener of the cbtSend instance. Here, we use the Delegate class to properly scope the goto actions in the sendComments() function.

17. Finally, add a keyframe to frame 20 of the actions layer. With this keyframe selected, open the Actions panel and add the following actions:

     var tReceipt:TextField; var lvReceive:LoadVars; tReceipt.text = lvReceive.timeDate; 

    This action takes the time and date returned by the server, and uses its value for the text property of the tReceipt instance.

18. Save your Flash document again and test it (Ctrl+Enter or z+Return). Type some information into the text fields and click the Send Comments button. If the server script is available, you should see the output state display the time/date receipt from the server.

Figure 29-3: These text fields accept input from your site visitors.

Figure 29-4: The Receipt field will display the time that the server received the Flash form data.

The server script supports either GET or POST methods. Remember, every data exchange with a Flash movie should use input, wait, output, and error states.

On the CD-ROM 

Use the sendmail.cfm script on www.flashsupport.com only for development and/or testing purposes. Do not try to use the script for demanding, high-volume Web sites. Remember that live Flash movies on a Web server can only access server-side scripts on the same server. While you can use the sendmail.cfm script on www.flashsupport.com for local testing in the Flash 8 authoring environment, it will not work once you upload your Flash movie to your own Web server — you'll have to install the sendmail.cfm script (or equivalent) on your own Web server. The same ColdFusion script is available on this book's CD-ROM, in the ch29/form folder. You can find the completed version of the Flash document, sendmail_cfm.fla, in the ch29/form folder. We have also created equivalents of the sendmail.cfm script in other popular middleware languages: sendmail.asp (Microsoft ASP.NET), sendmail.php (PHP 4 or higher), and sendmail.pl (Perl 5 or higher). Note that we do not have live versions of these alternative server-side scripts; you will need to install them on your own Web server to test and deploy them.