Section 12.1. Understanding ColdFusion MXand Flash Remoting

12.1. Understanding ColdFusion MXand Flash Remoting

ColdFusion is a rapid application deployment service with a simple but powerful scripting language offering a remarkably easy learning curve. A free trial version of ColdFusion and information on installing and using it can be found at:

http://macromedia.com/software/coldfusion/

To perform the exercise in this chapter, which relies on ColdFusion, download and install the trial version from the preceding URL. The sample files are all available on the book's web site. Even if you don't install ColdFusion and test the example, it is informative to read through the code. For ColdFusion hosting services, refer to the resources cited in the Preface.

ColdFusion is often described as an application server, but it is technically a service of the application server. ColdFusion Markup Language (often referred to as CFML or ColdFusion) is a tag-based programming language, so you can use any text editor, such as the one included in Dreamweaver, HomeSite, or Flash Pro to write your CFML code. Many third-party editors, such as PrimalScript (http://www.sapien.com/ primalscript .aspx), are also available. ColdFusion Server interprets the CFML logic and effectively converts it to an HTML page that can be served to any web browser.

ColdFusion offers a powerful underlying platform to develop applications that perform database queries, HTTP requests , FTP operations, file and directory system operations, email services, and much more. ColdFusion encourages good programming practices, such as separating business logic from page content and storing reusable chunks of CFML in ColdFusion components , which make it easy to create n -tiered applications. That, in turn , provides a great foundation for using ColdFusion in conjunction with Flash Remoting. In addition, ColdFusion has Flash Remoting technology built in, so no additional elements need be installed in order to use ColdFusion, Flash Remoting, and FlashCom Server together.

12.1.1. Using CFML and ColdFusion Components

CFML is an XML/HTML-like language you can use to create the two basic types of ColdFusion elements: ColdFusion pages (stored in .cfm or .cfml files) and ColdFusion components (stored in .cfc files). ColdFusion pages are part of the presentation tier and therefore don't really fit into the Flash Remoting model. ColdFusion components (CFCs), however, can form the business logic of a ColdFusion application and are, therefore, an appropriate choice when using ColdFusion in conjunction with Flash Remoting.

Let's take a few minutes to discuss the basics of building a CFC using CFML. If you're not already familiar with CFML or CFCs, consider getting a good ColdFusion reference such as Programming ColdFusion MX, 2nd Edition (O'Reilly). If you have a good programming background, you may find that this simple introduction and the online CFML documentation included with ColdFusion provide ample resources.

Like all ColdFusion code, CFCs can be created in any text editor. A CFC must always have a <cfcomponent> tag as the root element and should be stored in a text file with the extension .cfc . Enclosed within that are one or more methods defined using <cffunction> tags. The following code defines a CFC with a single method named getProducts( ) , albeit one that doesn't do anything:

 <cfcomponent>   <cffunction name="getProducts">   </cffunction> </cfcomponent> 

Typically, a method includes one or more lines of CFML between the opening and closing <cffunction> tags. A method can return a value using a <cfreturn> tag. The following code defines a CFC with a getProducts( ) method in which ColdFusion queries a database and returns a recordset (additions shown in bold):

 <cfcomponent>   <cffunction name="getProducts">  <cfquery datasource="fcs_products" name="qProducts">   SELECT *   FROM products   </cfquery>   <cfreturn qProducts />  </cffunction> </cfcomponent> 

The query has been named qProducts using the name attribute in the <cfquery> tag. The results of the query are returned in the query object named qProducts . You can also define method parameters using <cfargument> tags. The following rewrite of the CFC adds a single parameter that allows the caller to specify the product category (additions shown in bold):

 <cfcomponent>   <cffunction name="getProducts">  <cfargument name="category" type="string" />  <cfquery datasource="fcs_products" name="qProducts">       SELECT *       FROM products  WHERE category = '#category#  '     </cfquery>     <cfreturn qProducts />   </cffunction> </cfcomponent> 

By default, any parameter you define is required. However, you can make a parameter optional by specifying "false" for the required attribute of the <cfargument> tag. You can also set a default value with an optional parameter. The following rewrite of the CFC makes the category parameter optional. If no value is specified, ColdFusion uses a default value of "software" (changes shown in bold):

 <cfcomponent>   <cffunction name="getProducts">     <cfargument name="category" type="string"  required="false" default="software  " />     <cfquery datasource="fcs_products" name="qProducts">       SELECT *       FROM products       WHERE category = '#category#'     </cfquery>     <cfreturn qProducts />   </cffunction> </cfcomponent> 

When using CFCs with a standard ColdFusion presentation tier (ColdFusion pages), the preceding examples work just fine. However, if you want to make a CFC method accessible to Flash Remoting, you need to set the correct access for the method. You can make the getProducts( ) method accessible to Flash Remoting by specifying a value of "remote" for the access attribute of the <cffunction> tag. The final version is as follows (changes shown in bold):

 <cfcomponent>   <cffunction name="getProducts"  access="remote  ">     <cfargument name="category" type="string" required="false" default="software" />     <cfquery datasource="fcs_products" name="qProducts">       SELECT *       FROM products       WHERE category = '#category#'     </cfquery>     <cfreturn qProducts />   </cffunction> </cfcomponent> 

ColdFusion components should be saved into a directory accessible to the web server just as you'd save a ColdFusion template ( .cfm ). CFCs are standard text documents, so you can create them using any text editor. A CFC can define multiple functions (with separate <cffunction> tags), and you can give the component any name, such as FCSUtilities.cfc . The .cfc filename becomes the name of the service, and the functions defined within it become methods of the service as described in subsequent sections.

12.1.2. Using Flash Remoting with ColdFusion

You need to know five basic pieces of information in order to use Flash Remoting with ColdFusion from FlashCom:

• What is the Flash Remoting gateway URL?

• What is the service address?

• What is the name of the service method?

• What parameters does the method require/accept, and how can you pass those parameters to the method?

• What kind of data does the method return, and how should you handle the return data?

In truth, these issues are identical regardless of whether you are using Flash Remoting with ColdFusion or some other server-side technology such as Java, .NET, or PHP. Consult the online documentation for your server, or see Flash Remoting: The Definitive Guide for details on the slight differences in, say, the URL of the Flash Remoting gateway.

12.1.2.1 Determining the Flash Remoting gateway URL

Every Flash Remoting request and response is routed through a gateway. In the case of ColdFusion MX, the gateway is a servlet running in the /flashservices/gateway context. For example, if you want to connect your FlashCom application to a ColdFusion Server on the same domain, use the following gateway URL:

http://localhost/flashservices/gateway

The following code illustrates how to create a NetConnection object that connects to a Flash Remoting gateway in which ColdFusion is running on the same domain as FlashCom:

 load("NetServices.asc"); application.onAppStart = function (  ) (   NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");   var nc = NetServices.createGatewayConnection( ); }; 

12.1.2.2 Determining the service address

Once you've created a connection to the Flash Remoting gateway, you next need to specify the address of the service. The service, in the case of ColdFusion, is a CFC. CFCs should be referenced using the fully qualified name. That means you include any package names delimited by dots, but you should not include the .cfc file extension. For example, if you have a CFC named FCSUtilities.cfc accessible within the root context of the web server on the ColdFusion machine, you can create a service object as follows:

 var frservice = nc.getService("FCSUtilities", this); 

The preceding code assumes that nc is a valid NetConnection object created using NetServices.createGatewayConnection( ) .

If FCSUtilities.cfc is within the /fcs/cfcs context, then the corresponding ActionScript code would be:

 var frservice = nc.getService("fcs.cfcs.FCSUtilities", this); 

12.1.2.3 Calling the service method

Calling the service method is simple. Just invoke the method on the service object using dot notation. The following code calls a CFC method named getProducts( ) from a service object named frservice :

 frservice.getProducts(  ); 

12.1.2.4 Passing parameters to a service method

You can pass parameters to a service method in one of two ways: positional or named. To use positional parameters, pass a comma-delimited list of values between the parentheses following the function name, such as:

 frservice.addProfile(   param1   ,   param2   ,   param3   ,   param4   ); 

Consider the following CFC method code:

 <cffunction name="addProfile" access="remote">   <cfargument name="name_first" type="string" />   <cfargument name="name_last" type="string" />   <cfargument name="city" type="string" />   <cfargument name="category" type="string" />   <cfquery datasource="fcs_profiles">     INSERT INTO profiles(name_first, name_last, city, category)     VALUES('#name_first#', '#name_last#', '#city#', '#category#')   </cfquery>   <cfreturn true /> </cffunction> 

The addProfile( ) method defined in the preceding code requires four parameters: name_first , name_last , city , and category . If you use standard, positional parameters when you call it from FlashCom, you need to specify the parameters in exactly the order in which the <cfargument> tags appear within the method definition. For example:

 frservice.addProfile("Kevin", "Singh", "New York", "student"); 

Optionally, you can use named parameters. When you use named parameters, you pass the method a single object in which the names of the properties match the names of the parameters defined in the CFC method. The following is an example using the addProfile( ) method:

 frservice.addProfile({name_first: "Kevin", name_last: "Singh",                       city: "New York", category: "student"}); 

If you use named parameters, then the order in which the properties appear within the object does not matter. The following code works just like the previous example, even though the order of the properties is different:

 frservice.addProfile({name_last: "Singh", name_first: "Kevin",                       category: "student", city: "New York"}); 

The named parameters option poses a potential quirk if you want to pass a single associative array ( Object instance) as the parameter to a CFC method. For example, you may have a CFC defined as follows:

 <cffunction name="addData" access="remote">   <cfargument name="data_structure" type="struct" />   <cfquery datasource="fcs_example">     INSERT INTO sample(a, b, c, d)     VALUES('#data_structure.a#', '#data_structure.b#',            '#data_structure.c#', '#data_structure.d#')   </cfquery> </cffunction> 

However, if you attempt to call that method from FlashCom in the following way, you'll get an error:

 frservice.addData({a: "a", b: "b", c: "c", d: "d"}); 

ColdFusion reports an error saying that the method expects a parameter named data_structure and not parameters named a , b , c , and d . Because just one parameter is being passed and because that parameter is an associative array, Flash Remoting and ColdFusion will treat it as a series of named parameters. To solve the problem, simply wrap the associative array in another object as follows:

 frservice.addData({data_structure: {a: "a", b: "b", c: "c", d: "d"}}); 

12.1.2.5 Handling return values

As you've already learned, Flash Remoting works asynchronously. Therefore, if a service method returns a value, you cannot use a simple assignment statement when calling the method via Flash Remoting. For example, the following will not work to assign to products_rs the value returned by getProducts( ) :

 var products_rs = frservice.getProducts(  ); 

Instead, you need to handle the results with a response object as discussed in Chapter 11. The response object can be any ActionScript object to which you add appropriately named methods to handle the response. You can tell FlashCom how to handle the response by passing the response object when you call getService( ) , as in the following:

 var frservice = nc.getService("fcs.cfcs.FCSUtilities", this); 

Here, the keyword this indicates that the current object will handle the response. If the preceding code appears within a method attached to the application object, it means the application object will handle any responses from any calls made to the service's methods.

The response object should have a method whose name takes the form: serviceMethodName _Result . For example, if the service method is named getProducts( ) , the response object should have a method named getProducts_Result( ) . The following is an example of such a method defined for the application object:

 application.getProducts_Result = function (products_rs) {   trace(products_rs.getLength(  ) + " products were returned."); }; 

For other ways to specify response objects, see Chapter 11.