Generating ColdFusion forms with Adobe Flash Builder 4

Adobe Flash Builder 4, formerly known as Flex Builder, features a form wizard that you can use to quickly create forms populated with data. This allows you to easily create interfaces for manipulating data.

In this tutorial, you will then create a simple employee search tool using Flash Builder controls. Next, you will generate a form using a custom data type. Lastly, you will populate the form with the employee sales data returned from the search tool.

As mentioned in the introduction, this tutorial uses the same development environment as Getting started with ColdFusion and Flash Builder 4 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 Types category. You may see up to two data types listed depending on which tutorials you have completed in this series. Note whether the EmployeeSalesData data type is present.

Follow the steps below to assign your own data type name to the returned data that is retrieved in the getItem() service call to the CFC method:

1. In the Data/Services view, right-click the getItem() function and select Configure Return Type (see Figure 2).

Each record from the query will be 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 the returned data as an object, the wizard lets you to give the data a return type name.

2. Keep the default radio button checked to Auto-detect the return type from sample data (see Figure 3). Click Next.

3. In the In the Auto-Detect Return Type, enter 100001 in the Enter Value field (see Figure 4).

4. Click Next.
5. If the EmployeeSalesData data type does not exist, then, in the Configure Operation Return Type dialog box, create a new custom data type named EmployeeSalesData. If the EmployeeSalesData data type already exists, then click the radio button next to Use an existing data type and select EmployeeSalesData from the popup list (see Figure 5). Also select the Update selected custom data type check box.

6. Click Next.

   Note: If you have stepped through the Managing Data with Adobe Flash Builder 4 tutorial and you delete the first employee in the database (Allen Sman), then you will get an error message that states, "The operation returned a response of the type 'Object'." In this case, use another value, such as 100002 or 100003, which is the primary key for another employee.

7. In the Configure Return Type dialog box, click Finish.

You will see the EmployeeSalesData() data type listed after the getItem() service operation (see Figure 7). Note that the properties of the data type are the query columns returned from the CFC method.

In this section you will create an employee search tool that will retrieve data records according to employee last name:

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_Generating_Forms.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 that you follow in this series to avoid creating additional Flash Builder projects.

5. Switch to Design mode by clicking the Design button below the Editor tab for the F4CF_Generating_Forms.mxml file (see Figure 8).

6. Locate the Components view.

   Note: The Components view may be opened by selecting Window > Components.

7. Drag and drop a TextInput control from the Controls folder of the Components view into the design area (see Figure 9).

The TextInput control will serve as the input field for the search tool. You will be passing the text entered into the TextInput control as an argument to the getItem() function to return the employee's data.

The ID property of the TextInput control is the unique identifier name for the control in the SWF application. The following steps show you how to set the ID property for the TextInput control.

8. Locate the Properties view.
9. Give the TextInput control an ID of employeeSearch and press the Enter key (see Figure 10).

Note: Pressing the Enter key ensures that the property value is retained.

Creating the search functionality

Next, you will use a Search Button control to run the getItem() service operation that will return an employee sales record to this application. You will pass the value entered into the TextInput control as the argument of the getItem() operation when the user clicks the Button control:

1. Drag and drop a Button control from the Controls folder of the Components view and place it to the right of the TextInput control in the design area (see Figure 11).

2. Double-click the Button control to change its label to Search.
3. Drag the getItem() CFC function from the Data/Services view and drop it onto the Search button in the design area (see Figure 12).

Flash Builder will switch you to Source mode and highlight the SALESTARGETID argument in the getItem() service call that is now associated with this Button control.

Flash Builder populated the click event of the Button control with the getItem() function of the F4CF_Getting_Started_Service when you dropped the getItem() function onto the Button control. The argument for the getItem() function is highlighted. By default it is SALESTARGETID because SALESTARGETID is the name of the argument specified in the CFC and introspected by the Data Service wizard when it evaluated the CFC and added it to the Data/Services view.

However, you want to use the employee SALESTARGETID that was entered into the TextInput control as the argument. Remember that you gave the TextInput control a unique identifier of employeeSearch. You access the text value entered into the TextInput control through the text property of that control.

Note: You can also define the argument required by the getItem() function to any column of the SalesTargets data table. Simply update your CFC function appropriately.

4. Replace the SALESTARGETID argument between the parentheses of the f4CF_Getting_Started_Service. getItem() function with the employeeSearch.text property as shown in the following snippet:

5. Save the file.

In this section, you will use the Flash Builder Form Generation wizard to create a form that is bound to employee sales data. You will use this form to display individual employee data requested by the search tool.

1. Switch to Design mode.
2. In the Data/Services panel, right-click the EmployeeSalesData data type and select Generate Form (see Figure 13).

3. Leave the default setting for the Choose source dialog box, Data type, shown in Figure 14, and click Next.

4. In the Property control mapping dialog box, uncheck the SALESTARGETID, EMPIMAGE, YTD, Q1GOAL, and REGION values (see Figure 15).

5. Change the Control field to Text for the FIRSTNAME, LASTNAME, PHONE, and EMAIL properties (see Figure 16).

6. Click Finish.
7. Reposition the form below the TextInput control (see Figure 17).

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

9. Enter 100001 into the TextInput control and click the Search button.

You should see that the form will not populate when an employee's SALESTARGETID is entered (see Figure 19). You will fix this in the next section.

In this section, you will populate the form based on the result of the search query:

1. Switch to Source mode.
2. Locate the <fx:Declarations> tag block.

   The <fx:Declarations> tag block contains the code that is generated by Flash Builder when you drop a service operation onto a UI control. The code created consists of a CallResponder component and data type component. The CallResponder component deals with the returned data. You will add an ActionScript result handler to it that will populate the form.

3. Locate the getItemResult CallResponder component and add the result event to the CallResponder component:

The form you created with the Form Generation wizard is based on the employeeSalesData data type instance so you want to populate that instance with the data that is returned from the service call.

4. In the result event of the getItemResult CallResponder component, add employeeSalesData = (as shown):

Note that the CallResponder instance is named getItemResult. The returned data is stored in the lastResult object of the getItemResult data.

5. To the right of the equal sign in the result event, add getItemResult.lastResult:

Only one record is being return, so you will need to reference the first element. Remember that ActionScript is a zero-indexed language so use zero.

6. After the getItemResult.lastResult value, add [0]:

ActionScript requires that the data types on each side of a value assignment match so you must cast the result data as an EmployeeSalesData data type.

7. After the [0] index, use the as operand data type the value to the EmployeeSalesData data type:

8. Save the file and run the application.
9. Enter the value 100001 into the TextInput control and click the Search button.

Note: You should see the form populated with the information for the fictional employee Allen Sman (see Figure 20).

Where to go from here

In this tutorial you learned how to use the Adobe Flash Builder Form Generation wizard to create a search interface. If you are interested in learning how to integrate your SWF applications into a ColdFusion web page and to pass URL variables to it, be sure to read Deploying a Flex application with ColdFusion URL variables.