Using Flash Remoting MX
Using Flash Remoting MX with ColdFusion MX

Using Flash Remoting MX with ColdFusion pages

When developing ColdFusion pages for use with Flash Remoting MX, you need to know how to do the following:

• Determine the Flash service name for the ColdFusion page
• Pass parameters back and forth between the Flash application and the ColdFusion page
• Return information to a Flash application from a ColdFusion page

The following sections describe how to perform these actions.

Determining the Flash service name

When building a ColdFusion page called from Flash applications, the directory name on the server containing the ColdFusion page translates to the service name called in ActionScript from Flash. The ColdFusion page names contained in that directory translate to service functions in ActionScript.

For example, you create a ColdFusion page named helloWorld.cfm in the directory helloExamples under your web root (web_root/helloExamples). You then use the following ActionScript in your Flash application to call helloWorld.cfm:

#include "NetServices.as"

NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");
gatewayConnection = NetServices.createGatewayConnection();
CFMService = gatewayConnection.getService("helloExamples", this);
CFMService.helloWorld();

To specify subdirectories of the web root directory or a virtual directory, use package dot notation. If helloWorld.cfm was in the directory web_root/helloExamples/ColdFusion, you use the following ActionScript to create the service:

CFMService = gatewayConnection.getService("helloExamples.ColdFusion", this);

Remember to use periods to delimit directory names for getService().

Using the Flash scope to pass parameters to ColdFusion pages

ColdFusion MX defines a scope called Flash that you use to access parameters passed from Flash applications and return values to Flash applications.

The Flash scope has several predefined variables that you can use to pass information, as described in the following table:

Variable	Description	For more information
Flash.Params	Array containing the parameters passed from the Flash application to the ColdFusion page. If you do not pass any parameters, Flash.Params still exists, but it is empty.	See "Using Flash.Params to access parameters in a ColdFusion page" on page 69.
Flash.Result*	Result returned to the Flash application from the ColdFusion page.	See "Returning results to ActionScript" on page 72.
Flash.Pagesize	Number of records in each increment of a record set returned to Flash from a ColdFusion page.	See "Returning record sets to Flash" on page 73.
* 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.

When you call a ColdFusion page from a Flash application, the Flash Remoting gateway converts ActionScript data types to ColdFusion data types. The data type of any results returned from ColdFusion to the Flash application are converted to ActionScript data types. For more information on this conversion, see Chapter 3, "Using Flash Remoting Data in ActionScript".

Using Flash.Params to access parameters in a ColdFusion page

The Flash.Params array contains one element for each parameter passed from ActionScript, in the order that the parameters were passed to the ColdFusion page. You use standard ColdFusion array syntax to reference the parameters.

For example, the following ActionScript call passes three parameters:

myService.myMethod(param1, param2, param3);

In your ColdFusion page, you access these parameters using Flash.Params, as follows:

<cfset p1=Flash.Params[1]>

<cfset p2=Flash.Params[2]>
<cfset p3=Flash.Params[3]>

The following ActionScript calls a ColdFusion page to execute a query. The ActionScript passes a single parameter to the ColdFusion page:

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

gatewayConnection = NetServices.createGatewayConnection();
myService = gatewayConnection.getService("doc_code", this);

myService.query1param("RipperStik");

In your ColdFusion page, you access the parameter using Flash.Params, as shown in the following example:

<cfquery name="flashQuery" datasource="exampleapps" >

   SELECT ItemName, ItemDescription, ItemCost
   FROM tblItems
  WHERE ItemName='#Flash.Params[1]#'
</cfquery>

<cfset Flash.Result=flashQuery>

Because ColdFusion converts an ActionScript data type to the corresponding ColdFusion data type, you can perform CFML type-specific operations on the parameter. Therefore, if a parameter passed from a Flash application is an ordered array, you can perform all CFML array operations on the parameter.

For example, if you pass an array using the following ActionScript:

var array1 = new Array(); 

array1[0] = "zero"; 
array1[1] = "one"; 
myService.myMethod(array1, param2, param3);

You access the elements in the array in your ColdFusion page using ColdFusion array notation, as follows:

<cfset arrayElement1=Flash.Params[1][1]>

<cfset arrayElement2=Flash.Params[1][2]>

Note:   While ActionScript starts the array index at zero, ColdFusion array indexes start at one.

ActionScript also supports named, or associative, arrays. These arrays have the following form:

var struct1 = new Array(); 

struct1["zero"] = "banana"; 
struct1["one"] = "orange"; 
myService.myMethod(struct1, param2, param3);

ColdFusion converts associative arrays into ColdFusion structures. To access the associative array elements from Flash.Params, you use structure notation, as follows:

<cfset structElement1=Flash.Params[1].zero>

<cfset structElement2=Flash.Params[1].one>

Note:   You can use most of the CFML array and structure functions on ActionScript collections. However, one CFML function, StructCopy, does not work with ActionScript collections.

The following table describes ActionScript collections and how to access them in ColdFusion pages:

Collection	ActionScript example	Notes
Strict array	var myArray = new Array(); myArray[0] = "zero"; myArray[1] = "one"; myService.myMethod(myArray);	The Flash Remoting service converts the array argument to a ColdFusion MX array. All CFML array operations work as expected. <cfset p1=Flash.Params[1][1]> <cfset p2=Flash.Params[1][2]>
Named or associative array	var myStruct = new Array(); myStruct["zero"] = "banana"; myStruct["one"] = "orange"; myService.myMethod(myStruct);	In ActionScript, named array keys are not case-sensitive. <cfset p1=Flash.Params[1].zero> <cfset p2=Flash.Params[1].one>
Named arguments using object initializer	myService.myMethod({x:1, y:2, z:3});	Provides a convenient way of passing named arguments to ColdFusion pages. Access these arguments in ColdFusion pages as members of the Flash scope. <cfset p1=Flash.x> <cfset p2=Flash.y> <cfset p3=Flash.z>

Accessing ActionScript objects

ActionScript supports the object initializer syntax when calling a function. For example, the following function call passes two parameters as objects:

myService.myMethod({x:1, y:2});

In this example, the function passes x with a value of 1 and y with a value of 2.

In your ColdFusion page, you can access objects using the object name, as in the following example:

<cfset param1=Flash.x>

<cfset param2=Flash.y>

You can also pass arrays and structures using this syntax, as follows:

var array1 = new Array(); 

array1[0] = "zero"; 
array1[1] = "one"; 

var struct1 = new Array(); 
struct1["zero"] = "banana"; 
struct1["one"] = "orange"; 

myService.myMethod({x:array1, y:struct1});

You access x and y in your ColdFusion page using ColdFusion array and structure notation, as follows:

<cfset arrayElement1=Flash.x[1]>

<cfset arrayElement2=Flash.x[2]>
<cfset structElement1=Flash.y.zero>
<cfset structElement2=Flash.y.one>

You can pass ActionScript objects to ColdFusion pages. The following ActionScript defines an object:

var myObj = new Object(); 

myObj.x = "one"; 
myService.myMethod(myObj);

In ColdFusion, you access the object elements using named parameters in the Flash scope, as follows:

<cfset p1=Flash.myObj>

Returning results to ActionScript

In ColdFusion pages, only the value of the Flash.Result variable is returned to the Flash application. While you are limited to returning a single variable to the Flash application, that variable can contain a single value, an array, a structure, or a record set returned from a ColdFusion query.

For more information about converting data types between ColdFusion and Flash, see Chapter 3, "Using Flash Remoting Data in ActionScript".

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 returns a structure:

1. Create a folder in a directory accessible to ColdFusion and your web server, and name it helloExamples. This directory can go under your web root directory.
2. Create a ColdFusion page, and save it as helloWorld.cfm in the helloExamples directory.
3. Edit the helloWorld.cfm page to insert the following code:

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

   In the example, you add two string variables to a structure, one with a formatted date and one with a simple message. The structure is returned to the Flash application using the Flash.Result variable.

4. Save the file.

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

#include "NetServices.as"

NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");
gatewayConnection = NetServices.createGatewayConnection();
CFMService = gatewayConnection.getService("helloExamples", this);
CFMService.helloWorld();

Within the result handler of helloWorld, you access the structure returned by ColdFusion.

Returning record sets to Flash

One common reason for a Flash application to call a ColdFusion page is for the ColdFusion page to access a database and return a record set to the Flash application. For example, the following ColdFusion code executes a query and returns the results of the entire query to the Flash application:

<cfquery name="myQuery" datasource="ExampleApps">

  SELECT *
  FROM tblItems
</cfquery>

<cfset Flash.Result = myQuery>

You can pass parameters from the Flash application to the ColdFusion page to conditionalize the query. The previous section contained an example that passed an argument to the WHERE clause of the query, as the following code shows:

<cfquery name="myQuery" datasource="ExampleApps">

   SELECT ItemName, ItemDescription, ItemCost
   FROM tblItems
  WHERE ItemName='#Flash.Params[1]#'
</cfquery>

<cfset Flash.Result = myQuery>

Depending on the SQL code of the query and the amount of data stored in the database, the query can return a single record, a few records, or a very large number of records. To pass the entire record set to the Flash application, you only have to write the record set to the Flash.Result variable.

In ActionScript, you access the record set columns to display the query. For example, you use the following ActionScript to call a ColdFusion page named cfQuery.cfm that contains the previous query:

myService.cfQuery("RipperStik");

In the result handler for the cfQuery() function, you access the record set as follows:

function cfQuery_Result ( result )

{
  DataGlue.bindFormatStrings(employeeData, result, 
"#ItemName#, 
#ItemDescription#, 
#ItemCost#");
}

In this example, employeeData is a Flash list box. This result handler displays the columns ItemName, ItemDescription, and ItemCost from each record in the result set, separated by commas, in the list box.

Returning record sets in increments

ColdFusion 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 the Flash application waits for the application server data to load.

The entire record set is called a Pageable Record Set and each increment is called a page. Therefore, the Flash.Pagesize variable sets the number of records in each page.

The ColdFusion page executes once and returns all the results to the Flash Remoting gateway. The Flash application then requests subsequent records from the gateway as required.

To create a ColdFusion page that returns an 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:

   <cfset Flash.Pagesize = Flash.Params[1]>
   <cfquery name="myQuery" datasource="ExampleApps">
     SELECT ItemName, ItemDescription, ItemCost
     FROM tblItems
   </cfquery>
   <cfset Flash.Result = myQuery>
   

   In this example, you pass a parameter from the Flash application that defines the increment size.

3. Save the file.

When you assign a value to the Flash.Pagesize variable, you specify that if the record set has more than that number of records, the record set becomes pageable and returns the number of records specified in the Flash.Pagesize variable. For example:

#include "NetServices.as"

NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");
gatewayConnection = NetServices.createGatewayConnection();
CFMService = gatewayConnection.getService("helloExamples", this);
CFMService.getData(10);

Flash UI components are designed to recognize results returned in increments. After the initial delivery of records, the RecordSet ActionScript class becomes responsible for fetching records. You can configure the client-side RecordSet object to fetch records in various ways using the setDeliveryMode ActionScript function.

In many cases, you do not have to modify the Flash UI components to handle data returned in increments. For example, if the record set is returned to a Flash list box, the list box requests more rows as the user scrolls through the list box.

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flashremoting/mx/Using_Flash_Remoting_MX/usingFRCF2.htm

Add Comment