Exercise 2.5: Retrieving and handling data with the RemoteObject object

In the previous two exercises you used the HTTPService and WebService components to access dynamic server-side data. Both components return untyped data. If you want to work with typed data, use the RemoteObject component.

In this exercise you will use the RemoteObject object to retrieve the dynamic server-side data to populate the Employee DropDownList control in the Employee Portal: Vehicle Request application shown in Figure 1.

In this exercise you will learn how to:

• Use the RemoteObject object
• Make the RemoteObject request
• View the returned data in the Network Monitor
• Store the returned data in an application variable
• Display the data in the UI
• Implement the fault event
• Examine the fault event object
• Display the fault data in an Alert dialog box

In this section you will use the RemoteObject component to retrieve the data for the Employee Portal: Vehicle Request application.

Note: In this exercise, you are using the remoting gateway for a ColdFusion server. However, you can use any server technology that supports binary AMF data. Some examples are BlazeDS for Java and the Zend Framework for PHP. Explore the mini Flex Developer Centers for PHP, Java, ColdFusion and .NET to learn more about Flex and those technologies.

1. Download the ex2_05_remote_starter.zip file if you haven't already and extract the ex2_05_remote _starter.fxp to your computer.
2. Open Flash Builder.
3. Import the ex2_05_remote_starter.fxp file.
4. Within the ex2_05_remote_starter project, open the ex2_05_remote_starter.mxml file.
5. Locate the Declarations block.
6. Between the Declarations tag set, create a RemoteObject instance:

7. To the RemoteObject component instance, add the id property with a value of employeeService, the destination property with a value of ColdFusion, the source property with a value of f45iaw100.remoteData.employeeData, and the endpoint property with a value of http://adobetes.com/flex2gateway/.

   By setting the source property to f45iaw100.remoteData.employeeData, you are pointing to the ColdFusion component that the RemoteObject instance will use to query the database on the server. The endpoint value, http://adobetes.com/flex2gateway/, refers to the mapping used by the ColdFusion server to handle AMF/RemoteObject requests.

8. Save the file.

In this section you will initialize the retrieval of data using the RemoteObject component.

1. Within the opening Script block, locate the initApp() function.
2. Within the function, call the employeeService.getEmployees() method.

   The getEmployees() method exists in the ColdFusion component and returns all of the employee information listed in the table on the server.

3. Save the file.

Note: In order to complete this part of the exercise, you must have Flash Builder Premium Edition installed. If you have Flash Builder Standard Edition installed, skip this section and continue with the next section. If you want to download and install a trial version of Flash Builder Premium Edition, be sure to 1) back up your existing workspace and projects, 2) uninstall Flash Builder Standard Edition, and then 3) install the trial version of Flash Builder Premium Edition. To compare the Standard Edition with the Premium Edition, check out the Upgrade Details page.

In this section you will use the Network Monitor view to examine the data returned by the RemoteObject object.

1. Open the Network Monitor view (see Figure 2).

2. Click the Enable Monitor button (see Figure 3).

3. Click the Run button to run the application.
4. Return to Flash Builder and double-click the Network Monitor view's tab to maximize the view.
5. Select the recording of the RemoteService (see Figure 4).

Note: If the workspace you are using has multiple projects open, you may not see the recording in the Network Monitor. Close all other projects and enable the monitor again for your current project and make sure the message in the Network Monitor view reads, "Enabled for project 'ex2_05_remote_starter.'"

6. On the right side, within the Response tab, expand the Response body tree to reveal the employee data.

   You should see that the data result is displayed in the Network Monitor as shown in Figure 5.

   Note: The data properties are all uppercase. ColdFusion returns properties in all upper case format by default. You need to adjust the Flex controls to be compatible with the data.

7. Double-click the Network Monitor view's tab to minimize the view.

In this section you will store the retrieved data in an ArrayCollection variable named employees that is bound to the DropDownList control in the Employee Portal: Vehicle Request Form.

1. Within the RemoteObject tag, use the content assist tool to generate the result event (see Figure 6).

2. Within the content assist tool, double-click the Generate Result Handler option (see Figure 7).

3. Within the Script block, locate the employeeService_resultHandler() function.
4. Within the function, remove the commented code and set the value of the employees variable to the event.result property:

5. Use the as operand to cast the event.result value to the ArrayCollection class.

   The result of the RemoteObject object is typed to the Object class by default. You must cast the result to the ArrayCollection class so that it can be used with the employees ArrayCollection variable.

6. Save the file.

In this section you will adjust the application user interface to use the data returned by the service call.

1. In the ex2_05_remote_starter.mxml file, within the Form container block, locate the FormItem container that nests the DropDownList control.
2. Change the value of the DropDownList control's labelField property to LASTNAME.

3. Locate the FormItem container that nests the TextInput control for the office phone number.
4. Change the value the text property is being passed from the DropDownList control to dropDownList.selectedItem.PHONE:

5. Save the file.
6. Run the application.
7. Select an employee from the DropDownList control to see the Office Phone field populate (see Figure 8).

In this section, you will generate a fault event.

1. Return to Flash Builder.
2. Locate the RemoteObject object in the Declarations block.
3. To the RemoteObject object, use the content assist tool to create a fault event.
4. Still using content assist, choose the Generate Fault Handler option. This will create a fault event in the Script block.

In this section, you will use the Flash Builder Debugger to view the information returned from the fault event.

1. From the RemoteObject object's source property, remove the last character so that property will be invalid.

2. Within the Script block, locate the generated employeeService_faultHandler() function.
3. Add a breakpoint to the same line as the closing brace of the employeeService_faultHandler() function (see Figure 9).

4. Save the file.
5. Click the Debug button.
6. Click Yes when the Confirm Perspective Switch dialog box appears.
7. Double-click the Variables tab to maximize the view.
8. In the Variables view, expand the event object to reveal the fault event.

   Note the faultString property and value (see Figure 10).

9. Double-click the Variables tab to minimize it.
10. Click the Terminate button to end the debugging session.
11. Return to the Flash perspective.

In this section, you will use the Alert class to create a pop-up dialog box to display fault data.

1. Within the Script block, locate the employeeService_faultHandler() function.
2. Within the function, use the show() method of the mx.controls.Alert class to display the event.fault.faultString value as text in an Alert pop-up. Make the title of the alert Fault Information.

   Within the Script block, note the import statement for the mx.controls.Alert class. If this import statement is not present, add it to your code to make the application work.

3. Save the file and run the application.

   You will see the Alert dialog box display the fault event information (see Figure 11).

In this exercise you learned how to use a RemoteObject object to retrieve data from a remote ColdFusion server.