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.
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. |
|
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. |
|
Flash.Pagesize |
The number of records returned in each increment of a record set to a Flash application. |
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:
For a complete explanation of using Flash Remoting data in ActionScript, see Using Flash Remoting MX 2004 Help.
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]#">
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
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; }
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
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.