This article is targeted towards people who already have experience in Flash Remoting, you can find more info on Flash Remoting at: http://www.macromedia.com/support/flash_remoting/

Introduction

Around the days when I first started working with Flash Remoting, I was working with the FTree Component and filling it from a hierarchical structure on the back-end. It was basically an admin tool for editing the structure (adding nodes, deleting them, renaming them) I quickly ran into something that frightened me though, asynchronous calls. Asynchronous by definition means, not simultaneous. Which means you use result handlers rather than direct assignment to a variable:

/* incorrect */
result = myService.someMethod();
/*correct*/
myService.someMethod();
function someMethod_Result(res){
   //…
}

Default Responder

/* typical stuff */
#include “NetServices.as”

NetServices.setDefaultGatewayURL("http://localhost:8500/flashservices/gateway");
gatewayConnection = Netservices.createGatewayConnection();

Above is syntax you should recognize. The setDefaultGatewayURL() method sets the gateway the Flash IDE will use. And finally createGatewayConnection() creates the connection to our server, in this case localhost. The documentation specifies two ways to then connect to a service. One way defines a defaultResponder, and the other one does not. In this section we will discuss the defaultResponder, the next section discusses custom responders.

Default Responder:
myService = gatewayConnection.getService("some.service.here",this);

If you define a defaultResponder, a method will be called within it having the name of the service’s method call appended with “_Result”. This is confusing to read so a complete example is below.

Actionscript:

#include "NetServices.as"
NetServices.setDefaultGatewayURL("http://localhost:8500/flashservices/gateway");
gatewayConnection = Netservices.createGatewayConnection();

myService = gatewayConnection.getService("HelloWorld",this);
myService.getString();

function getString_Result(str){
  trace("Received String: "+str);
}

CFC:

<cfcomponent>
   <cffunction name="getString" access="remote" returntype="string">
      <cfreturn "Hello World">
   </cffunction>
</cfcomponent>

You can find the complete examples in the HelloWorld.cfc and defaultResponder.fla. HelloWorld.cfc should be put in the wwwroot folder of ColdfusionMX.

This is ok for basic applications that don’t need to distinguish one call from another, which is where I ran into my original problem. The application had to guarantee that even if the order of the calls was messed up, that the user interface would stay in sync. The answer to this problem was creating a custom responder for each call to the service.

If you have used LoadVars in the past this will be very familiar to you. To pass in multiple variables all you need to do is separate them by using an ampersand (&). One example is:

Custom Responder

In the previous section you received a brief overview of defining a default responder. This section will discuss creating custom responders for each method call. The first step in defining your custom responder is to call the getService() method but without the second parameter. Example below.

No Default:
/* Look! No second parameter */
myService = gatewayConnection.getService("some.service.here");

The next step is creating a class that you will pass in with each method call. This class must have an onResult() method. The onResult() method receives the return from the remoting call. We can build on the HelloWorld example above and use the same CFC. However we have changed the ActionScript code around a bit to now use our custom class. An example is below.

#include "NetServices.as"

NetServices.setDefaultGatewayURL("http://localhost:8500/flashservices/gateway");
gatewayConnection = Netservices.createGatewayConnection();

myService = gatewayConnection.getService("HelloWorld");

function StringResponder(prepend){
  this.prepend = prepend;
}

StringResponder.prototype.onResult=function(str){
  trace(this.prepend+str);
}

myService.getString(new StringResponder("Received String: "));
myService.getString(new StringResponder("Received Another String: "));

In this example we have created a custom class called StringResponder for handling the return of our service. As you see this time onResult() is called in place of getString_Result(), this is because we have defined a custom responder. The constructor takes one parameter, prepend. This is what is prepended to the return of the method when we trace it. To show that each one is unique we pass in two different strings. When using service calls that take parameters you pass the custom responder as the first parameter and then the rest that the service requires, don’t worry your service’s method won’t receive the responder. This is too basic of an example show how this helps you distinguish calls, but don’t worry we will do some next. You can find the complete example in the customResponder.fla.

In the next example (just as useless in the real world) we will maintain an array of objects on both the server and the client. We will pass this structure to the back-end for it to store and then we will remove items from it. To make it a little more interesting we will add a property to the object that defines if it is removable or not. We will also shuffle the client’s array for the fun of it.

To begin put the StructureService.cfc in your wwwroot of ColdfusionMX. This is the service we will be working with. You can look through the cfc code if you like this exercise won’t go over it at all.

The first step in the ActionScript code is to setup the gateway and fetch the service.

#include "NetServices.as"

NetServices.setDefaultGatewayURL("http://localhost:8500/flashservices/gateway");
gatewayConnection = Netservices.createGatewayConnection();

myService = gatewayConnection.getService("StructureService");

Next we will define our RemoveResponder class. This class will handle the return from the removeItem() method of the StructureService service. The constructor of RemoveResponder will take two parameters, item and ref. Item is the item that is being removed and ref is the reference to the array that it is being removed from. The removeItem() method of our service returns false (as a string) if the item is not removable. So it is the job of the RemoveResponder to catch this.

function RemoveResponder(item,ref){
  this.item = item;
  this.ref = ref;
}

RemoveResponder.prototype.onResult=function(result){
   if(result == "false") return;

   for(var i=0; i<this.ref.length; i++){
      if(this.ref[i] == this.item){
         this.ref.splice(i,1);
         return;
      }
   }
}

As shown above the onResult() method checks for false, if it is the method returns. If it is not it loops through and locates the item that was passed in when it was instantiated and removes it.

DataProviders and DataConsumers

This is just a quick example that makes good use of custom responders. A lot of times most of your services will return data that can be used by data consumers. Most of the Flash UI components support DataProviders. To return a DataProvider from a CFC you just return an array of objects. The objects in the array should contain two properties data and label. Label is the string that will be used to display the return. I have made a very simple class that can make code a lot more elegant when working with these.

function DataResponder(dataConsumer){
   this.dataConsumer = dataConsumer;
}

DataResponder.prototype.onResult = function(dp){
   this.dataConsumer.setDataProvider(dp);
}

As you can see it is in fact, simple. All this does is catch the result and set the DataProvider of a supporting component. In the example files DataConsumer.fla and DataService.cfc you can see that DataService has methods getComboData() and getListBoxData(). Each return ten items for the components to display.

Journal Example

This example is not going to be walked through but rather explained and then you can play and learn from it. This is a fairly basic journal example, you can add items with a specified name, and add text to it. You can also delete any entry or remove all of them. There is several things that can happen that would usually make your UI get out of sync with the backend, but this example shows how to handle those cases. Doing things such as trying to delete the root node will make the backend fire an error. This is a good example of need distinguish remoting calls. The application may tell the backend to delete three nodes, but only two can be deleted. The UI needs to know what node each call referred to. There are four main actions that can be taken on the back-end. You can get the tree, add a node to it, remove a node from it, or save data to a node (This would be our journal text) With knowing that the application has a responder for each action. It also has one more, ChainResponder, which is a utility responder for chaining remoting calls. This is only used once in this application but it is actually a utility that I use quite often, most of the time you need to have one call return before you make another, this responder class enables that. Now back on to our four main responders.

• GetTreeResponder - An instance of this is passed in to the getTree() method of TreeService. When the onResult() handler is called it starts recursively filling the FTree component.
  
• AddNodeResponder - An instance of this is passed to the addNode() method of the TreeService. When the onResult() handler is called, if it is passed false (as a string) it will not add the node to the tree, otherwise it continues to add it.
  
• RemoveResponder - An instance of this is passed to the removeNode() method of the TreeService. If false is returned it does not remove the node.
  
• SaveResponder - An instance of this is passed to the saveNodeData() method of the TreeService. If false is returned the data is not added.
  
• ChainResponder - This is our utility responder as described above. This application uses this with the removeAll() method of the TreeService, because error or not we must rebuild the tree at the end of the call. So the getTree() method is chained onto the removeAll() method.

Note: Remember as mentioned earlier, the server-side methods never actually see these responders, the ActionScript remoting classes are smart enough to pull it off and save it for later.

That pretty much explains the logic of the application there. Using these custom responders makes it easy to catch errors on a call by call basis. You can test this application out by taking the TreeService.cfc and putting it in the wwwroot folder of your ColdFusionMX installation. You can run the ExampleTreeService.fla from anywhere. To help you sort through the bulk of the code, the layer names and what they contain are listed below.

• Remoting - This layer does the remoting includes and connects to our service
  
• Custom Responders - This is all the custom responder code as described above.
  
• UI Handlers - All the UI Handlers are here, such as button and tree selection.
  
• Actions - Only one line of code, the getTree() method is called on the TreeService.
  
• UI - All of the UI components.

This as far as I can take you now! This will be a good exercise for you too look at. If you find yourself getting lost you should go back and read this article again and make sure you haven't missed anything. If you aren't lost, build upon it. Try making the label's of the entries editable after they have been added. There is a lot of features that can be added to this now, if you are a backend guru make it multi-user enabled.

Examples

• customResponder.fla & HelloWorld.cfc – Flash Remoting call using a custom responder class.
• DataConsumer.fla & DataService.fla - An example showing how Custom responders can make code more elegant.
• defaultResponder.fla & HelloWorld.cfc – Flash Remoting call using a default responder
• StructureExample.fla & StructureServce.cfc – A more real world example of distinguishing remoting calls.
• TreeServiceExample.fla & TreeService.cfc - A journal example, shows how to guarantee the structure between the front-end and back-end without refreshing the complete structure at each change. The complete structure is maintained in server scope so you can close the movie and run it again and your data will appear as you left it.