Using the Flash Remoting service with ColdFusion pages

When you build a ColdFusion page that interacts with a Flash application, the directory name that contains the ColdFusion pages translates to the service name that you call in ActionScript. The individual ColdFusion page names within that directory translate to service functions that you call in ActionScript.

Note: Flash Remoting cannot interact with virtual directories accessed through a ColdFusion mapping.

In your ColdFusion pages, you use the Flash variable scope to access parameters passed to and from a Flash application. To access parameters passed from a Flash application, you use the parameter name appended to the Flash scope or the Flash.Params array. To return values to the Flash application, use the Flash.Result variable. To set an increment value for records in a query object to be returned to the Flash application, use the Flash.Pagesize variable.

The following table shows the variables contained in the Flash scope:

The following table compares the ColdFusion MX data types and their ActionScript equivalents:

Also, remember the following considerations regarding data types:

• If a string data type on the server represents a valid number in ActionScript, Flash can automatically cast it to a number if needed.
• To return multiple, independent values to the Flash application, place them in a complex variable that converts to a Flash Object, Array, or Associative Array, that can hold all of the required data. Return the single variable and access its elements in the Flash application.

For a complete explanation of using Flash Remoting data in ActionScript, see Using Flash Remoting MX 2004 Help.

Accessing parameters passed from Flash

To access variables passed from Flash applications, you append the parameter name to the Flash scope or use the Flash.Params array. Depending on how the values were passed from Flash, you refer to array values using ordered array syntax or structure name syntax. Only ActionScript objects can pass named parameters.

For example, if you pass the parameters as an ordered array from Flash, array[1] references the first value. If you pass the parameters as named parameters, you use standard structure-name syntax like params.name.

You can use most of the CFML array and structure functions on ActionScript collections. However, the StructCopy CFML function does not work with ActionScript collections. The following table lists ActionScript collections and describes how to access them in ColdFusion MX:

var myArray:Array = new Array(); 
myArray[0] = "zero"; 
myArray[1] = "one"; 
myService.myMethod(myArray);

var myStruct:Array = new Array(); 
myStruct["zero"] = "banana"; 
myStruct["one"] = "orange"; 
myService.myMethod(myStruct);

var myMxdArray:Array = new Array();
myMxdArray["one"] = 1; 
myMxdArray[2] = true;

myService.myMethod
({ x:1, Y:2, z:3 });

The Flash.Params array retains the order of the parameters as they were passed to the method. You use standard structure name syntax to reference the parameters; for example:

<cfquery name="flashQuery" datasource="cfdocexamples">
   SELECT ItemName, ItemDescription, ItemCost
   FROM tblItems
   WHERE ItemName EQ '#Flash.paramName#'
</cfquery>

In this example, the query results are filtered by the value of Flash.paramName, which references the first parameter in the passed array. If the parameters were passed as an ordered array from the Flash application, you use standard structure name syntax; for example:

<cfset Flash.Result = "Variable 1:#Flash.Params[1]#, Variable 2: #Flash.Params[2]#">

Tip: ActionScript array indexes start at zero. ColdFusion array indexes start at one.

Returning results to Flash

In ColdFusion pages, only the value of the Flash.Result variable is returned to the Flash application. For more information about supported data types between ColdFusion MX and Flash, see the data type table in Using the Flash Remoting service with ColdFusion pages. The following procedure creates the service function helloWorld, which returns a structure that contains simple messages to the Flash application.

To create a ColdFusion page that passes a structure to a Flash application:

1. Create a folder in your web root, and name it helloExamples.
2. Create a ColdFusion page, and save it as helloWorld.cfm in the helloExamples directory.
3. Modify helloWorld.cfm so that the CFML code appears as follows:

   <cfset tempStruct = StructNew()>
   <cfset tempStruct.timeVar = DateFormat(Now ())>
   <cfset tempStruct.helloMessage = "Hello World">
   

   In the example, two string variables are added to a structure; one with a formatted date and one with a simple message. The structure is passed back to the Flash application using the Flash.Result variable.

   <cfset Flash.Result = tempStruct>
   

4. Save the file.

Remember, the directory name is the service address. The helloWorld.cfm file is a method of the helloExamples Flash Remoting service. The following ActionScript example calls the helloWorld ColdFusion page and displays the values that it returns:

import mx.remoting.*;  
import mx.services.Log;
import mx.rpc.*; 

// Connect to helloExamples service and create the howdyService service object
   var howdyService:Service = new Service(
         "http://localhost/flashservices/gateway",
         null,
         "helloExamples",
         null, 
         null );
// Call the service helloWorld() method
var pc:PendingCall = howdyService.helloWorld();
// Tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "helloWorld_Result", "helloWorld_Fault" );  
  
function helloWorld_Result(re:ResultEvent)
{
   // Display successful result
   messageDisplay.text = re.result.HELLOMESSAGE;
   timeDisplay.text = re.result.TIMEVAR;
}

function helloWorld_Fault(fe:FaultEvent)
{
   // Display fault returned from service
   messageDisplay.text = fe.fault;
}

Note: Due to ActionScript's automatic type conversion, do not return a Boolean literal to Flash from ColdFusion. Return 1 to indicate true, and return 0 to indicate false.

Returning records in increments to Flash

ColdFusion MX lets you return record set results to Flash in increments. For example, if a query returns 20 records, you can set the Flash.Pagesize variable to return five records at a time to Flash. Incremental record sets let you minimize the time that a Flash application waits for the application server data to load.

To create a ColdFusion page that returns a incremental record set to Flash:

1. Create a ColdFusion page, and save it as getData.cfm in the helloExamples directory.
2. Modify getData.cfm so that the code appears as follows:

   <cfparam name="pagesize" default="10">
   <cfif IsDefined("Flash.Params")>
   	<cfset pagesize = Flash.Params[1]>
   </cfif>
   <cfquery name="myQuery" datasource="cfdocexamples">
   	SELECT *
   	FROM tblParks
   </cfquery>
   <cfset Flash.Pagesize = pagesize>
   <cfset Flash.Result = myQuery>
   

   In this example, if a single parameter is passed from the Flash application, the pagesize variable is set to the value of the Flash.Params[1] variable; otherwise, the value of the variable is the default, 10. Next, a cfquery statement queries the database. After that, the pagesize variable is assigned to the Flash.Pagesize variable. Finally, the query results are assigned to the Flash.Result variable, which is returned to the Flash application.

3. Save the file.

When you assign a value to the Flash.Pagesize variable, you are specifying that if the record set has more than a certain number of records, the record set becomes pageable and returns the number of records specified in the Flash.Pagesize variable. For example, the following code calls the getData() function of the CFMService and uses the first parameter to request a page size of 5:

import mx.remoting.*;  
import mx.services.Log;
import mx.rpc.*; 
// Connect to helloExamples service and create the CFMService service object
   var CFMService:Service = new Service(
         "http://localhost/flashservices/gateway",
         null,
         "helloExamples",
         null, 
         null );
// Call the service getData() method
var pc:PendingCall = CFMService.getData(5);
// Tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "getData_Result", "getData_Fault" );  
  
function getData_Result(re:ResultEvent)
{
   // Display successful result
   DataGlue.bindFormatStrings(employeeData, re.result, "#PARKNAME#, #CITY#, #STATE#");
}
function getData_Fault(fe:FaultEvent)
{
   // Display fault returned from service
   trace("Error description from server: " + fe.fault.description);
}

In this example, employeeData is a Flash list box. The result handler, getData_Result, displays the columns PARKNAME, CITY, and STATE in the employeeData list box. After the initial delivery of records, the RecordSet ActionScript class assumes the task of fetching records. In this case, the list box requests more records as the user scrolls the list box.

You can configure the client-side RecordSet object to fetch records in various ways using the ResordSet.setDeliveryMode ActionScript function.

View comments in LiveDocs