By: Mike Chambers

July 10th, 2002

Reader Rating: 7.5

One of the cool new 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.

Today, we’ll walk through 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.

Getting Started

1. Download the tutorial files.

All the files you’ll need can be downloaded here (35 KB) [1].

Create a folder at cf_webroot\com\macromedia\test. Unpack the ZIP file into the test folder. Note that throughout the tutorial, we’ll refer to cf_webroot Your cf_webroot varies based on your installation location.

2. Install the required software

The software we’ll use through the tutorial includes:

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

You can download trial versions of the software listed here. Follow the installation wizards to ensure that all software is correctly installed.

Creating the Server-side Code

The server-side code is a simple ColdFusion component. It’s included in the file HelloWorld.cfc in the com/macromedia/test folder, and note that the file name HelloWorld.cfc also determines the service name for the component. So in this case, the service name is HelloWorld. If you open HelloWorld.cfc in a text editor, you’ll see this:

<cfcomponent name="HelloWorld">

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

</cfcomponent>

As you can see, it’s pretty simple to create a basic component – we simply use the cfcomponent tag. Although the component represents a Macromedia Flash Remoting service, it does nothing by itself.

In order to make the component function, we add the cffunction tag -- which is a method -- to it. Thus, the component now contains a cffunction tag named "sayHello," in which the cfreturn tag is nested. And when you call this component, it returns a "HelloWorld" string to whichever URL or service etc. called the method. You can have as many functions as you’d like inside a component, but for this example, we’ll include just the one.

Notice also that the access attribute value is "remote" within the cffunction tag. This attribute is required if you want Flash movies (or other remote services) to access the component methods.

And that’s it! We’ve successfully created a component. Note that the corresponding file is located here
coldfusionmx_webroot\com\macromedia\test\HelloWorld.cfc

Why did I instruct you to place the files in that folder? Well, components aren’t referred to just by name – they’re also referred to by location (in this case, coldfusionmx_webroot\com\macromedia\test\). So by placing your component in the com\macromedia\test folder, you:

1. Ensure that another developer on your team doesn't overwrite your “HelloWorld" component with a "HelloWorld" component of his or her own.
   
2. adopt best practice organization of your components.

And finally, you’ve probably noticed by now that com/macromedia is simply macromedia.com in reverse. Likewise, you should use your own domain name for the components that you create, such as net/foo if your site’s called foo.net.

So, what’s next? At this point you could start building Macromedia Flash code to access your component, but first, let’s make a simple ColdFusion page to ensure that the component actually works. If we test it now, it’ll be easier to debug any problems that may arise than it would be to debug once we’d started working with Macromedia Flash MX.

In the cfusionmx_webroot/com/macromedia/test/ directory, there is a file named test.cfm which contains the following code:

<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. Let’s now take a quick look at the cfinvoke tag's attributes to understand what's going on.

The code which reads:

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 the function or method that is to be executed within the component.

The next section:

returnVariable="message"

specifies the variable name we’ll use to store any data returned from the component. We’ll use this variable to return the string from the component method, and the cfoutput tag to display the variable in the Web browser.

Save the ColdFusion page, test.cfm, and view 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 particular set up). The message "Hello World" should display. If it doesn't, or you receive an error, check your component code, the CFML test page, and the URL for typos.

You've just experienced the power of components! They allow you to create modular code that can be used in many 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 we'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, though, let’s 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.

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, as 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 view all 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 is shown here. 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 illustrates this scenario:

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

Note that 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, 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, just change the URL in this ActionScript accordingly.

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

Next, use the NetConnection object to connect to the ColdFusion MX server:

var gw = NetServices.createGatewayConnection();

Note that the Macromedia Flash movie does not connect to the server at this point – instead, think of the object returned by this code as a connection to the server. Next, obtain a reference to the component that resides on the server 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 -- it defines the component that you’re 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, and onStatus methods) whenever the server sends data or information.

It may seem odd that we’re passing an instance to the Result class by passing a new Result(). We could have done the following instead:

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

However, as, in this case, we won’t need to use the instance of the class once the data is loaded, we 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. This is how it works:

1. Flash MX calls the ColdFusion MX server, passing the component name to the server.
   
2. Flash Remoting locates the component based on the path specified by Flash, and then calls the function within the component (also specified by Flash).
   
3. The component function returns a string.
   
4. The gateway receives the string, and passes it back to the Flash movie.
   
5. 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.

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 Flash MX, test the movie by going to Control > Test Movie. "Hello World" appears in the Flash MX output window, as follows:
   image
   
3. Publish your Flash movie.
   
4. View your Flash movie in a browser. The ColdFusion component produces the "Hello World" data in the Flash movie.

Conclusion

Now you know how to create a simple Flash movie that uses Flash MX, ColdFusion MX and Flash Remoting. Sure -- displaying "Hello World" may not seem that impressive or useful, however, remember that "Hello World" is simply a "string" object type. You can easily 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 on your Website. These topics are featured in the Application Development Centers for ColdFusion MX, Macromedia Flash MX, and Dreamweaver MX.

Reproduced with permission from Macromedia

[1] http://webmasterbase.com/examples/startremoting/startremoting.zip