Ben Forta

forta.com

Important note: Effective with the release of Adobe LiveCycle ES, the Adobe Flex Data Services 2 server product has been rebranded as a Solution Component of LiveCycle ES. This article was written based on Flex Data Services but will likely work as is with LiveCycle Data Services ES. Any articles referring to or using ColdFusion and Flex Data Services are not compatible with LiveCycle Data Services ES. To learn about the new capabilities of LiveCycle Data Services ES, see the tutorials in the LiveCycle Developer Center and read about Adobe LiveCycle Data Services ES.

Adobe ColdFusion MX 7.0.2 enables you to create applications with the rich Internet capabilities of Adobe Flex and the advanced data retrieval features of ColdFusion. You can use ColdFusion to create, read, update, and delete records in a database while using the rich presentation features of Flex. This article is part of a series of articles that demonstrate how you can use ColdFusion with Flex.

This article uses the Flex Phone Selector sample application to demonstrate some basic Flex funcitonality, including:

• The use of Flex states to control display
• The use of renderers and custom components
• The use of custom formatters

The Phone Selector application is a very simple example of a Flex application powered by ColdFusion. This sample application is deliberately small and highly focused to demonstrate ColdFusion Flex integration options, including:

• Accessing ColdFusion components through Flash Remoting
• The automatic conversion between ColdFusion components and equivalent ActionScript objects

This application is not intended to demonstrate development best practices, and was designed purely to demonstrate integration capabilities, functionality, and techniques.

Note: This application does not require Flex Data Services 2.0, nor does it require any data sources or setup within ColdFusion.

Requirements

To make the most of this article, you need to install the following software and files:

Important note: Effective with the release of Adobe LiveCycle ES, the Adobe Flex Data Services 2 server product has been rebranded as a Solution Component of LiveCycle ES. This article was written based on Flex Data Services but will likely work as is with LiveCycle Data Services ES. Any articles referring to or using ColdFusion and Flex Data Services are not compatible with LiveCycle Data Services ES. To learn about the new capabilities of LiveCycle Data Services ES, see the tutorials in the LiveCycle Developer Center and read about Adobe LiveCycle Data Services ES.

Flex Builder 2 (SDK Included)

• Try
• Buy

Flash Player 9

• Download

ColdFusion MX 7.0.2  (Includes connectivity for ColdFusion with Flex 2)

• Try
• Buy

Sample files:

• phones.zip (ZIP, 255K)

Prerequisite knowledge

Familiarity with ColdFusion data management and general Flex concepts.

Additional documentation

• ColdFusion MX 7.0.2 documentation and release notes
• Installation instructions for ColdFusion MX 7.0.2

Installing and configuring the application

The phone selector application has two parts: the ColdFusion code (ColdFusion components and a test ColdFusion page) and the Flex code (MXML and AS files). Make sure the ColdFusion code works properly before testing any integration.

To install the application, follow these steps:

1. Download the Phone Selector sample files that accompany this article.

2. Create a folder named Phones in the CFIDE/samples folder (under the web root). If a folder named samples does not exist under your CFIDE folder, create it.

   Note: You must place the application (both the ColdFusion and Flex bits) under the Web root. Furthermore, for automatic conversion between CFCs and ActionScript objects to occur, you must explicitly specify the path to these components and the path must be consistent in both ColdFusion and ActionScript code.

3. Create two folders in the Phones folder, one named CF (for the ColdFusion code) and the other named Flex (for the Flex Project).
4. Create a new project in Flex Builder 2. Select ColdFusion Flash Remoting Service as the server technology. Use the default location of the Flex Data Services server. Specify Phone selector as the application name. Specify the samples/Phones/Flex folder as the project location. Specify Main.mxml as the main page.

5. To use Flash Remoting, specify the following Flex compiler flag in the project properties:

   --services=C:\CFusionMX7\wwwroot\WEB-INF\flex\ services-config.xml

   (You must change the path, if your ColdFusion is installed in a different location).

6. Right-click the project and select Close Project.
7. Extract the ColdFusion files (catalog.xml, Phone.cfc, Catalog.cfc, and test.cfm) to the samples/Phones/CF folder.
8. Extract the Flex files (Main.mxml, Thumbnail.mxml, ProductDetails.mxml, FeatureFormatter.as, and Phone.as) to the samples/Phones/Flex folder. When asked whether to overwrite Main.xml, click Yes to overwrite the auto-generated Main.mxml with the complete one.
9. Copy the assets folder (with all of its contents) to the Flex folder.
10. To ensure that the CFML code works (which you must do before attempting to connect to it using a Flex client), run test.cfm, which is in the samples/Phones/CF folder. To run test.cfm, browse to it using http://localhost:8500/CFIDE/samples/Phones/CF/test.cfm. (If you are not using the built-in server, change the URL accordingly.) Test.cfm simply instantiates the catalog, gets the phones array, and dumps the output. If test.cfm runs correctly, you are ready to try the Flex client.
11. Open the project in Flex Builder and run it to display the phone list that ColdFusion returns. You can also select Show Details and Hide Details as needed.

The ColdFusion back end

The ColdFusion back end consists of three files:

• catalog.xml: This file contains the raw phone data.
• Phone.cfc: Phone.cfc is a single phone object. It contains variables to store phone properties (name, price, description, and so on), Get and Set functions for use with those properties, and a function used to populate these properties. It also contains a series of CFML <cfproperty> tags, which define the object properties. Although <cfproperty> tags are not generally used within ColdFusion applications, they are very important when creating objects that are consumed by Flash Remoting (or web services, for that matter).
• Catalog.cfc: Catalog.cfc reads the XML file to obtain phone data, and then creates an array of Phone components populated with the data (in function loadData() which is called by the constructor). The getPhones() function returns that array.

The Flex client

The Flex Client consists of five files:

• Main.mxml: This file is the main application page.
• ThumbNail.mxml: This file is the thumbnail renderer, used by the TileList in Main.mxml.
• ProductDetails,mxml: ProductDetails,mxml is the detail view component, used in Main.mxml.
• FeatureFormatter.as: This file is an ActionScript custom formatter, used in ProductDetails.mxml.
• Phone.as: This is an ActionScript class; it's the ActionScript equivalent of the ColdFusion component, Phone.cfc.

Understanding the application

The Phone Selector application demonstrates some important concepts and techniques, which are outlined in the following sections.

The ColdFusion code

The ColdFusion code consists of the following components and function:

• Phone.cfc: Phone.cfc uses the <cfproperty> tag to list each property in this CFC. The properties, their names and types, and their exact order are extremely important. If these do not match the properties in the equivalent ActionScript file, mapping does not occur (and when the array phones arrives in Flex it is an array of generic objects instead of an array of Phone objects).
• Catalog.cfc: To create the array of objects, Catalog.cfc uses the <cfinvoke> tag to create and populate a Phone.cfc (which is returned and appended to the array). The <cfinvoke> tag uses a fully qualified path to Phone.cfc, even though it is in the same folder. (In fact, component="Phone" would work). This, too, is to facilitate CFC to ActionScript class mapping. The fully qualified path is embedded in the array that is sent to the Flex application; it must match the path specified in the equivalent ActionScript class.
• getPhones(): The getPhones() function is the only function invoked from Flex. As a result, it must specify access="remote". Only CFC methods with this access level can be invoked through Flash Remoting.

The Flex code

The Flex code includes the following files:

• Main.mxml:

  • A <mx:RemoteObject> tag specifies to Flex how to get to the ColdFusion Catalog.cfc file. The source is fully qualified, and the destination is ColdFusion. This generic destination makes it unnecessary to map specific endpoints in Flex XML configuration files.
  • The main display uses states to switch between two views (with or without details), and the application exists within a <mx:Panel> tag with a <mx:ControlBar> tag at the bottom.
  • The <mx:Application> tag contains creationComplete="svc.getPhones()", which specifies that the application automatically invokes the ColdFusion getPhones() function as soon as the application is loaded and ready to use.
  • A variable named phones is defined and made bindable. The phones variable is where the phone data returned from ColdFusion is stored.
  • When ColdFusion returns data, a message handler is automatically invoked, as specified in the <mx:RemoteObject> tag. It creates an array that contains the data and uses that array to populate the phones variable.

• Phone.as:

  • Phone.as defines a new class of type Phone. This is the class that maps to Phone.cfc on the server.
  • The actual mapping is performed with the following code: [RemoteClass(alias="CFIDE.samples.Phones.CF.Phone")]
  • This code matches the <cfinvoke> syntax in Catalog.cfc, which is how the object types are automatically matched to each other.
  • The properties are exactly the same as those in Phone.cfc; they match the names, types, and order, which is required for mapping to work.
  • The Phone class has an empty constructor and a toString() method. (It is a good idea for every class you create to have a toString() method). In this simple example there are no other methods; however, there could be, just as the equivalent Phone.cfc has extra functions.

• FeatureFormatter.as:

  • Phones have two highlight points, and may have up to three other features (camera, video, tri-band) to highlight. ColdFusion developers frequently use inline <cfif> tags to determine whether to display values, and how to display them. This is a little more complicated in a Flex application; it is a custom formatter.
  • The formatter code is rather simple. It extends a base Formatter class (and calls that base class's constructor). The format() method builds the string, starting with the two highlight points and conditionally appending additional text.

• ProductDetails.mxml:

  • This is the details display component (used when Show Details is clicked).
  • A local bindable property named phone of type Phone is defined. This is passed in Main.mxml.
  • The code uses two formatters, a built-in one for currency formatter, and the FeatureFormatter custom formatter, which is then used to display phone features.

Where to go from here

Flash Remoting is the most efficient way to pass data between ColdFusion and client-side Flex applications. An important part of the new Flash Remoting adapter is support for automatic CFC to ActionScript object mapping. This requires careful calling conventions, explicit property definitions, and a RemoteClass definition within the ActionScript class. Once these are in place, passing complex data back and forth becomes very easy, and object types are retained (making any CFC functions or ActionScript class methods usable).

For more information, visit the Flex and ColdFusion topic page in the Flex Developer Center.

Using ColdFusion with Flex – Part 4: Creating and running a session tracker

About the author