Using the Flash Remoting service with ColdFusion pages

When building a ColdFusion page that interacts with Flash movies, the directory name that contains the ColdFusion pages translates to the Flash service name in ActionScript. The individual ColdFusion page names contained in that directory translate to service functions in ActionScript.

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

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

Variable

Description

For more information

Flash.Params

A structure containing the parameters passed from the Flash movie.

See "Accessing parameters passed from Flash" on page 686.

Flash.Result

The variable returned to the Flash movie that called the function.

See "Returning results to Flash" on page 687.

Flash.Pagesize

The number of records returned at a time to Flash.

See "Returning records in increments to Flash" on page 688.

Variable	Description	For more information
Flash.Params	A structure containing the parameters passed from the Flash movie.	See "Accessing parameters passed from Flash" on page 686.
Flash.Result	The variable returned to the Flash movie that called the function.	See "Returning results to Flash" on page 687.
Flash.Pagesize	The number of records returned at a time to Flash.	See "Returning records in increments to Flash" on page 688.

In addition, the following table compares the ColdFusion data types and their ActionScript equivalents:

ActionScript data type

ColdFusion MX data type

Number (primitive data type)

Number

boolean (primitive data type)

boolean

String

String

ActionScript (AS) object

Structure

AS Object (as the only argument passed to a service function)

Arguments to the service function. ColdFusion pages (.cfm): flash variable scope, ColdFusion components (.cfc): named arguments

null

null (ASC returns 0, which translates to not defined)

undefined

null (ASC returns 0, which translates to not defined)

Ordered array

Array

Named array

Struct

Date object

Date

XML object

XML document

RecordSet

Query object

ActionScript data type	ColdFusion MX data type
Number (primitive data type)	Number
boolean (primitive data type)	boolean
String	String
ActionScript (AS) object	Structure
AS Object (as the only argument passed to a service function)	Arguments to the service function. ColdFusion pages (.cfm): `flash` variable scope, ColdFusion components (.cfc): named arguments
null	null (ASC returns 0, which translates to not defined)
undefined	null (ASC returns 0, which translates to not defined)
Ordered array	Array
Named array	Struct
Date object	Date
XML object	XML document
RecordSet	Query object

Accessing parameters passed from Flash

To access variables passed from Flash movies, 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 describes the collections and examples:

Collection

ActionScript example

Notes

Strict array

var myArray = new Array(); myArray[1] = "one"; myArray[2] = "two"; myService.myMethod(myArray);

The Flash Remoting service converts the array argument to a ColdFusion MX array. All CFML array operations work as expected.

Named or associative array

var myStruct = new Array(); myStruct["one"] = "banana"; myStruct["two"] = "orange";

In ActionScript, named array keys are not case-sensitive.

Mixed array

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

Treat this collection like a structure in ColdFusion MX. However, keys that start with numbers are invalid CFML variable names. Depending on how you attempt to retrieve this data, ColdFusion MX might throw an exception. The following ColdFusion component example throws an exception:
<cfargument name="ca" type="struct"> <cfreturn ca.2>

The following ColdFusion component example does not throw an exception:
<cfargument name="ca" type="struct"> <cfreturn ca["2"]>

Using an ActionScript object initializer for named arguments

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

This notation provides a convenient way of passing named arguments to a ColdFusion MX-based Flash Remoting service. You can access these arguments in ColdFusion pages as members of the Flash scope, or as normal named arguments of a ColdFusion component function

Collection	ActionScript example	Notes
Strict array	var myArray = new Array(); myArray[1] = "one"; myArray[2] = "two"; myService.myMethod(myArray);	The Flash Remoting service converts the array argument to a ColdFusion MX array. All CFML array operations work as expected.
Named or associative array	var myStruct = new Array(); myStruct["one"] = "banana"; myStruct["two"] = "orange";	In ActionScript, named array keys are not case-sensitive.
Mixed array	var myMixedArray = new Array(); myMixedArray["one"] = 1; myMixedArray[2] = true;	Treat this collection like a structure in ColdFusion MX. However, keys that start with numbers are invalid CFML variable names. Depending on how you attempt to retrieve this data, ColdFusion MX might throw an exception. The following ColdFusion component example throws an exception: `<cfargument name="ca" type="struct">` `<cfreturn ca.2>` The following ColdFusion component example does not throw an exception: `<cfargument name="ca" type="struct">` `<cfreturn ca["2"]>`
Using an ActionScript object initializer for named arguments	myService.myMethod({ x:1, Y:2, z:3 });	This notation provides a convenient way of passing named arguments to a ColdFusion MX-based Flash Remoting service. You can access these arguments in ColdFusion pages as members of the Flash scope, or as normal named arguments of a ColdFusion component function

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

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

  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 array. If the parameters were passed as an ordered array from Flash, you use standard structure name syntax; for example:

<cfset flash.result = "Variable 1:#Flash.params[1]#, Variable 2: #Flash.params[2]#">

In this ActionScript example, notice that ActionScript starts the array index at zero. ColdFusion array indexes start at one.

Returning results to Flash

In ColdFusion pages, only the value of Flash.Result variable is returned to the Flash application. For more information about supported data types between ColdFusion 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 containing simple messages to the Flash application.

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

Create a folder in your web root, and name it helloExamples.
Create a ColdFusion page, and save it as helloWorld.cfm in the helloExamples directory.

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.
Save the file.

Remember, the directory name is used 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:8500/flashservices/gateway");
gatewayConnection = NetServices.createGatewayConnection();
CFMService = gatewayConnection.getService("helloExamples", this);
CFMService.helloWorld();

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 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 lets you minimize the time that Flash application waits for the application server data to load.

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

Create a ColdFusion page, and save it as getData.cfm in the helloExamples directory.
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="ExampleApps">
  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 default is set to 10. Next, a cfquery statement queries the database. After that, the pagesize variable is assigned into the Flash.Pagesize variable. Finally, the query results are assigned into the Flash.Result variable, which is returned to Flash.
Save your work.

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. For example:

include "NetServices.as"

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

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.