Managing ColdFusion data with Adobe Flash Builder 4

Adobe Flash Builder 4 has a Data Management wizard that makes it easy for you to map ColdFusion server-side create, retrieve, update, and delete (CRUD) business logic to data service calls and then apply them to UI controls.

In this tutorial, you will create a data service for the CFC and then use the Flash Builder Data Management wizard to map CRUD operations between the application and the server by creating ActionScript event handlers for the UI controls.

You can skip the steps above if you have already successfully completed the "Getting started with ColdFusion and Flash Builder 4" tutorial or any other tutorial in this series.

This tutorial is intended for:

• Experienced ColdFusion developers without previous Adobe Flex framework or Adobe Flash Builder 4 experience.
• ColdFusion developers who are familiar with ColdFusion components.

As mentioned in the introduction, this tutorial uses the same development environment as the Getting started with ColdFusion and Flash Builder 4 tutorial and the other tutorials in this series.

1. Locate the Data/Services view in Flash Builder 4. You should see the F4CF_Getting_Started_Service service shown in Figure 1.

2. Expand the Data Type category. If you see the EmployeeSalesData data type listed (also shown in Figure 1), then you can skip to the next section, Mapping service calls to CRUD functionality.
   

If you do not see the data type, follow the steps below to assign your own data type name to the returned data that is retrieved in the getAllData() service call to the CFC method.

1. Right-click the getAllData() function in the F4CF_Getting_Started_Service option of the Data/Services view and select Configure Return Type (see Figure 2).

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

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

Rather than generically referring to this returned data as an object, this wizard lets you to give the data a return type name. You will do this next.

2. In the Configure Return Type dialog box, click Next to auto-detect a return type (see Figure 3).

3. In the Configure Return Type dialog box, create a new custom data typenamed EmployeeSalesData. (see Figure 4).

4. Click Finish.

You will see the EmployeeSalesData data type listed in the Data Types category of the Data/Services view (see Figure 5). Note that the properties of the data type are the query columns returned from the CFC method.

In this section, you will use the Data Management wizard to map CRUD functionality to the appropriate service call for adding, updating, and deleting records in a database.

1. In the Data/Services view, right-click the EmployeeSalesData data type and select Enable Data Management.
2. In the Select Unique Identifier for the Data Type dialog box, click the check box next to SALESTARGETID (see Figure 6).

You must choose the SALESTARGETID as the unique identifier for the EmployeeSalesData data type, because it is the primary key of the database.

3. Click Next.

   In the Map Data Management Operations dialog box, you must select the appropriate service call for each field.

4. For the Create (Add) Operation, select the createItem() service operation from the popup menu.
5. Select getItem() for the Get Item operation.
6. Select updateItem() for the Update Item operation.
7. Select deleteItem() for the Delete Item operation.

   Figure 7 shows what your Map Data Management Operations dialog box should look like at this point.

You learned earlier that the arguments for each service were introspected from the CFC by the Flash Builder Data Service wizard. For the add and update operations, you will pass a complex object, in this case the EmployeeSalesData data type, to the CFC. The getItem() and deleteItem() operations only need to pass the the primary key, SALESTARGETID, for processing.

8. Click Finish.

   You should see that the EmployeeSalesData data type now has the data management icon (two green arrows in opposite directions) applied to it (see Figure 8). Also, note that the SALESTARGETID data object now has a key icon next to it, indicating that it is the primary key of the managed data.

In this section, you will populate a DataGrid control with employee sales information.

1. In the F4CF_Getting_Started project, close all open MXML files.
2. Create a new application file by selecting File > New > MXML Application from the menu.
3. Name the file F4CF_Managing_Data.mxml and set the Layout popup list to None.
4. Click Finish.

   Note: In practice you will usually have only one main application file in a Flash Builder project. You will create a new main application file for each tutorial you follow in this series to avoid creating additional Flash Builder projects.

5. Select Design mode and locate the Components view.
6. Select a DataGrid control and drag it into the Design area (see Figure 9).

7. Using the Properties view, enter employeeDataGrid for the ID property of the DataGrid control, and set the Editable property to True (see Figure 10).

8. In the Data/Services view, drag and drop the getAllData() function onto the DataGrid control (see Figure 11).

   You should see the DataGrid control populate the column titles with the columns from the database.

9. Leave the defaults in the Bind To Data dialog window, and Click OK (see Figure 12).

10. Save the file and run the application by clicking the Play (round green) button on the toolbar (see Figure 13). Alternatively, you can select Run > F4CF_Managing_Data.

You will see the DataGrid control populated with all of the data from the database (see Figure 14). Note that you can edit all of the cells in the DataGrid control except the primary key values.

In this section you will add Button controls to the display that the user will click to add, delete, or save the employee sales data. Next, you will have Flash Builder generate the skeleton code for the Button control click handlers. Lastly, you will write some simple ActionScript logic to send the data back to the server.

Adding Button controls to the interface

In the following steps, you will add Button controls to the application display that users will use to trigger add, delete, and save functionality.

1. Drag and drop three Button controls from the Controls folder of the Components view into the Design area (see Figure 15).

2. Double-click each Button to change the button label to Create, Delete, and Save All, respectively.

Handling Create button events

In the following steps, you will create a click handler for the Create Button control that will add records to the DataGrid control.

1. Right-click the Create Button control and select Generate Click Handler.

   Flash Builder 4 will generate a custom ActionScript click handler function and switch you to Source mode so that you can add the business logic to it.

2. Rename the button1_clickHandler() function to createButton_clickHandler().

   Note: ActionScript supports many types of events. The MouseEvent data type for the event argument declares that this code is written for user mouse interactions. For more information about ActionScript events, see the Handling user events and Introducing the event object videos in the Flex in a Week video training series.

3. Replace the //TODO Auto-generated method stub comment with a new ActionScript variable that you create using the var keyword. Name it employee and give it a data type of EmployeeSalesData. Set the variable equal to a new instance of the EmployeeSalesData().

This code creates a new instance of the EmployeeSalesData data type that you defined earlier. Remember that each record that was received in the getAllData() service operation is an instance of the EmployeeSalesData, which contains the values for the SALESTARGETID, FIRSTNAME, LASTNAME, and all the other properties from the database. If you cut-and-pasted the code, Flash Builder will not have added the import statement. Manually add it now above the other import statements.

4. Note that when you typed the new EmployeeSalesData() statement that Flash Builder automatically added the following import statement to the beginning of the Script block that will allow you to use this class in ActionScript code.

5. Below the variable declaration, define the SALESTARGETID, FIRSTNAME, LASTNAME, PHONE, EMAIL, REGION, EMPIMAGE, YTD, and Q1GOAL properties:

You have just populated the new instance of the EmployeeSalesData object with new data.

Note: For the purposes of this example, you are hard-coding the SALESTARGETID property.

6. Below the employee property declarations in the createButton_clickHandler() function, attach the newly created employee information to the DataGrid control's dataProvider property.

The dataProvider property of a DataGrid control contains a complex object that contains all of the EmployeeSalesData instances for all the records. The addItem() method of the DataGrid control will add the specified item, in this case employee, to the end of the data.

7. Set the DataGrid control's verticalScrollPosition property to adjust for the new row being added to the control.

The dataProvider property has a length value that contains the number of records in the DataProvider control. ActionScript starts counting at zero, so you must subtract 1 from the length to get the index of the last record. By setting this calcuation for the verticalScrollPosition property you are forcing the scrollbar for the DataGrid control to move to the bottom when you add the new record.

8. Switch to Design mode.
9. Select the Create button.
10. Use the Properties view to change the value of the On Click property to createButton_clickHandler(event) (see Figure 16).

11. Save the file and run the application.
12. Click the Create button.

Handling Save All button events

In the following steps, you will create a click handler that commits all changes to the DataGrid control to the server.

1. Return to Design mode.
2. Right-click the Save All Button control and select Generate Click Handler.

   Note: Flash Builder will generate an event handler function and switch you to the Source view.

3. Rename the generated function saveAllButton_clickHandler().
4. Replace the //TODO Auto-generated method stub comment with a call to the commit() function of the F4CF_ManagingData_Service as shown in the following snippet:

Remember that, earlier, you created the data service named F4CF_Managing_Data_Service. Flash Builder generated all the code necessary for that data service to function. You reference the service in ActionScript with the same name as your data service, but with an initial lowercase letter. This is common practice for naming instances.

The commit() function is a built-in function of the data service that will run the service that you defined as the update operation in the Data Management wizard. In this case, it is running the updateItem() function once for each record in the DataGrid control.

5. Switch to Design mode.
6. Select the Save All button.
7. Use the Properties view to change the value of the On Click property to saveAllButton_clickHandler(event).
8. Save the file and run the application.
9. Click the Create Button control and add a new record.
10. Click the Save All Button control to send the changes to the server.
11. Refresh the browser to refresh the application.

You should see that your new record has been added to the database.

Handling Delete button events

In the following steps, you will create a click handler for the Delete Button control that will be used to delete records from the DataGrid control.

1. Return to Design mode.
2. Right-click the Delete Button control and select Generate Click Handler.

   Note: Flash Builder will generate a click handler function and switch you to the Source view.

3. Rename the generated function deleteButton_clickHandler.
4. In the deleteButton_clickHandler() function, use the deleteItem() service operation to delete the selected row from the DataGrid control employeeDataGrid using the primary key, SALESTARGETID:

5. Return to Design view.
6. Select the Delete Button control and Locate the Properties view.
7. Change the On Click property to deleteButton_clickHandler(event).
8. Save and run the file.
9. Select the record that you just created earlier and click the Delete button.

When you refresh the browser, you will see that the record has been removed from the database.

Where to go from here

In this tutorial you learned how to create client-to-server CRUD functionality using the Flash Builder Data Services and Data Management wizards. To learn more about how Flex and ColdFusion work together, refer to the following tutorials:

• Creating Master/Detail forms
• Deploying Flex apps with ColdFusion URL variables