Adobe ColdFusion 8

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:

Variable

Description

For more information

Flash.Params

Array that contains the parameters passed from the Flash application. If you do not pass any parameters, Flash.params still exists, but it is empty.

See Accessing parameters passed from Flash.

Flash.Result

The variable returned from the ColdFusion page to the Flash application that called the function.

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

See Returning results to Flash.

Flash.Pagesize

The number of records returned in each increment of a record set to a Flash application.

See Returning records in increments to Flash.

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

ActionScript data type

ColdFusion data type

Number (primitive data type)

Number

Boolean (primitive data type)

Boolean (0 or 1)

String (primitive data type)

String

ActionScript Object

Structure

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

Arguments of the service function. ColdFusion pages (CFM files): flash variable scope, ColdFusion components (CFC files): named arguments

Null

Null (Asc() returns 0, which translates to not defined)

Undefined

Null (Asc() returns 0, which translates to not defined)

Ordered array

Note: ActionScript array indexes start at zero (for example: my_ASarray[0]).

Array

Note: ColdFusion array indexes start at one (for example: my_CFarray[1]).

Named (or associative) array

Struct

Date object

Date

XML object

XML document

RecordSet

Query object (when returned to a Flash application only; you cannot pass a RecordSet from a Flash application to a ColdFusion application)

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:

Collection

ActionScript example

Notes

Strict array

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

The Flash Remoting service converts the Array argument to a ColdFusion 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:Array = new Array(); myStruct["zero"] = "banana"; myStruct["one"] = "orange"; myService.myMethod(myStruct);

Named array keys are not case-sensitive in ActionScript.

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

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

Mixed array

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

Treat this collection like a structure in ColdFusion. However, keys that start with numbers are invalid CFML variable names. Depending on how you attempt to retrieve this data, ColdFusion might throw an exception. For example, the following CFC method throws an exception:

<cfargument name="ca" type="struct">

<cfreturn ca.2>

The following CFC method 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 ColdFusion pages. You can access these arguments in ColdFusion pages as members of the Flash scope:

<cfset p1 = Flash.x>

<cfset p2 = Flash.y>

<cfset p3 = Flash.z>

Or, you can access them as normal named arguments of a CFC method.

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]#">

Note: 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 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.

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 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.

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 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 RecordSet.setDeliveryMode ActionScript function.