Getting started with ColdFusion and Flash Builder 4 – Database, CFC, and data services setup

Introduction

Adobe Flash Builder 4, formerly known as Flex Builder, has simplified the integration of Adobe ColdFusion with the Adobe Flex framework to create SWF applications. You can now use simple wizards to import ColdFusion components (CFCs) into your projects and access data through service calls to the CFC functions. You can also easily populate Flex UI controls with the returned data by simply clicking-and-dragging the data object onto the control.

Many of the tutorials in the Flex and ColdFusion mini learning center use the same sample database with employee sales information for the Fictitious Sales Planner. In this tutorial, you will learn how to set up a ColdFusion data source and Flash Builder project, and use the Flash Builder Data Services wizard to import a CFC for a sample application, Fictitious Sales Planner. You will then access one of the CFC operations to return data to the Flash application and populate a Flex framework DataGrid control.

Time to complete: 15 minutes.

In this tutorial you set up the sample database, and create the Apache Derby data source.

Note: The following setup instructions assume that you have a local, standalone installation of the Developer's Edition of ColdFusion 9 Professional

Downloading the sample database archive file

In this section you will download the F4CF_FictitiousSalesPlanner database directory. This database contains the employee sales data for the Fictitious Sales Planner sample application, which is used in other tutorials of the Flex and ColdFusion mini learning center.

1. Download thef4cf_fictitious_db.zip sample file if you haven't done so already.
2. Unzip the file to the \ColdFusion9\db directory and review the contents:
   The \ColdFusion9\db folder now contains the F4CF_FictitiousSalesPlanner folder which contains the control files and sample data for the Derby db.
3. Start the ColdFusion server.

Creating the Apache Derby Data Source

In this section, you will use the ColdFusion Administrator to create an Apache Derby Data Source to access the FictiousSalesPlanner data.

4. Log on to the ColdFusion Administrator.
5. Expand the Data & Services left hand navigation and Click on Data Sources.
6. Enter F4CF_FictitiousSalesPlanner as the Data Source Name and Select Apache Derby Embedded from the Driver drop down menu as shown in Figure 1.

7. Click the Add button.
8. Click the Browse Server button next to the Database Folder, and navigate to the ColdFusion9\db\F4CF_FictitiousSalesPlanner folder. Click Apply. The Data Source definition panel will appear as shown in Figure 2.

9. Click the Submit button.
10. You should now see the F4CF_FictitiousSalesPlanner Data Source listed under the Connected Data Sources as shown in Figure 3.

You will be testing the installation of the F4CF_FictitiousSalesPlanner data source later in this tutorial.

Time to complete: 5 minutes.

In this section, you will set up a Flash Builder data service project with ColdFusion for use with the Fictitious Sales Planner sample application.

Creating a Flash Builder project

A Flash Builder project is similar to a Dreamweaver site. You create a project to store and organize your code files. Follow these steps to create a Flash Builder project:

1. Open Flash Builder 4.

   Note: We assume that you are working with the standalone (not the plug-in) version of Flash Builder 4 . You can install the plug-in version if you are already using Eclipse for your programming environment. However, you will likely see some minor variations in the following steps. We also assume that you have a local, standalone installation of ColdFusion. You may need to make changes to the paths based on your custom installation.

2. Select File > New > Flex Project as shown in Figure 4.

You will get the new project dialog box. Set up your new project as shown in Figure 5:

• Name the project F4CF_Getting_Started.
• Be sure to use the default location for this example.
• In the Server technology section of the dialog box, select ColdFusion from the Application server type drop-down menu. (Note that the Use remote object access service check box is selected by default when you select a server technology.)
• Select the ColdFusion Flash Remoting option.

3. Click Next.

Connecting to the ColdFusion server

Follow these steps to configure your Flash Builder project to work with your ColdFusion server:

1. In the Configure ColdFusion Server dialog box, select the options for your ColdFusion installation type. Figure 6 shows the settings if you are using the default installation of ColdFusion in Standalone mode on a PC.

Note: If you have used the default installation of ColdFusion in Standalone mode for a Mac OS X computer, your ColdFusion settings will likely be:

• ColdFusion root folder: /Applications/ColdFusion9
• Built-in ColdFusion web server web root: /Applications/ColdFusion9/wwwroot
• Built-in ColdFusion web server root URL: http://localhost:8500

2. Click the Validate Configuration button to ensure that the settings are correct.

   Note that the location of the Output folder is located within the ColdFusion server web root.

   Flash Builder automatically creates a folder named based on the project name and appended with –debug. In this case, the F4CF_Getting_Started-debug folder is where Flash Builder will place the compiled Flash SWF and HTML wrapper files.

   Note: If you have the default installation of ColdFusion in Standalone mode for a Mac OS X computer, your Output folder setting is likely /Applications/ColdFusion9/wwwroot/F4CF_Getting_Started-debug.

   Remember that Flash source files, unlike ColdFusion source files, are not deployed to the web server. Instead, you compile the source into a SWF file that is referenced in HTML wrapper files. The SWF and HTML files are uploaded to the server.

3. Click Finish to create the Flash Builder project.

You will see the F4CF_Getting_Started project in the Package Explorer, shown in Figure 7. Note also that the MXML application file with the same name is created and opened for editing. Note that Figure 7 shows the MXML Editor tab in Design mode. Click the Source button below the tab to see the Editor in code view.

The Flex framework provides two programming languages: ActionScript, which is a fully object-oriented language, and MXML, which is an XML-based language with similar syntax to CFML.

Note: If you are working through the Getting Started section of the Flex and ColdFusion mini learning center, continue with the following section. If you came to this section from another Flex for ColdFusion developers tutorial, return to that tutorial for your next tasks.

Time to complete: 5 minutes.

Now that your database, data source, and Flash Builder project are set up, you are ready to learn how easy it is to retrieve data from a CFC method and bind it to a Flex user interface element.

Introspecting the ColdFusion component

ColdFusion components are a way of organizing your business logic into reusable code. They were introduced in ColdFusion MX and replace the inline database query construct. In other words, instead of putting a cfquery tag at the top of your CFML page, you invoke the query that is placed into a CFC method, passing in arguments as necessary.

Note: Refer to the article Understanding the role of CFCs in Flex application development for more information on CFCs.

1. Download and unzip the provided f4cf_getting_started_tutorial.zip file on your local disk if you haven't done so already.
2. Move the SalesTarget.cfc file to the \\wwwroot\F4CF_Getting_Started-debug directory.

   When you configured the Flash Builder project, a project-specific debug folder was automatically referenced and created as the output location for the compiled SWF and related HTML wrapper files. Since this is a ColdFusion data service project, the debug folder is in the ColdFusion server's web root. Figure 8 shows the CFC in the same directory as the SWF and HTML wrapper files.

   Note: Refer to Deployment assets for more information about the SWF and HTML wrapper files. The default Flash Builder compile settings are configured to create these files immediately and whenever the source files are saved.

3. Open the SalesTarget.cfc file in a code editor or in a browser.

You will see many CFC methods defined with cffunction tags. Each method contains encapsulated business logic for the Fictitious Sales Planner application. In this tutorial, you will use the getAllData operation to retrieve all employees in the database.

Note: Each method has the access property set to remote, which makes the method available for use with SWF applications.

Testing the CFC with the sample data source

You will now use the provided test file to ensure the successful setup of the Fictitious employee data source:

1. Download and unzip the provided f4cf_getting_started _db_test.zip file onto your local disk if you haven't done so already.
2. Move the SalesTargetTest.cfm file to the \\wwwroot\F4CF_Getting_Started-debug directory.
3. Open a browser and run the SalesTargetTest.cfm page.

   You will see all of the database records in a cfdump display (see Figure 9).

Using the Data Services wizard to import a CFC

Next, you will import the CFC into the project using the Data/Services view in Flash Builder:

1. Locate the Data/Services view in Flash Builder shown in Figure 10.

   (If the view is not open, select Window > Data/Services.)

2. Click the Connect to Data/Service link to run the Data Services wizard.

   Note: You can also select Data > Connect to Data/Service to open the Data Services wizard. Use this method if you already have a Data Service defined.

3. Select ColdFusion for the service type (see Figure 11).

4. Click Next.
5. Name the service F4CF_Getting_Started_Service and configure it as shown in Figure 12.

   Note: The service name is arbitrary. You can name it anything you want; however, it is related to the CFC so you will often see it named similarly. In this case, it might be something like SalesTarget_Service. We have chosen to name the service to match the tutorial.

   • Be sure the Import CFC option is selected.
   • Specify the CFC location: Click the Browse button next to the CFC Location field, navigate to the \wwwroot\F4CF_Getting_Started-debug\ directory, select the SalesTarget.cfc file, and click Open.

Note that the Package is set to services.f4cf_getting_started_service. When you complete the following steps you will see that the project's src folder in the Package Explorer contains a services.f4cf_getting_started_service package. This package contains ActionScript files that are automatically generated by the Flash Builder wizard.

6. Click Next.
7. In the Remote Service Authentication dialog box, shown in Figure 13, enter your RDS username and password.

   Note: Be sure to have RDS enabled in the ColdFusion Administrator. Remember that the default username is admin.

8. Click OK.

   Flash Builder accesses the CFC, introspects it, and returns information about the available operations and data types associated with those operations. You will see each method in the CFC displayed in the Service Operations window shown in Figure 14.

9. Click Finish.

   Flash Builder creates the service. You may see the instructions shown in Figure 15, if you have not previously selected the check box in the lower left corner of the Using Remote Services dialog box.

The rest of this tutorial steps you through these instructions.

10. Click OK to dismiss the Using Remote Services dialog box.
11. Locate the Data/Services view to see the CFC operations shown in Figure 16.

Note that the getAllData() method name is followed by the word Object. When Flash Builder introspected the CFC and provided information about the methods, it mapped the ColdFusion query that is returned from this operation to a generic ActionScript Object data type.

Time to complete: 15 minutes.

Now that the CFC has been introspected into Flash Builder and the Flash Builder project is set up, you will use the returned data to create a simple employee data display.

Configuring the data return type

In this section, you will assign your own data type name to the returned data that is retrieved in the CFC method call:

1. Right-click the getAllData() operation in the F4CF_Getting_Started_Service and select Configure Return Type (see Figure 17).

Each record from the query will be placed in an ActionScript object with each column of data (FIRSTNAME, LASTNAME, EMAIL) set in a name/value pair. Each record is indexed starting at zero.

Note: Unlike ColdFusion, ActionScript is a zero-indexed language.

Instead of generically referring to the returned data as an object, this wizard allows you to give the data a return type name. You will do this next.

2. In the Configure Return Type dialog box, leave the radio button checked for Auto-detect the return type from sample data. (see Figure 18).

3. Check the box for Remote authentication, and Enter your username and pasword in the Service Authentication window (see Figure 19).

4. Click OK, and then click Next.
5. Enter a name to create a new data type. In the field next to 'Array of' , enter the name, EmployeeSalesData (see Figure 20).

6. Review the Properties returned by the operation and click Finish.

You can now expand the Data Types category in the Data/Services view to see that the EmployeeSalesData data type is defined as an object that includes EMAIL, FIRSTNAME, and LASTNAME properties (see Figure 21).

Binding data to a Flex component

After you have configured a method return type, you can easily bind it to components. This section demonstrates how to bind the EmployeeSalesData data type to a DataGrid component:

1. Switch to Design mode in Flash Builder by clicking the Design button below the Editor tab (see Figure 22).

2. Locate the DataGrid control of the Components view (see Figure 23).

3. Drag and drop the DataGrid component into the Design view of the F4CF_Getting_Started.mxml file as shown in Figure 24.

4. Drag and drop the getAllData() CFC function from the Data/Services view onto the DataGrid control to populate it with the EmployeeSalesData data type.

Leave the defaults in the Bind to Data dialog window and Click OK. (see Figure 25)

The DataGrid control now has columns that match the properties in the EmployeeSalesData data type (see Figure 26).

5. Select File > Save tosave the MXML file.
6. Click the Run (green round) button to test the file(see Figure 27).

Figure 28 shows the DataGrid control populated with the CFC data. Note that Flash Builder has opened the HTML wrapper file from the F4CF_Getting_Started-debug folder in the web root.

Where to go from here

In this tutorial, you set up the HSQLDB engine, a sample database, and a ColdFusion data source. Then you set up a Flash Builder project to work with ColdFusion server technology. Finally, you experienced how easy it is to retrieve data from a CFC method and bind it to a Flex user interface element.

To learn more about how Flex and ColdFusion work together, refer to the following tutorials:

• Binding data to UI components
• Generating forms
• Creating master/detail forms
• Managing data
• Deploying a Flex application with ColdFusion URL variables