Exercise 3.3: Dispatching a value object from the custom component

In previous exercises you created an Employee Portal: Vehicle Request Form. The application UI (the form) is encapsulated in a custom component file and the main application manages the data retrieval and transforms the returned employee data into an ArrayCollection instance of employee value objects. This data is passed to the custom component, via a custom property, and then displayed in the DropDownList control.

Remember that a value object is a packet of related data that you want to treat as a unit. For example, in the case of an employee, the first name, last name, email address, and so on, constitute a unit of data. In the first part of this exercise, you will aggregate data from the form into a second packet of data, or value object, that contains all the vehicle request information.

In the second part of this exercise, you will create a custom event class to dispatch the vehicle request data from the custom component back to the main application. Keep in mind that a custom event class is required when you are dispatching custom data in an event object.

When the user clicks the Submit button for the form, the vehicle request value object is created, passed to the new custom event object and then dispatched to the main application. The user is presented with an alert message that the form has been submitted (see Figure 1).

In this exercise, you will learn how to:

• Create a value object to hold the form data
• Populate the value object with data
• View the populated value object in the Debugger
• Create a custom event class to dispatch the form data
• Dispatch and handling the custom event

In this section you will create a new ActionScript class to represent the Employee Portal: Vehicle Request form data.

1. Download the ex3_03_starter.zip file if you haven't already and extract the ex3_03_starter.fxp file to your computer.
2. Open Flash Builder.
3. Import the ex3_03_starter.fxp project file.
4. Within the Package Explorer view, right-click the src folder and select New > ActionScript class (see Figure 2).

5. Within the New ActionScript class, set the Package value to valueObjects and the Name to VehicleRequest (see Figure 3).

6. Click Finish.

   You should see the VehicleRequest.as file in the Package Explorer view (see Figure 4). You should also see the VehicleRequest.as file open in the Editor view.

7. In the VehicleRequest.as file, within the class definition, type id, press CTRL+1 to invoke the quick assist tool, and select the Create instance variable id option. This declares a private variable named id data typed to the Object class. Modify this variable so that the access modifier is public and so it is data typed to the String class.
   

   
   

8. Below the id variable, use the quick assist tool to create four more public variables named phone, mobilePhone, pickupDate, and returnDate. Data type the variables to the String class.

9. Save the file.

In this section you will use the click event of the Submit Request Button control to call a function that will assign property values to the VehicleRequest value object based on the information in the form fields.

1. From the Package Explorer view, components package, open the VehicleRequestForm.mxml file.
2. At the bottom of the Form container code, locate the FormItem container that nests the Button control.
3. To the Button control, add the click event using the content assist tool (see Figure 5).

4. Using the content assist tool, select the Generate Click Handler option (see Figure 6).

5. Within the Script block, locate the submitButton_clickHandler() function.
6. Within the submitButton_clickHandler() function, delete the generated code stub, create a local variable named vehicleRequestData and use the content assist tool to data type it to the VehicleRequest class (see Figure 7).

7. Ensure an import statement for the valueObjects.VehicleRequest class was created below the others.

8. Within the submitButton_clickHandler() function, set the vehicleRequestData instance to a new instance of the VehicleRequest class. The vehicleRequestData instance is a value object that you will now populate with data from the form.

9. Below the vehicleRequestData variable declaration, set the vehicleRequestData.id value to the dropDownList.selectedItem.id value.

   
   

10. Set the vehicleRequestData.phone value to the phone TextInput control's text property value.

11. Set the vehicleRequestData.mobilePhone value to the mobilePhone TextInput control's text property value.

12. Set the vehicleRequestData.pickupDate value to the pickupDate.selectedDate.toDateString() value.

    Using the toDateString() method allows you to format the selected date as a String value so that it is compatible with the data on the server.

13. Set the vehicleRequestData.returnDate value to the returnDate.selectedDate.toDateString() value.

14. Save the file.

In this section you will use the Flash Builder Debugger to view the data in the value object that you just created.

1. Place a breakpoint on the closing line of the submitButton_clickHandler() function (see Figure 8).

   
   

2. Click the Debug button.

   You should see the application run in a browser.

3. From the DropDownList control, select the employee with the last name Parker.
4. In the Mobile Phone field, type 415-555-5555.
5. From the Pickup Date DateChooser control, select a pickup date.
6. From the Return Date DateChooser control, select a return date.
7. Click the Submit Request Button control.

   You should see the Confirm Perspective Switch dialog box shown in Figure 9.

8. Click Yes to confirm the switch.
9. Within the Flash Debug perspective, double-click the Variables tab to maximize the view.
10. Expand the vehicleRequestData node.

    You should see the properties are populated with values from the Form container (see Figure 10).

11. Double-click the Variables tab to minimize the view.
12. Click the Terminate button to stop the debugging session.
13. Click the Flash perspective button to return to the Flash perspective.

You will dispatch the value object from the custom component to the main application. Remember that in order to pass custom data in an event, you must create a custom event class, which you will do in this section.

1. From the Package Explorer view, right-click the src folder and select New > ActionScript Class.
2. In the New ActionScript Class dialog box, set the Package value to events and the Name to VehicleRequestEvent (see Figure 11).

3. Next to the Superclass field, click the Browse button.
4. In the Superclass dialog box, select the Event class and click OK (see Figure 12).

5. In the New ActionScript Class dialog box, click Finish.

   You should see the VehicleRequestEvent.as file in the Package Explorer view (see Figure 13). You should also see the VehicleRequestEvent.as file open in the Editor view.

6. In the VehicleRequestEvent.as file, within the class definition, use quick assist to declare a public variable named vehicleRequestData and use the content assist tool to data type it to the VehicleRequest class (see Figure 14).

7. Ensure that an import statement for the valueObjects.VehicleRequest class has been created above the class definition.

8. From the VehicleRequestEvent() function, remove the last two arguments.

   The type argument is used by the Event class to define the event type.

9. To the VehicleRequestEvent() function add the vehicleRequestData argument and data type it to the VehicleRequest class.

   With this code, you are declaring that this custom event class requires two arguments: the event type and the data from the form, packaged as a VehicleRequest value object.

10. Within the VehicleRequestEvent() function, from the super() method, remove the bubbles and cancelable arguments.

11. Below the super() method, set the this.vehicleRequestData value to the vehicleRequestData object from the constructor's argument.

12. Save the file.

In this section you will learn how to dispatch the custom event, with the form data, from the custom component to the main application and then handle the event by displaying an alert message to the user.

1. Return to the VehicleRequestForm.mxml in Flash Builder.
2. Below the Metadata comment, create a Metadata block.

3. Within the Metadata block, type [Ev to invoke the content assist tool and declare the Event() method with the name argument set to vehicleRequestEvent and the type argument set to the events.VehicleRequestEvent class.

4. Within the >code>Script block, import the events.VehicleRequestEvent class.

5. Locate the submitButton_clickHandler() function.
6. At the bottom of the submitButton_clickHandler() function, create a local variable named eventObject and data type it to the VehicleRequestEvent class.

7. To the eventObject variable, assign a new instance of the VehicleRequestEvent class, passing vehicleRequestEvent as the type argument and the local vehicleRequestData variable value as the vehicleRequestData argument.

8. Below the eventObject variable declaration, use the dispatchEvent() method to dispatch the eventObject event.

   
   

9. Save the file.
10. From the Package Explorer view, open the ex3_03_starter.mxml file.
11. Locate the components:VehicleRequestForm instance.
12. Within the tag, use the content assist tool to add the vehicleRequestEvent event (see Figure 15).

13. Use the content assist tool to generate an event handler function for the vehicleRequestEvent (see Figure 16).

    Note that Flash Builder automatically gave the component an instance name of vehiclerequestform1.

14. Within the Script block, locate the vehiclerequestform1_vehicleRequestEventHandler() function.
15. Within the function, delete the generated code stub and use the Alert.show() method to display the message, Your vehicle request has been submitted.

16. Save the file.
17. Run the application.
18. From the DropDownList control, select an employee.
19. In the Mobile Phone field, type 415-555-5555.
20. From the Pickup Date DateChooser control, select a pickup date.
21. From the Return Date DateChooser control, select a return date.
22. Click the Submit Request Button control.

    You should see the Alert window displaying the message, "Your vehicle request has been submitted." (see Figure 17).

In this tutorial you consolidated your knowledge about creating custom events and value objects by creating a custom event that dispatched a value object, representing data from a form. You also handled the custom event in the main application and displayed an alert dialog to the user.

In the next videos and exercises, you will learn how to pass this data back to the server for insertion into the database.