By David Golden
Senior Technical Writer
Macromedia, Inc.

With Macromedia Flash and ColdFusion Server, you can extend Web application user interfaces beyond static HTML. Using the Flash Player, you can build rich, highly-interactive Web applications and user interfaces, including:

• Ability to place objects and text anywhere on the page
• Flexible manipulation of object and text appearance
• Fast, lightweight applications using vector-based animation's efficient use of bandwidth
• Consistent presentation across browsers and platforms

At the same time, HTML and the Flash Player share a common characteristic: HTTP. Because the Flash Player uses HTTP to communicate with other files over the Web, passing data between ColdFusion Server and Macromedia Flash closely resembles the process of passing data between two Web pages.

This technical brief describes the following basics of using Macromedia Flash and ColdFusion together:

• The basics of dynamic Macromedia Flash
• Using HTTP methods with Macromedia Flash and ColdFusion

You can also use XML and WDDX to transfer data between ColdFusion Server and Macromedia Flash. For more information, see the online Help in Macromedia Flash and ColdFusion Server.

To benefit fully from this technical brief, you should possess some knowledge of the Macromedia Flash authoring environment, ActionScript, and experience publishing FLA files to SWF files. If you have not developed Macromedia Flash applications previously, before proceeding with this tutorial, you should review the product tutorials listed on the Help menu in the Macromedia Flash authoring environment.

Software requirements and configuration

For this tutorial, you need the following software installed on your computer:

• ColdFusion Server 5
• Macromedia Flash 5
• ColdFusion Studio 4.5.2

If you do not own these products, you can download evaluation versions from the Macromedia Web site.

The following figure describes how an example dynamic Macromedia Flash application might work. In the figure, the CFM page calls the Macromedia Flash movie (SWF file). Next, the Flash movie communicates with another CFM page, which performs any kind of processing or queries to a database. When the processing is complete, the CFM page returns the name-value pairs to the Flash Player. Finally, the Flash Player shows the results to the user.

Figure 1: A sample dynamic Macromedia Flash application

Here are four simple rules to keep in mind when writing CFML for Macromedia Flash:

1. When using the HTTP methods GET and POST, use only name-value pairs to pass variables to Macromedia Flash.
2. Separate name-value pairs with ampersands (&). An ampersand must also preceed the first name-value pair.
3. To suppress extraneous HTML output from a ColdFusion template, use the cfsetting tag with the enableCFOutputOnly attribute enabled.
4. If a ColdFusion template takes longer than normal to process, insert a flag in the form of an extra name-value pair. This flag acts as a signal to Macromedia Flash that ColdFusion Server has finished processing the template.

To pass a variable to Macromedia Flash, you must use the name-value pair syntax name=value. The following example sets the user ColdFusion variable's value to Julie and the Macromedia Flash name variable to the same value:

<cfset user=Julie>
<cfoutput>
	name=#user#
</cfoutput>

When you run this code, a Web browser simply outputs name=Julie. To pass this variable into a Macromedia Flash movie, follow these steps:

1. Copy and paste this code into a blank document in ColdFusion Studio.
2. Prefix name=#user# with &. The ampersand acts as marker for Macromedia Flash.
3. In the Web root, save the file as flashtest.cfm.
4. In the Macromedia Flash authoring environment, create a movie that contains a simple text box.
5. In the Text Options panel, select Dynamic Text and enter "name" in the Variable text field.
6. Select the first frame in the timeline, and open the Actions panel (Ctrl+Alt+A).
7. Apply the loadVariables action. Enter the fully qualified URL to flashtest.cfm, such as http://127.0.0.1/flashtest.cfm.
8. Save the file as movietest.fla.
9. Test the movie.

The word "Julie" displays in the Flash Player (see Figure 2).

Figure 2: The dynamic text box displays the value passed from ColdFusion.

In the ColdFusion template, you can perform any kind of processing, such as database queries, calls to other pages, or if/then logic; However, the name-value pairs must remain intact. In addition, remember to allow enough time in your Macromedia Flash movie for the ColdFusion template to process.

Using multiple Macromedia Flash name-value pairs

To pass multiple variables, you append name-value pairs separated by ampersands in a string. For example, to pass first name, last name, and department to a Macromedia Flash movie, the CFML would look like this:

<cfset fname="Julie">
<cfset lname="Einstein">
<cfset dept="Modeling">
<cfoutput>
	&fname=#fname#&lname=#lname#&dept=#dept#
</cfoutput>  

Notice that name-value pairs are represented in one string and are separated by ampersands.

To pass these variables to Macromedia Flash, follow these steps:

1. In ColdFusion Studio, copy and paste the previous code into flashtest.cfm.
2. Save the file.
3. In the Macromedia Flash authoring environment, create a movie with three text boxes, make them dynamic, and name them fname, lname, and dept.
4. Save the file as movietest2.fla.
5. Test the movie.

The words "Julie", "Einstein", and "Modeling" display in the Macromedia Flash movie text box (see Figure 2).

Figure 3: The dynamic text boxes display the values passed from ColdFusion.

Suppressing extraneous HTML output

When using the HTTP methods GET or POST, Macromedia Flash recognizes only name-value pairs as variables, so ColdFusion templates must generate only those values. Therefore, you must suppress all other HTML. To do that, use the cfsetting tag with its enableCFoutputOnly attribute enabled.

For an example, look at the following code:

<cfsetting enableCFoutputOnly="Yes">
<cfset fname="Julie">
<cfoutput>
&fname=#fname#
</cfoutput>  

Notice that no closing cfsetting tag is used.

Inserting a "finished" flag

If a ColdFusion template contains code that takes longer than normal to process, include an extra name-value pair at the end of the string. This name-value pair acts as a flag to Macromedia Flash that ColdFusion has finished processing the page. The following example shows the trailing value pair finished=1:

<cfsetting enableCFoutputOnly="Yes">
<cfset fname="Julie">
<cfoutput>
&fname=#fname#&finished=1
</cfoutput>  

In Macromedia Flash, you must add two more keyframes and apply the following ActionScript to the second frame:

onClipEvent (load) {
    if (finished == 1) {
        gotoAndPlay (3);
    } else {
        gotoAndPlay (1);
    }
}

The Flash Player proceeds through Macromedia Flash movies (SWF files) one frame at time, just like a movie projector. Thus, the Flash Player loads the variables from flashtest.cfm in frame 1. When frame 2 loads (onClipEvent (load), it checks for the existence of if (finished == 1). If ColdFusion passes finished == 1, the Macromedia Flash movie proceeds to frame 3 (gotoAndPlay (3). If ColdFusion does not pass finished == 1, the Flash Player returns to frame 1 (gotoAndPlay (1)) and tries to load the variables again.

Using the HTTP methods GET and POST, Macromedia Flash can pass variables to ColdFusion templates just like any other Web page. Further, using the ActionScript action getURL, you can open a separate Web browser window to display the results of a ColdFusion template. In addition, using the ActionScript action loadVariables , you can pass variables between ColdFusion and Macromedia Flash without leaving the Flash Player environment.

The following sections explain how to use the getURL action with ColdFusion. For more information on the loadVariables action, see the online Help documentation in the Macromedia Flash authoring environment.

Using getURL with the GET method

The getURL action opens a second browser window when executed, which is especially useful if you want to send the user outside of the Macromedia Flash environment. In addition, you can pass variables using the GET method to the specified URL.

To find out how to use the GET method, follow these steps:

1. In ColdFusion Studio, open flashtest.cfm. Replace the existing code with this code:
   

   <cfsetting enableCFoutputOnly="Yes">
   <cfoutput>
   	First Name: #URL.fname#<br>
   	Last Name:  #URL.lname#<br>
   	Department: #URL.dept#
   </cfoutput>
   

   Notice that the cfset tags were removed and the prefix URL was added to all variables.



2. Save the file.
3. In the Macromedia Flash authoring environment, create a movie with three text boxes.
4. In the Text Options panel, select Input Text. In the Variable text field, enter fname in the first text box, lname in the second, and dept in the third.
5. Create a button, and convert it to a symbol.
6. Apply the following ActionScript to the button:

   on (press) {
       getURL ("http://127.0.0.1/flash/flashtest.cfm", _blank, "GET");
   }
   

   This ActionScript tells the Flash Player that when the button is released, open a Web browser window, and using the GET method, to send the variables entered by the user in the text boxes to flashtest.cfm.



7. Save the file as gettest.fla.
8. Test the movie.

In the following Macromedia Flash movie, try it for yourself.

To view this demo, you need the latest version of the Macromedia Flash Player.
Download the free Macromedia Flash Player now.

Using getURL with the POST method

To send variables using the getURL action with the POST method, you only need to make a few changes to the GET method example.

To create this example, follow these steps:

1. In ColdFusion Studio, open flashtest.cfm. Replace the existing code with this code:

   <cfsetting enableCFoutputOnly="Yes">
   <cfoutput>
   	First Name: #FORM.fname#<br>
   	Last Name:  #FORM.lname#<br>
   	Department: #FORM.dept#
   </cfoutput>
   

   Notice that the variable prefixes are changed from URL to FORM.
2. Save the file as posttest.cfm.
3. In Flash, open gettest.fla.
4. Replace the existing ActionScript applied to the Submit button with the following ActionScript:

   on (press) {
       getURL ("http://127.0.0.1/flash/posttest.cfm", _blank, "POST");
   }
   

   Notice that only the file name and the HTTP method are changed.



5. Save the file as posttest.fla.
6. Test the movie.

In the following Macromedia Flash movie, try it for yourself.

To view this demo, you need the latest version of the Macromedia Flash Player.
Download the free Macromedia Flash Player now.

ColdFusion-powered Macromedia Flash can do much more than just pass simple text strings. You can manipulate almost any attribute in the Macromedia Flash environment, such as colors, shapes, or sounds. You are limited only by your imagination.

In addition, you can use XML and WDDX to pass data between ColdFusion and Macromedia Flash. For more information, see the Macromedia Flash and ColdFusion Server documentation.

The following list presents some of the important points in this technical brief:

• You can create dynamic Macromedia Flash applications quickly and easily with Macromedia Flash and ColdFusion Server.
• Macromedia Flash and ColdFusion Server can communicate through HTTP operations, much like HTML form pages.
• You must have some knowledge of ActionScript to create dynamic Macromedia Flash movies.
• You can perform any kind of ColdFusion processing, such as database queries, conditional logic, or calls to other ColdFusion pages, in the ColdFusion page that the Macromedia Flash movie calls. However, when the GET and POST methods are used, you must follow the name-value pair syntax for the string that is passed to Macromedia Flash.
• Use the getURL and loadVariable actions in ActionScript to interact with ColdFusion Server.

For more information on other methods of integrating Macromedia Flash and ColdFusion Server, see the Macromedia Flash and ColdFusion Server documentation. On the Macromedia Web site, you can find additional resources in the Macromedia Flash and ColdFusion Support forums.