Flash Remoting with ColdFusion

Although HTML is usually enough for most web-based applications, many users expect or demand the features and power of a more typical desktop or client-server application's heavy clients. Although JavaScript, JScript, and Dynamic Hypertext Markup Language (DHTML) can provide some of the client-side logic and features users demand, many things are just not possible with those technologies. Typically, developers turn to Macromedia Flash to provide rich and powerful web-based clients; but up until now, integrating Flash with ColdFusion or other server-side applications has been a difficult and time-consuming chore. This has all changed with the development of Flash MX and Flash remoting, which we briefly touched on in Chapter 6, "ColdFusion Components." As we'll see in this section, working with Flash directly from ColdFusion has become as simple as connecting to databases using CFQUERY!

Flash and ColdFusion Templates

There are different ways to work with Flash from ColdFusion MX, ColdFusion components (CFCs) and web services, server-side ActionScript (AS), and CFML. Although CFCs might be many ColdFusion developers technique of choice, it's also very simple to communicate with Flash directly from CFML.

In CFML, you can communicate with Flash movies through the Flash variable scope , which is a new variable scope in ColdFusion. There are three major Flash variables in the Flash variable scope. Flash.Params is an array that contains the parameters passed from the Flash movie. By calling the Flash variable scope, you can access parameters passed back from Flash movies by calling the Flash parameter directly in the Flash variable scope, like this:

 Flash.parametername 

Depending on how you pass the values from Flash, you can refer to array values using typical array syntax or structure 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 from Actionscript, you can you use structure syntax, such as params.name.

You can use most of the CFML array and structure functions on AS collections. However, the StructCopy CFML function does not work with AS collections.

Because Flash.Params is an array, it retains the order of the parameters as they were passed to the function. You use standard structure name syntax to reference the parameters, as shown in the following code:

 <cfquery name="getCustomer" datasource="ICF" dbtype="ODBC">  SELECT Customer.CustomerID, Customer.CustomerFirstName, Customer.CustomerLastName,  Customer.CustomerAddress, Customer.CustomerCity, Customer.CustomerStateID,  Customer.CustomerZip, Customer.CustomerPhone, Customer.CustomerEmail,  Customer.CustomerPassword, Customer.CustomerNotification  FROM Customer, State  WHERE Customer.CustomerStateID='#Flash.stateID#'  </cfquery> 

As you can see, the query returns results based on the value of the stateID passed from Flash. Now if you want to pass values as an array from Flash, you would access them like this:

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

The second variable in the Flash variable scope is the result variable, which is returned to the Flash application. For example, let's create a simple ColdFusion template that passes the ColdFusion Server version information to an AS.

Listing 16.10 getVersion.cfm

 <cfset tempStruct = StructNew()>  <cfset tempStruct.cfversion = #Server.ColdFusion.ProductVersion#>  <cfset tempStruct.Message = "This is your version of ColdFusion"> 

In this example, we pass a structure that contains the version information for ColdFusion as well as a simple message that is passed back to the requesting Flash application through the Flash.Result variable.

Now when you create and save this template, save it into a new folder under your webroot directory called Flashexamples. The reason for this is Flash and AS use the directory name that contains the ColdFusion templates as the Flash service name in AS. The actual templates contained in the directory translate to service functions in AS.

Listing 16.11 getVersion.swf

 include "NetServices.as"  NetServices.setDefaultGatewayUrl("http://localhost:8500/flashservices/gateway");  gatewayConnection = NetServices.createGatewayConnection();  CFMService = gatewayConnection.getService("Flashexamples", this);  CFMService.getVersion(); 

Try testing this in your Flash MX studio. With Flash.Return, you can return most types of ColdFusion data to AS, as if you were working with a ColdFusion-based application, but you need to be aware of some specific data type conversions. See Table 16.2 for information on the data type conversions.

Table 16.2. Data Type Conversion Between Flash and ColdFusion

ActionScript Data Type	ColdFusion MX Data Type
Number (primitive data type)	Number
Boolean (primitive data type)	From ColdFusion, return to ActionScript either a 1 to indicate true or a 0 to indicate false.
String	String
AS object	Structure
AS object (passed as the only argument 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

When you are working with ColdFusion and Flash, you sometimes want to limit the amount of information you return to a Flash application at one time. For example, if we do a query that returns all the products in our database, we might want to limit the amount of records returned to 10. To do this, we use the Flash variable flash.pagesize, which enables you to return the total record set in increments. This speeds the communication time to Flash and enables it to deal with more manageable chunks of data.

Let's do a simple example.

Listing 16.12 getProducts.cfm

 <cfparam name="pagesize" default="10">  <cfif IsDefined("Flash.Params")>    <cfset pagesize = Flash.Params[1]>  </cfif>  <cfquery name="getProducts" datasource="ICF">   SELECT Product.ProductID, Product.ProductName, Product.ProductPricePerUnit,  Product.VendorID, Vendor.VendorID, Vendor.VendorName  FROM Product, Vendor  WHERE Product.VendorID=Vendor.VendorID  </cfquery>  <!--- set the record count to return --->  <cfset Flash.Pagesize = pagesize>  <!--- return the query --->  <cfset Flash.Result = getProducts> 

Make sure to save this file into our Flashexamples directory. Now this template is pretty simple and the only thing we need to look at is flash.pagesize, which is new. The flash.pagesize variable returns the number of records it was assigned unless the total number of records was smaller than its assigned value. To test this with a simple ActionScript, go to Flash MX Studio and try this.

Listing 16.13 getProducts.swf

 include "NetServices.as"  NetServices.setDefaultGatewayUrl("http://localhost:8500/flashservices/gateway");  gatewayConnection = NetServices.createGatewayConnection();  CFMService = gatewayConnection.getService("Flashexamples", 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.

Summary

As you can see, all you really need to know to integrate client-side ActionScript and Flash applications with ColdFusion is two simple variables in the Flash variable scope: flash.params and flash.return. Macromedia has once again taken a complex chore like creating server-side-driven Flash applications and made it as simple as manipulating a variable scope!