Using Flash Remoting MX
Using Flash Remoting MX with ColdFusion MX

Using Flash Remoting MX with ColdFusion components

ColdFusion components require little modification to work with Flash. The cffunction tag names the function and contains the application logic, and the cfreturn tag returns the result to Flash.

Determining the Flash service name

The service name in ActionScript corresponds to the name of the .cfc file that contains the ColdFusion component. For example, if you create a ColdFusion component in the file flashComp.cfc, and the file is located in the directory helloExamples under your web root directory, you would define the service in ActionScript as follows:

#include "NetServices.as"

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

Within ColdFusion components, you create functions that define the functionality of the component. After defining the ActionScript service, you call component functions directly from ActionScript. For example, the following component defines two functions:

<cfcomponent>

  <cffunction name="functA" access="remote" returnType="Struct">
    ...
  </cffunction>

  <cffunction name="functB" access="remote" returnType="Struct">
    ...
  </cffunction>
</cfcomponent>

Note:   For ColdFusion component methods to communicate with Flash applications, you must set the cffunction tag's access attribute to remote.

You call these functions in ActionScript using the following syntax:

CFCService.functA();

CFCService.functB();

Returning results to ActionScript

In a ColdFusion component, you use the cfreturn tag to return a single variable to ActionScript. The following example returns a structure variable:

<cfcomponent>

  <cffunction name="helloWorld" access="remote" returnType="Struct" >
    ...
    <cfreturn tempStruct>
  </cffunction>
</cfcomponent>

Returning record sets in increments from a component

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 component executes once and returns all the results to the Flash Remoting gateway. The Flash application then requests subsequent records from the gateway as required.

The following example sets the Flash.Pagesize variable to 10 as part of returning results to the Flash application:

<cfcomponent>

  <cffunction name="getQuery" access="remote" returnType="query" >
    <cfquery name="myQuery" datasource="ExampleApps">
      SELECT *
      FROM tblItems
    </cfquery>
    ...
    <cfset Flash.Pagesize = 10>
    <cfreturn myQuery>
  </cffunction>
</cfcomponent>

For more information, see "Returning record sets in increments".

Passing parameters to ColdFusion components

You can pass multiple parameters from ActionScript to a ColdFusion component. In a component, you either include the cfargument tag within a function definition that corresponds to each parameter, or access the parameters directly from the Arguments scope.

The order in which you specify the cfargument tags in the function corresponds to the order in which the parameters are passed from ActionScript. For example, the following ActionScript call passes three parameters:

CFCService.functA(a, b, c);

The corresponding ColdFusion component defines three arguments, including the data type of the parameter:

<cfcomponent>

  <cffunction ...>
    <cfargument name="arg_for_a" type="type_of_a">
    <cfargument name="arg_for_b" type="type_of_b">
    <cfargument name="arg_for_c" type="type_of_c">
    ...
  </cffunction ...>
</cfcomponent>

For information on how ActionScript data types are converted to ColdFusion data types, see Chapter 3, "Using Flash Remoting Data in ActionScript".

The following table describes using the cfargument tag to access parameters:

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. <cffunction ...> <cfargument name="arg1" type="array"> <cfset p1=arg1[1]> <cfset p2=arg1[2]> ... </cffunction ...>
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. <cffunction ...> <cfargument name="arg1" type="struct"> <cfset p1=arg1.zero> <cfset p2=arg1.one> ... </cffunction ...>
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 as normal named arguments of a component function. <cffunction ...> <cfargument name="x" type="numeric"> <cfargument name="y" type="numeric"> <cfargument name="z" type="numeric"> <cfset p1=x> <cfset p2=y> <cfset p3=z> ... </cffunction ...>

The following example replicates the helloWorld function that was previously implemented as a ColdFusion page. For more information, see "Using Flash Remoting MX with ColdFusion pages" on page 68.

To create a ColdFusion component that interacts with a Flash application:

1. Create a ColdFusion component, and save it as flashComponent.cfc in the helloExamples directory.
2. Edit flashComponent.cfc so that it appears as follows:

   <cfcomponent>
     <cffunction name="helloWorld" access="remote" returnType="Struct">
         <cfset tempStruct = StructNew()>
         <cfset tempStruct.timeVar = DateFormat(Now ())>
         <cfset tempStruct.helloMessage = "Hello World">
         <cfreturn tempStruct>
     </cffunction>
   </cfcomponent>
   

   This example creates the helloWorld function. The cfreturn tag returns the result to the Flash application.

3. Save the file.

The following ActionScript example calls this function:

#include "NetServices.as"

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

For ColdFusion components, the component filename, including the directory structure from the web root, serves as the service name. Remember to use a period to delimit the path directories, rather than a backslash.

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 component, you can access objects using the object name, as in the following example:

<cfcomponent>

  <cffunction ...>
    <cfargument name="x" type="numeric">
    <cfargument name="y" type="numeric">
    ...
  </cffunction ...>
</cfcomponent>

You can also pass arrays, structures, and named objects using this syntax. The following ActionScript defines an object:

params = new Object();

params.first = "Hello";
params.second = true; 
service.concat(params); 

In a component, you access the object elements using named parameters, as follows:

<cfcomponent>

  <cffunction name="concat" access="remote" returntype="any">
    <cfargument name="first" type="any" required="true">
    <cfargument name="second" type="any" required="true">
    ...
    <cfreturn first & second>
  </cffunction>
</cfcomponent> 

This component specifies that two parameters are required. An ActionScript object will satisfy this requirement, as it will be split into named arguments. However, an ActionScript array will not.

Passing objects from ActionScript lets you use the Arguments scope within a component function. The Arguments scope works the same away as the Flash scope in ColdFusion pages. In a component, you can access parameters using the syntax Arguments.paramName. Therefore, you can access the params object from the previous example, as follows:

<cfcomponent>

  <cffunction name="concat" access="remote" returntype="any">
    <cfset p1=Arguments.first>
    <cfset p2=Arguments.second>
    ...
  </cffunction>
</cfcomponent> 

Using component metadata with the Flash Remoting service

Flash MX designers can use the Service Browser in the Flash MX authoring environment to discover business logic functionality built in ColdFusion. You use the description attribute of the cffunction and cfargument tags to describe the ColdFusion functionality to the Service Browser.

To create a ColdFusion component that describes itself to the Service Browser:

1. Edit flashComponent.cfc in the helloExamples directory to insert the following code:

   <cfcomponent>
     <cffunction name="getTime" access="remote" returnType="Date" 
       description="Returns date">
       <cfset tempStruct = StructNew()>
       <cfset tempStruct.timeVar = DateFormat(Now ())>
       <cfreturn tempStruct>
     </cffunction>
     <cffunction name="sayHello" access="remote" returnType="Struct" 
       description="Returns hello message">
       <cfset tempStruct = StructNew()>
       <cfset tempStruct.helloMessage = "Hello World">
       <cfreturn tempStruct>
     </cffunction>
   </cfcomponent>
   

   In this example, the description attribute of the cffunction tag supplies a short text description of the component method.

2. Save the file.
3. Open the Flash MX authoring environment, and open the Service Browser using the Window > Service Browser menu command.
4. If not already present, add the Flash Remoting gateway using your Flash Remoting service URL, such as http://localhost/flashservices/gateway.
5. Add the flashComponent service using the service address helloExamples.flashComponent.
6. Click the getTime or sayHello folder, the description appears in the Service Browser.

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/usingFRCF3.htm

Add Comment