Art Catalog: Building Your First ColdFusion Powered Flex 2 Application

This tutorial assumes that you have already installed the following:

• ColdFusion MX 7.0.1 (with examples and getting started material installed).
• The ColdFusion Flex 2 Adapter.
• Flex Builder 2.

The ColdFusion Flex 2 Adapter comes with installation instructions that must be followed very carefully. (Most initial problems are the result of the Adapter not be installed or configured correctly). The Application The application that you will be building is a simple data drill-down application which uses the sample data that is installed with ColdFusion MX 7.0.1. On startup, the application displays a drop down combo box containing a list of artists. Selecting any artist displays that artist's art, and clicking on art items displays an image. Setup Create a folder for your new application under your web root. The default I am using in this tutorial has a folder named flex under the web root, and a folder for this application named ArtCatalog in the flex folder. (On a default installation on a Windows machine this will therefore be c:\cfusionmx7\wwwroot\flex\artcatalog). The Backend The backend for this application is a simple ColdFusion Component named art.cfc which contains two methods. GetArtists() returns the artist list, and GetArt() accepts an artistid and returns that artist's art. The CFC itself is very simple: Notice that both methods query for data, and then query that query. There are two reasons for this. One, there is a bug in the current adapter whereby database query column names may not be converted to lowercase properly, querying the query solves this problem. Two, some Flex controls (like <mx:ComboBox>) have specific column name requirements, and the second query in GetArtists() renames the columns to the naming convention needed by that control. It is generally a good idea to thoroughly test CFCs using simple ColdFusion calls before using them in your Flex apps. The following file named arttest.cfm can be used to test that art.cfc is functioning properly: Defining The Service Flex 2 applications access ColdFusion Components via Flash Remoting using a service name. This name must be defined in an XML file, mapping a destination name to a source (the path to the CFC). When you installed the ColdFusion Adapter you copied a file named coldfusionsamples.xml into the WEB-INF\flex folder. Open that file, and add the following destination definition. The source here specifies flex\artcatalog\art as the path to the CFC (the .cfc extension should not be included), if you are using a different path make the necessary changes to the source. Once you have made the change and saved the xml file, you will need to restart ColdFusion. Creating The Project Here are the steps needed to create the new Flex Builder project:

1. Open Flex Builder 2.
2. Select File, New, Flex Project.
3. Specify ArtCatalog as the project name.
4. Specify the project location (you can use the same folder as where you created art.cfc).
5. The default Main Application File and Output Folder are ok, so click Finish to create the project.
6. Right click on the new project in the Navigator panel, and select Properties to open the project Properties dialog.
7. Select Flex Compiler.
8. In the Additional compiler arguments field enter: -services=C:\CFusionMX7\wwwroot\WEB-INF\flex\flex-services.xml (or modify the path to match your installation).
9. Click OK.

Building The Application Now you can start building the application. The first thing you need to do is tell Flex how to find your CFC. You do this using the <mx:RemoteObject> tag, as follows: Now, whenever you refer to artSvc Flex will be able to connect to art.cfc using the previously created mapping. Next you'll define the artist drop down combo box. Here is the code (make sure to place it between the <mx:Application> tags, after the <mx:RemoteObject> tag): Save the code and run the application (click on the run button, the one with the white arrow in a green circle). The application should run, but the combo-box will not be populated . This is actually the correct behavior, you never called the CFC method, so there were no results to populate it with. You want the GetArtists() method to be invoked automatically on application startup. To do that, create a ActionScript function named InitApp() as seen here: Next, modify the <mx:Application> tag. Go to the end of the tag and press space, you should see a popup of all available properties and methods. Select the property named creationComplete and specify InitApp() as the value. The opening tag should now look like: Save the code and run it again. This time the combo box should be automatically populated because the dataProvider points to artSvc.GetArtists.result (the result returned by the call to GetArtists in the artSvc service). Next you'll create the data grid to display artist's art. Here is the code, place it after the tag: This code creates a grid containing four columns. (The grid columns could have been omitted, but then all columns would have been displayed, and you'd also have lost the ability to fine-tune the appearance of specific columns as you will see shortly). The grid's dataProvider points to the result of artSvc.GetArt(). Which means that method must be invoked. Modify the <mx:ComboBox> and add the following property and value: This way, any time the combo box changed, GetArt() will be called. GetArt() requires that an argument be passed to it, the id of the artist who's art you wish to obtain. This argument is passed to GetArt() as artistsCB.selectedItem.data (the data value for the currently selected item in artistsCB). Now save and run the application. You should be able to select any artist to populate the data grid with his or her art. Now add the following code so as to display an image of the art when an art item is selected in the grid. Place it after the </mx:DataGrid> tag and before the closing <mx:HBox> tag: This code creates a panel, setting the title to the artname currently slected in the data grid, and populate the source on an <mx:Image> tag with the image URL as returned by GetArt(). Using Cell Renderers The default display in the data grid is fine for simple text data, but there are two columns that don't look right here. The Sold column is displaying true or false, which is not very intuitive. And the Price column is not formatting the values as currency values. Both of these problems can easily be addressed using cell renderers. Basically, a cell renderer is code that Flex should use to render cells instead of any default rendering. The Sold column could use a checkbox to display a check if sold and not if not. To do this, simply add the following property to the appropriate <mx:DataGridColumn> tag: If you run the application now you'll see that a checkbox is displayed, and will automatically be checked if true and not if false. To format the Price column you will use a custom cell renderer, a new component. To create a new component do the following:

1. Right click on the ArtCatalog project in the Navigator panel.
2. Select New, MXML Component.
3. Specify ArtPrice as the File name, and select VBox as the Base component.
4. Click Finish.

Flex Builder will create a new component (based on <mx:VBox>) for you to use. When a component is called as a cell renderer, an object named dataObject is passed to it containing the row to be rendered. Add the following code in between the <mx:VBox> tags: <mx:CurrencyFormatter> creates a formatter that knows how to format values as currency values. The <mx:Label> tag simply uses that formatter to display dataObject.price (the price column of the current row). The last thing to do is to tell Flex to use this new cell renderer. Go back to ArtCatalog.mxml and modify the price <mx:DataGridColumn> so that it includes the following: That's it. Save the files, and run the application. You can now select an artist, display art (formatted using cell renderers), and click on any art item to see it's image (not all of the items have associated images). Application Source Code This downloadable zip file contains the ColdFusion and Flex source code. Summary This application demonstrates basic ColdFusion Flex 2 integration, passing data to and from ColdFusion, as well as basic bindings and cell renderers. Watch for more complex and powerful examples coming soon.