Using Flash Remoting

Using Flash Remoting involves the following steps:

1.	Plan the application, separating client and server processing as needed.
2.	Write the server-side code.
3.	Create the Flash application using Flash.
4.	Embed ActionScript code in the Flash application to invoke the server-side code via Flash Remoting.
5.	Pass requests to the server as needed and process any returned results.

Obviously, using Flash Remoting requires a basic understanding of Flash and ActionScript.

NOTE

Flash movie and animation featuresfor example, use of the timelineare not required to leverage Flash Remoting.

Within ColdFusion, you have three ways to respond to Flash Remoting requests:

• ColdFusion Components

• Straight .cfm calls

• Server-side ActionScript

Each of these is reviewed below.

Using ColdFusion Components

ColdFusion Components (CFCs) are used to encapsulate back-end processing. CFCs can be used by ColdFusion, by Flash Remoting, and as Web Services.

CFCs were reviewed in Chapter 31, "ColdFusion Components."

ColdFusion Components contain methods (or functions). By default, methods are available only to ColdFusion. To make CFC methods available to the outside world (including to client-side Flash), you must set the access level to remote, as seen here:

 <cfcomponent>   <cffunction name="GetEmployees"               access="remote"               output="no"               returntype="query">     <cfquery name="Employees"              datasource="exampleApps">     SELECT *     FROM tblEmployees     ORDER BY LastName, FirstName     </cfquery>   <cfreturn Employees> </cfcomponent> 

The above code defines a CFC containing a single method; GetEmployees returns a list of employees from a database. This code could be used in ColdFusion applications, and because access="remote", it can also be invoked by client-side ActionScript.

To invoke this code from within Flash, ActionScript code is used. Here is a code snippet:

 #include "NetServices.as" var gwURL="http://localhost:8500/flashservices/gateway"; NetServices.setDefaultGatewayURL(gwURL); gw=NetServices.createGatewayConnection(); employeeService=gw.getService("hr.employees", this); employeeService.getEmployees(); 

This script includes the Flash Remoting client-side code, then defines a connection to the ColdFusion server. /flashservices/gateway is a virtual path to the Flash Remoting engine in ColdFusion.

Once the gateway connection has been established, access to specific CFCs can be defined. In this example, employeeService is being bound to hr.employees, the employees.cfc (the above ColdFusion Component) in the hr directory.

The final line of code then executes the getEmployees() method in employeeService, the method defined above. getEmployees() expects no arguments; had this not been the case, arguments could have been provided as function parameters.

All of this happens without a client-side refresh; data is sent back and forth on demand and can be processed as needed.

NOTE

As getEmployees() returns a result, Flash will expect a function named getEmployees_Result() to receive the returned data. If the function is not present, a notification to that effect will be displayed in the output box (when in the Flash development environment).

Using CFML

ColdFusion Components are ideal for creating applications where the client and server are explicitly separated, as seen above. However, when needed, Flash Remoting can also be used to directly access any .cfm file in much the same way as described above.

Consider the following ActionScript code:

 #include "NetServices.as" var gwURL="http://localhost:8500/flashservices/gateway"; NetServices.setDefaultGatewayUrl(gwURL); gw = NetServices.createGatewayConnection(); hrService = gatewayConnection.getService("hr", this); hrService.List(); 

The ActionScript looks much like the ActionScript used to interact with a CFC. However, in this example the service being connected to is hr, the directory (as opposed to a specific CFC). The hrService.List() invocation is executing list.cfm in the hr directory.

Unlike ColdFusion Components, straight CFML files do not have a structured way to accept and return data. To this end, ColdFusion provides a special interface to Flash within .cfm files via the FLASH scope (which will be present only if a .cfm file is invoked via Flash Remoting). Table 36.1 lists the members of the FLASH scope.

Table 36.1. The FLASH Scope

ELEMENT	DESCRIPTION
pagesize	The number of records at a time to be returned to Flash. This allows for data to be displayed or used before it has all been transmitted. The default is 10.
params	Provides access to passed arguments (parameters). Data is in an array (either indexed or associative) and can be accessed using array or structure functions.
result	Data to be returned to Flash.

Arrays and structures were covered in Chapters 14 and 15, "Arrays" and "Structures," respectively.

Data returned by Flash Remoting is automatically converted to appropriate client-side data types. For example, ColdFusion queries are returned as ActionScript RecordSets, and structures are returned as named arrays.

NOTE

Only data stored in FLASH.result is sent back to Flash on the client.

TIP

The downside of using .cfm files instead of .cfc files for Flash Remoting is that the CFML code must be Flash-specific, and will not be portable. As a general rule, interaction via ColdFusion Components is preferred.

Using Server-Side ActionScript

CFCs or straight CFML are ColdFusion developers' primary interfaces to Flash Remoting. For Flash developers who may be familiar with ActionScript but not CFML, Flash Remoting also allows very basic access to the ColdFusion world via server-side ActionScriptActionScript source code that ColdFusion processes on the server.

The following is a code snippet that is functionally equivalent to the GetEmployees CFC method seen previously:

 function basicQuery() {  employees=CF.query(    {datasource:"exampleapps",     sql:"SELECT *          FROM tblEmployees          ORDER BY LastName, FirstName"    });  return employees; } 

Assuming that this code was saved as list.asr in the HR directory, the ActionScript invocation code used to invoke a CFML page could be used here.

NOTE

Server-side ActionScript does not fully expose CFML and ColdFusion. In fact, all it exposes are database queries (equivalent to <cfquery>, as seen here) and server-side HTTP requests (equivalent to <cfhttp>).

Using DataGlue

Once data has been received inside of Flash, it must be processed, usually by looping through results and associating them with UI elements. To simplify this process, Flash includes a function library called DataGlue (which, as its name suggests, is used to bind data with objects).

To use DataGlue, the DataGlue.as file must be included in the ActionScript code, like this:

 #include "DataGlue.as" 

DataGlue.as defines a collection of functions that may used as needed. The following example is the result-processing function that the CFC invocation described earlier in this chapter may useit receives data from the GetEmployees() method, which it uses to populate a combo box:

 function getEmployees_Result(result) { DataGlue.bindFormatStrings(employee_cb,  result,  "#lastname#, #firstname#",  "#employeeid#"); } 

NOTE

DataGlue is not always needed; some Flash UI components (for example, the DataGrid) can accept RecordSets directly.

Debugging

Flash features its own debugger as well as a NetConnection Debuggerkind of a sniffer window that reports on the requests and results that are sent back and forth between Flash on the client and Flash Remoting on the server. To use NetConnection Debugger, you must use the following #include statement in the ActionScript code:

 #include "NetDebug.as" 

NetConnection Debugger can also display any and all ColdFusion debugging information if debugging is enabled on the server.

Debugging was reviewed in Chapter 20, "Debugging."