ColdFusion Article

Getting started with ColdFusion MX and Macromedia Flash Remoting

One of the new, cool features of Macromedia ColdFusion MX is Macromedia Flash Remoting. Macromedia Flash Remoting allows you to use ColdFusion MX functionality in your Macromedia Flash movies easily using familiar Macromedia Flash syntax and objects.

What you'll learn

This article walks through creating a simple Macromedia Flash Remoting example. The SWF will use Macromedia Flash Remoting to call a ColdFusion MX component (also known as a CFC) on the server. The ColdFusion component will return a string which will be loaded into Macromedia Flash and displayed.

Prerequisites

1. Download the tutorial files, flash_remoting.zip (35 KB)

   Create a folder at cf_webroot\com\macromedia\test. Unpack the ZIP file into the test folder. Please note that this tutorial refers to cf_webroot throughout its steps. Your cf_webroot varies based on your installation location.

2. Install the required software:

   • Macromedia Flash MX
   • Macromedia ColdFusion MX
   • Flash Remoting Components for Macromedia Flash MX

   You can download trial versions for any of the software listed here. After installing the software, follow the installation wizards and ensure that all software is correctly installed.

Creating the server-side code

The server-side code is a simple ColdFusion component.

It is included in the file, HelloWorld.cfc in the com/macromedia/test folder. The file name HelloWorld.cfc determines the service name for the component. In this case, the service name is HelloWorld. If you open HelloWorld.cfc in a text editor, you will see the following code:

<cfcomponent name="HelloWorld">

	<cffunction name="sayHello" access="remote">
		<cfreturn "Hello World">
	</cffunction>

</cfcomponent>

As you can see, creating a basic component is pretty simple. First, it creates the component by using the cfcomponent tag. Although the component represents a Macromedia Flash Remoting service, by itself, it does nothing.

In order to make the component do something, add the cffunction tag to it. This adds a method to the component. The component has a cffunction tag named "sayHello," with the cfreturn tag nested within it. When you call this component, it returns a "HelloWorld" string to whatever (a URL, a service, and so on) called the method.

Note: You can have as many functions inside of a component that you would like, but this example will only have one function in its component.

Notice that the access attribute value is "remote" within the cffunction tag. This attribute is required if you want your Macromedia Flash movies (or other remote services) to access the component methods. That's all you need to do to create component. Note that the file is located at:

coldfusionmx_webroot\com\macromedia\test\HelloWorld.cfc

Why did I instruct you to place the files in that folder? Components are not referred to by just their name, but also by their location (in this case coldfusionmx_webroot \com\macromedia\test\). Placing your component in the com\macromedia\test folder accomplishes the following:

1. It ensures that another developer on your team doesn't overwrite your "HelloWorld" component with her own "HelloWorld" component..

2. It is a preferable way to organize your components.

You have probably noticed that com/macromedia is simply macromedia.com in reverse. You should use your own domain name for the components that you create, such as net/foo for foo.net.

At this point you could start building Macromedia Flash code to access the component, but first, make a simple ColdFusion page to ensure your component works. Testing now makes it is easier to debug any problems that may arise once you start working with Macromedia Flash MX.

In the cfusionmx_webroot/com/macromedia/test/ directory, there is a file named test.cfm with the following code inside it:

<cfoutput>
	<cfinvoke 
		component="com.macromedia.test.HelloWorld" 
		method="sayHello" 
			returnVariable="message" 
	/>
	#message#
</cfoutput>

The file test.cfm uses the cfinvoke tag to call the component and then print the component's output with the cfoutput tag. Take a quick look at the cfinvoke tag's attributes to take a closer look at what's going on.

The following code:

component="com.macromedia.test.HelloWorld"

specifies which component will be called. The path, com.macromedia.test.HelloWorld points to the com\macromedia\test\HelloWorld file relative to cf_webroot folder.

The following code:

method="sayHello"

specifies which function or method to execute within the component.

The following code:

returnVariable="message"

specifies the variable name to store any data returned from the component. You will use this variable to return the string from the component method. Use the cfoutput tag to display the variable in the web browser.

Save the ColdFusion page, test.cfm, and browse it in a web browser, at http://localhost/com/macromedia/test/test.cfm (change the domain name, or add a port number as necessary for your setup). The message "Hello World" displays. If it doesn't display or if you receive an error, check your component code, the CFML test page, and the URL typos.

You've just experienced the power of components. They allow you to create modular code that can be used in multiple ways, and even by multiple programs (in this case ColdFusion MX and Macromedia Flash MX). Now you're ready to connect to your component with Macromedia Flash MX.

Creating the client-side code in Macromedia Flash MX

Create a new Macromedia Flash movie, and then open it up with Macromedia Flash MX. In the folder where you unpacked the ZIP file for this tutorial, find the Macromedia Flash movie named gatewayHelloWorld.fla.

The Macromedia Flash movie you'll create will be simple: It will make a connection to the server, call the method on HelloWorld.cfc, which will load the data from the server, and display it in the output window. First, look at the ActionScript for the Macromedia Flash movie. Below is a step-by-step walkthrough of the code. The movie has one frame as shown below.

Figure 1. Timeline

The ActionScript code is as follows:

#include "NetServices.as"
#include "NetDebug.as"

function Result()
{
	//receives data returned from the method
	this.onResult = function(result)
	{
		trace("Data received from server : " + result);
	}

	this.onStatus = function(error)
	{
	trace("Error : " + error.description);
	}
}

NetServices.setDefaultGatewayUrl("http://localhost:8500/flashservices/gateway");
var gw = NetServices.createGatewayConnection();
var server = gw.getService("com.macromedia.test.HelloWorld", new Result());
server.sayHello();

First, the ActionScript libraries appear in the application code:

#include "NetServices.as" 
#Include "NetDebug.as"

The ActionScript libraries are required. They contain the ActionScript code and objects necessary to communicate with Macromedia Flash Remoting. NetDebug.as is used to debug the communication between Macromedia Flash and the server. When NetDebug.as is included, you can then view all of the client/server communication by opening the NetConnection panel within Macromedia Flash MX (Window > NetConnection Debugger).

Next, the movie creates a new ActionScript class called Result. It uses the methods in an instance of the class to catch and manipulate the data received from the server.

function Result()
{

	this.onResult = function(result)
	{
		trace("onResult : " + result);
	}

	this.onStatus = function(error)
	{
		trace("onStatus called : " + error.description);
	}
}

This creates a Result class with two methods. The first method:

this.onResult = function(result)
	{
	trace("Data received from server : " + result);
	}

retrieves the response from the component on the server. Whenever data from the server loads, it calls the onResult method. In this case, the application code prints the response from the server to the output window in Macromedia Flash MX using the trace() method.

Next, the application code creates a function named onStatus. This is called if an error occurs when trying to load the data from the server. When an error occurs, it's passed to the method. You can access the error description through the description property, as it is done in this method. In this case, it prints the error message from the server to the output window in Macromedia Flash using the trace() method. The code below shows this scenario:

this.onStatus = function(error)
	{
	trace("Error : " + error.description);
	}

The object that contains the methods does not need to be named Result.

Once you have created the Result class, you're ready to connect to the server. First, in the code, set the path to the ColdFusion MX server, with the following code. If your ColdFusion MX server is running on a different port or domain name, please change the URL in the following ActionScript accordingly.

NetServices.setDefaultGatewayUrl(http://localhost:8500/flashservices/gateway);

Next, use the NetConnection object to connect to the ColdFusion MX server. Use following code :

var gw = NetServices.createGatewayConnection();

Note that the Macromedia Flash movie does not connect to the server at this point. You can think of the object returned by this code as a connection to the server. Next, get a reference to the component on the server that you want to access:

var server = gw.getService("com.macromedia.test.HelloWorld", new Result());

Notice that two parameters are passed to the getService method. The first parameter, com.macromedia.test.HelloWorld is the path to our component, and defines the component that you are connecting to (you may need to change this parameter based on the location of your component). The second parameter, new Result(), creates a new instance of the Result object. Passing the new Result ()instance to the method indicates that the method should call the functions in that object (the onResult, onStatus methods) whenever the server sends data or information.

Note: It may seem odd to pass an instance to the Result class by passing a new Result().

We could have done the following:

var r = new Result(); 
var server = gw.getService("com.macromedia.test.HelloWorld", r);

However, since you do not need to use the instance of the class once the data is loaded, you don't need to save an instance of it within a variable.

The getService() method returns an object that represents the actual component on the server. In this case, it is stored in a variable called server. Now if you want to call a method in your component, call it through the server variable, as follows:

server.sayHello().

At this point, the code calls the service and component on the server. The following describes the process:

1. Macromedia Flash MX calls the ColdFusion MX server, passing the component name to the server.

2. Macromedia Flash Remoting locates the component based on the path specified by Macromedia Flash, and then calls the function within the component also specified by Macromedia Flash.

3. The component function returns a string.

4. The gateway receives the string returned from the function and passes it back to the Macromedia Flash movie.

5. Macromedia Flash receives the string from the server (through Flash Remoting), and passes it to the onResult() method for the object specified (in this case, the Result class).

6. The onResult method processes the data.

Of course, you don't really need to be aware of this process, since ColdFusion MX, Macromedia Flash MX, and Macromedia Flash Remoting automatically take care it.

Running the example

To run the example, and test the movie, use the following steps.

1. Verify that the ColdFusion MX server is running.

2. Within Macromedia Flash MX, test the movie by going to Control > Test Movie. "Hello World" appears in the Macromedia Flash MX output window, as follows:

   

   Figure 2. Test movie example

3. Publish your Macromedia Flash movie.

4. Browse your Macromedia Flash movie (SWF) in a browser. Note that the ColdFusion component produces the "Hello World" data in the Macromedia Flash movie.

You learned how to create a simple Macromedia Flash movie that uses Macromedia Flash MX, ColdFusion MX and Macromedia Flash Remoting. Displaying "Hello World" may not seem that impressive or useful. However, remember that "Hello World" is simply a "string" object type. You could change your ColdFusion component so that it returns other types of data, such as arrays, structures, or database query results. Furthermore, you could use the following server-side code to populate your arrays, structures, or database queries:

• ColdFusion Components (as in this example)

• ColdFusion pages

• Server-side ActionScript

• Java

• Web Services

These ColdFusion MX features help you leverage Macromedia MX functionality in your website. These topics are featured in the Application Development Centers for ColdFusion MX, Macromedia Flash MX, and Dreamweaver MX.

About the Author

Mike Chambers has been creating applications using primarily Macromedia Flash, Generator, and Java for the past three years. He also has experience working with ASP, JSP, PHP, and ColdFusion. Recently he has been working with Macromedia Flash and embedded devices, contributing to the "Macromedia Flash Pocket PC Player Authoring Kit." He is coauthor of "Flash Enabled" and “Generator and Flash Demystified."

Mike received his Masters in International Economics and European Studies from the John Hopkins School of Advanced International Studies (SAIS) in 1998.