Brian Szoszorek
Building your first data management application with ColdFusion and Flex
With Adobe ColdFusion 8 and Flex 3, building rich Internet applications has never been easier. Used together, these technologies enable developers to create expressive applications quicker than ever before.
In this article the focus will be on creating simple UI using Flex DataGrid to display result sets that are synchronized across all connected clients. The moment a user updates the DataGrid, all other users accessing that data will receive the updates instantly. This means you no longer have to worry about race conditions and data overwrite issues. While this may sound like a complex example for a beginner-level tutorial, I think you will be amazed by how easy ColdFusion 8, Flex Builder 3, and LiveCycle Data Services ES make this task.
There are different options available for integrating data services into your RIAs. In this article, I will focus on using the integrated LiveCycle Data Services ES that are installed with ColdFusion 8. You can find out more about the different data services options in the data services and integration page of the LiveCycle Developer Center.
Requirements
To complete this tutorial you will need to install the following software and files:
Adobe Flex Builder 3 (includes the free Flex 3 SDK)
Adobe ColdFusion 8
Note: This article uses the integrated LiveCycle Data Services that are installed with ColdFusion 8.
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License
Creating a Flex 3 project
Start by choosing File > New > Flex Project (see Figure 1).
Figure 1. Creating a new Flex project.
Use the New Flex Project wizard (see Figure 2) to set up the project.
Figure 2. The New Flex Project wizard.
Project name and location:
You may type any name for the project. In this example, the project is named “myProject”. You may also change the location of the project – where are all your files are stored – from the default presented to you.
Application type:
For the Application type, select Web Application, which is the default. The application type determines what the compilation step will produce; in this case a SWF file is created when the project is compiled.
Server technology:
For the application server type select ColdFusion. Make sure Use remote object data service is selected and LiveCycle Data Services ES is selected.
Click Next to proceed to ColdFusion server setup (see Figure 3).
How you configure the project to work with the ColdFusion server depends on how ColdFusion 8 was installed. There are two different install options for installing ColdFusion 8: standalone and multiserver. If you installed using the multiserver option, then select “Deployed to J2EE Server” (see Figure 3). If you accepted the default options for the multiserver install then your web root will be C:/JRun4/servers/cfusion/cfusion-ear/cfusion-war. You can browse to this directory by opening the URL http://localhost:8300/ in your browser.
Figure 3. Configuring ColdFusion server.
If you are using Microsoft Internet Information Server (IIS) or Apache with your ColdFusion install, you will need to specify a different web root. If so, make sure to deselect “ColdFusion WAR is located in the web root”, and specify the location of the ColdFusion WAR folder. For example, if you are using IIS with a web root at C:/Inetpub/dev.icm.com and a custom site for the Root URL you would use the wizard to specify that configuration (see Figure 4).
Why do you have to point to the WAR folder? In the following sections, you will edit a configuration file in the ColdFusion server installation directory tree. Flex Builder looks for this file in the WEB-INF folder that is located under the ColdFusion WAR folder.
Figure 4. An example configuration when using IIS.
After modifying these settings as needed, click Validate Configuration. At the top of the dialog box you should see the following message: “The web root folder and root URL are valid”. If not, check your settings to ensure you have correctly set up all required paths. If your settings are valid, click Next.
In the next step you have an opportunity to set the build paths for your project. Leave the defaults set here (see Figure 5). If you had another folder with code you wanted to use in this project, you could add that folder to the Flex project’s build path.
Figure 5. Configuring additional source folders.
Now all the configuration options for the project are set; click Finish.
In the Flex Navigator view you will see the new project created along with several default folders (see Figure 6).
Figure 6. The Flex Navigator view.
Next, right-click the src folder, select New > Folder, type com/adobe/devnet/example, and click OK. The new folder should appear in the folder structure (see Figure 7).
Figure 7. The example folder created in the folder structure.
To ensure you are using the latest Flex SDK, right-click on the myProject folder Navigator view and select Properties from the context menu. When setting up the project Flex Builder detected the SDK on the server. Because the server does not have the latest SDK, Flex Builder set the project to use an SDK matching the server, most likely 2.0.1. Under the Flex SDK version, select the Flex 3 SDK and click OK. You will be prompted that Flex Builder will rebuild the project and delete files under the html-template folder; this is fine and will not hurt your project. Click Continue.
Figure 8. Selecting the Flex 3 SDK.
Using the ColdFusion 8 extensions for Eclipse and Flex Builder
When installing Flex Builder 3 you were asked if you wanted to install the ColdFusion extensions. If you did not select that option you can find them in the ColdFusion LiveDocs.
Set up Eclipse to connect to the ColdFusion Remote Development Service (RDS) by choosing Window > Preferences, then ColdFusion > RDS Configuration (see figure 9).
This example uses the locally installed ColdFusion server. You can specify multiple servers if you also wanted to connect to one or more ColdFusion servers located elsewhere.
Note: If you are using the multiserver install of ColdFusion, the port number will be 8300; if you are using the standalone install you should set the port to 8500. For the security information, type the username and password that you use to log in to the ColdFusion administrator. Click Test Connection to ensure everything is set up correctly and click OK.
Figure 9. Setting the RDS configuration.
To open the RDS view in the Eclipse workbench, choose Window > Other Views. From the list of views which you can add to the workbench, expand the ColdFusion node, select RDS Dataview, and click OK (see Figure 10).
Figure 10. Selecting the RDS Dataview.
In your workbench you should now see the RDS Dataview window (see Figure 11).
Figure 11. The RDS Dataview window.
You may need to click the refresh button to display the list of defined data sources in your ColdFusion server.
At this point, the ColdFusion CFC wizard will do much of the coding work for you. First you need to create the server-side ColdFusion files that will work with LiveCycle Data Services ES. Your list of data sources may differ from the list in Figure 11. If you installed the ColdFusion sample data sources you should have the cfartgallery data source already. If not, you can download the Access database from the article and add it to your data sources in the ColdFusion administrator. Learn more about adding data sources to ColdFusion.
Next, expand the cfartgallery tree (see Figure 12).
Figure 12. Expanding the cfartgallery tree.
Right-click the APP.ARTISTS table and select ColdFusion Wizards > Create CFC (see Figure 13).
Figure 13. Starting the ColdFusion CFC Value Object Wizard
Figure 14. The ColdFusion CFC Value Object Wizard
To create the CFC file, follow these steps:
- Set CFC Folder to /myProject/src/com/adobe/devnet/example
- The default CFC Package Name may be src.com.adobe.devnet.example, change this to com.adobe.devnet.example
- Select LiveCycle Data Services Assembler CFC’s the CFC Type
- Set the AS Folder to /myProject/src/com/adobe/devnet/example
- The default AS Package Name may be src.com.adobe.devnet.example, change this to com.adobe.devnet.example
- Click Finish.
Take a look at the four files that were generated. While this code is everything we need for this example, you can easily modify it to fit any custom needs you may have. In short, you just saved great deal of time having the wizard generate all the base code that you need.
Configuring ColdFusion 8 and LiveCycle Data Services ES
Rich Internet applications that deliver great experiences have data integration needs that go way beyond those of typical Internet page-based applications. This creates new challenges for developers. LiveCycle Data Services ES, however, easily enables this integration while allowing developers to concentrate on building great applications without spending great amounts of time on the server-side logic.
This article focuses on the Data Management Service of LiveCycle Data Services ES that is integrated with ColdFusion 8. The Data Management Service manages client-to-server synchronization by keeping track of changes to the data in your application. When a user changes data in the application and commits the changes to a service running on the server, the data changes are checked for conflicts before they are committed to the database. Further, when a change is made by one client and committed, this change is then pushed out to all other connected clients that are viewing the same data. This behavior is in contrast to most applications, in which the client is required to make requests to the server to get new data. With LiveCycle Data Services ES, changes are “pushed” to the client. This saves bandwidth and makes for a much more robust application.
So far you have completed these steps:
- Set up your Flex 3 project
- Set up the RDS connection to the ColdFusion server
- Used the CFC Wizard to generate all the server-side code you nee
Filling the Data Grid
Next you need to create a destination in the Data-Management-Config.xml under the ColdFusion installation.
- Browse to JRun4/servers/cfusion/cfusion-ear/cfusion-war/WEB-INF/flex.
- Open dataManagement-config.xml for editing.
- Add the following destination below the adapters tag and restart the ColdFusion server.
<!--
Use the ColdFusion adapter for any CF specific destinations
-->
< adapter ref ="coldfusion-dao" />
<!--
Use the ColdFusion configured channels that have
the instantiate-types flag set to false.
-->
< channels >
< channel ref ="cf-rtmp" />
< channel ref ="cf-polling-amf" />
</ channels >
< properties >
<!-- The component name or path on the CF server -->
< component > com.adobe.devnet.example.ARTISTSAssembler </ component >
<!-- Either "application" or "request" -->
< scope > application </ scope >
<!--
Should we look for "getFoo" or "setFoo" when translating an
ActionScript object to a CFC? If not found, the value is set in the
"this" scope. If your CFCs don't have getters and setters,
(they use the this scope) set this to false for better performance.
Optional, Default is true - look for accessor functions.
-->
< use-accessors > true </ use-accessors >
<!--
Should we create CFML Structures instead of value objects
when translating an ActionScript object with a remote alias?
Optional, Default is false (use CFCs)
-->
< use-structs > false </ use-structs >
<!--
The hostname or IP address of the CF host.
If Data Services is installed as part of CF, you omit this.
If Data Services runs outside of CF, you must define this.
<hostname>localhost</hostname>
-->
<!--
This is the ID of the ColdFusion Data Management service as configured
in the ColdFusion Administrator.
Only needed if you have more than one instance of CF on a machine
and Data Services is not installed as part of CF.
<identity>default</identity>
-->
<!--
Credentials to pass to the assembler CFC for all clients
Generally better to use setRemoteCredentials() API on client
<remote-username></remote-username>
<remote-password></remote-password>
-->
<!-- Define the resolution rules and access level of the CFC being invoked -->
< access >
<!-- allow "public" (and remote) or just "remote" methods to be invoked -->
< method-access-level > remote </ method-access-level >
</ access >
<!-- Optional controls for forcing property names to lowercase when converting to ActionScript -->
< property-case >
<!-- cfc property names -->
< force-cfc-lowercase > false </ force-cfc-lowercase >
<!-- Query column names -->
< force-query-lowercase > false </ force-query-lowercase >
<!-- struct keys -->
< force-struct-lowercase > false </ force-struct-lowercase >
</ property-case >
< metadata >
< identity property ="ARTISTID" undefined-value ="0" />
<!--
Optional, If the Assembler fill routine returns a query,
you must define an ActionScript type for the rows.
<query-row-type>com.adobe.icm.serverObjects.dataAccess.ICM_SALES_ORDER</query-row-type> -->
</ metadata >
< network >
<!-- Add network elements here -->
</ network >
< server >
<!--
The method declarations are ignored for CFC Assemblers,
with the exception of the fill-method settings.
No parameters are defined here, unlike Java.
Any arguments provided via the ActionScript call are passed along to the CFC,
just use optional arguments when defining the CFC.
-->
< fill-method >
<!--
Does the assembler have a "fill-contains" method?
This method is used to determine whether to refresh the fill.
If the specified method returns true the fill is re-executed
after a create or update.
Auto-refresh determines if the fill is always refreshed if not specified.
May only be used when auto-refresh is true.
Optional. Default is false.
-->
< use-fill-contains > false </ use-fill-contains >
<!--
Determines whether to refresh the fill on updates or creates.
Optional. Default value is true.
-->
< auto-refresh > true </ auto-refresh >
<!--
Determines whether order is important for this filled collection. Allows for
performance optimization when order is not important.
Optional. Default value is true.
-->
< ordered > true </ ordered >
</ fill-method >
</ server > </ properties > </ destination >
Bringing it all together
Now that ColdFusion and LiveCycle Data Services ES are configured and the server-side ColdFusion CFC files are in place, all that is left is to add a few simple lines of code to the Flex UI. In Flex Builder 3, open the myProject.mxml file. Copy and paste the following code into this file:
< mx:Application xmlns:mx ="http://www.adobe.com/2006/mxml" layout ="absolute"
creationComplete ="fillArtistDP()" >
< mx:Script >
<![CDATA[
import com.adobe.devnet.example.ARTISTS;
import mx.collections.ArrayCollection;
//This dummy variable forces Flex Builder to include Artists object in build
private var dummy:ARTISTS = new ARTISTS();
//ArrayCollection that will hold the data returned from the artistDataService
[Bindable]
private var artistDP:ArrayCollection = new ArrayCollection();
//Function executed on creationComplete event to call the Fill method on artistDataService
private function fillArtistDP():void
{
artistsDataService.fill(artistDP);
}
]]>
</ mx:Script >
< mx:DataService id ="artistsDataService" destination ="artgallerydataservice" />
< mx:DataGrid editable ="true" dataProvider ="{artistDP}" width ="100%" height ="100%" />
</ mx:Application >
That’s all the code you need to make this example work!
The DataService tag points to the artgallerydataservice destination that you created in the data-management-config.xml file that points to the ARTISTSAssembler.cfc. The DataGrid tag is set to be editable so the user can click in fields and edit data live. Once the user has made an edit and steps out of the cell, the change is committed back to the artgallerydataservice, which then pushes the change out to all other connected clients. The DataGrid gets its data from the artistDP array collection that it is bound to. Because the application tag specifies creationComplete=”fillArtistDP()”, the fillArtistsDP method will be executed when the application has finished loading. In this method you simply call the fill method on your DataService and reference the artistDP array collection that should be filled with the resulting data from the service.
You can now browse to the web root at http://localhost:8300/myProject.html. If everything is working properly you should see a grid of editable data (see Figure 16). You can click in each cell and modify the values. When you exit focus from the cell your changes are committed and saved to the server. The really cool part is when you have two or more browsers open. Make a change to a value in one browser, and you will instantly see the change reflected in all other browsers as the server pushes your change out to all other connected clients.
Figure 15. The application’s user interface features an Advanced DataGrid.
Where to go from here
While this article is not intended to teach best practices for building Flex 3 and ColdFusion 8 applications, it showed how easy you can hit the ground running as a developer and build complex functionality with ease.
In this example you saw how the productivity advantages provided by ColdFusion 8, Flex 3, CFC Wizard plug-in, and LiveCycle Data Services ES enable you to quickly build rich Internet applications with robust data management capabilities. ColdFusion 8 is the perfect powerful backend for your rich Internet applications with productivity unmatched by competing technologies. Flex 3 gives you the power to quickly build engaging UIs with minimal effort and easily connect to backend services such as ColdFusion 8 and LiveCycle Data Services ES. It is a truly fantastic time to be a developer equipped with latest Adobe technologies.