Requirements

 
 
Prerequisite knowledge
In order to successfully complete this tutorial, be sure to set up and test your environment as outlined in Getting started with ColdFusion and Flash Builder 4.You can skip the steps above if you have already successfully completed this 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
  •  
 
User level
All
 
 
Required products
Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)
Flash Builder 4 (Download trial)
   
 
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.
 
 
Configuring data return type
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.
Verify whether the EmployeeSalesData data type has been defined.
Figure 1. Verify whether the EmployeeSalesData data type has been defined.
 
    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).
 
Configure the return type of getItem() function.
Figure 2. Configure the return type of getItem() function.
 
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.
 
Select Auto-detect the return type from sample data.
Figure 3. Select Auto-detect the return type from sample data.
 
  1. In the In the Auto-Detect Return Type, enter 100001 in the Enter Value field (see Figure 4).
Populate the Enter Value field with an employee Id.
Figure 4. Populate the Enter Value field with an employee Id.
 
  1. Click Next.
  2. 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.
Either create a new custom data type or use an existing one.
Figure 5. Either create a new custom data type or use an existing one.
 
  1. 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.
     
  2. 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.
 
The data type and its properties.
Figure 7. The data type and its properties.
 

 
Creating the search control

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).
The Design mode button.
Figure 8. The Design mode button.
  1. Locate the Components view.
    Note: The Components view may be opened by selecting Window > Components.
     
  2. Drag and drop a TextInput control from the Controls folder of the Components view into the design area (see Figure 9).
Drop a TextInput into the Design area.
Figure 9. Drop a TextInput into the Design area.
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.
 
  1. Locate the Properties view.
  2. Give the TextInput control an ID of employeeSearch and press the Enter key (see Figure 10).
Give the TextInput control an ID of employeeSearch.
Figure 10. Give the TextInput control an ID of employeeSearch.
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).
Position the Button control next to the TextInput control.
Figure 11. Position the Button control next to the TextInput control.
  1. Double-click the Button control to change its label to Search.
  2. Drag the getItem() CFC function from the Data/Services view and drop it onto the Search button in the design area (see Figure 12).
Drag and drop the getItem() CFC function onto the Search button.
Figure 12. Drag and drop the getItem() CFC function onto the Search button.
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.
 
  1. 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:
protected function button_clickHandler(event:MouseEvent):void { getItemResult.token = f4CF_Getting_Started_Service.getItem(employeeSearch.text); }
  1. Save the file.

 
Generating a form based on data type

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).
Generate a form using the EmployeeSalesData data type.
Figure 13. Generate a form using the EmployeeSalesData data type.
  1. Leave the default setting for the Choose source dialog box, Data type, shown in Figure 14, and click Next.
The Generate Form Choose source dialog box
Figure 14. The Generate Form Choose source dialog box
  1. In the Property control mapping dialog box, uncheck the SALESTARGETID, EMPIMAGE, YTD, Q1GOAL, and REGION values (see Figure 15).
Select the form fields.
Figure 15. Select the form fields.
  1. Change the Control field to Text for the FIRSTNAME, LASTNAME, PHONE, and EMAIL properties (see Figure 16).
Change the Control type for a form property..
Figure 16. Change the Control type for a form property..
  1. Click Finish.
  2. Reposition the form below the TextInput control (see Figure 17).
The form located below the TextInput and Button controls.
Figure 17. The form located below the TextInput and Button controls.
  1. 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.
Click the Run button.
Figure 18. Click the Run button.
  1. 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.
 
Searching for an employee with the last name Sman.
Figure 19. Searching for an employee with the last name Sman.

 
Mapping the search results to the form

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:
<s:CallResponder id="getItemResult" result=""/>
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.
 
  1. In the result event of the getItemResult CallResponder component, add employeeSalesData = (as shown):
<s:CallResponder id="getItemResult" result="employeeSalesData = "/>
Note that the CallResponder instance is named getItemResult. The returned data is stored in the lastResult object of the getItemResult data.
 
  1. To the right of the equal sign in the result event, add getItemResult.lastResult:
<s:CallResponder id="getItemResult" result="employeeSalesData = 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.
 
  1. After the getItemResult.lastResult value, add [0]:
<s:CallResponder id="getItemResult" result="employeeSalesData = getItemResult.lastResult[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.
 
  1. After the [0] index, use the as operand data type the value to the EmployeeSalesData data type:
<s:CallResponder id="getItemResult" result="employeeSalesData = getItemResult.lastResult[0] as EmployeeSalesData"/>
  1. Save the file and run the application.
  2. Enter the value 100001 into the TextInput control and click the Search button.
  3. Note: You should see the form populated with the information for the fictional employee Allen Sman (see Figure 20).
     
The form displaying employee data from the search.
Figure 20. The form displaying employee data from the search.

 
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.