Exercise 4.5: Creating and using item renderers and item editors

In this exercise you will use multiple methods to apply item editors and item renderers to a DataGrid control as shown in Figure 1.

In this exercise, you will learn how to:

• Create an inline item renderer
• Create a component item renderer
• Set the item renderer as the editorr
• Create an inline item editor
• Create a component item editor
• Handle a DataGrid control click event

By default, an item renderer is displayed as a text field. In this section, you will create an inline item renderer that displays employee evaluation scores in a customized text field.

1. Download the ex4_05_starter.zip file provided if you haven't already and extract the ex4_05_starter.fxp to your computer.
2. Open Flash Builder.
3. Import the ex4_05_starter.fxp file.
4. Open ex4_05_starter.mxml.
5. Run the application.

   This is the application you built in the previous exercise. You should see the application consists of a DataGrid control with two columns, Name and Hire Date (see Figure 2).

6. Return to the ex4_05_starter.mxml file in Flash Builder.
7. Below the UI components comment, locate the columns property that contains the ArrayList instance within the DataGrid control.
8. Below the second GridColumn control that displays the employee hire dates, add another instance of the GridColumn control.

9. To the same GridColumn control, add the dataField property with a value of evaluation and the headerText property with a value of Evaluation.

The dataField property references the evaluation data from the employees.xml file in the data package of this propject. This data represents the quarterly performance evaluation score for each employee.

10. Save the file and run the application

Notice that the Evaluation column is too small to see the header (see Figure 3).

11. Return to the main application file.
12. Locate the DataItem control within the typicalItem property.
13. After the hireDate, add the evaluation object and set its value to the full length of the headerText, Evaluation.

14. Save the file and run the application.

Notice that the Evaluation column is now large enough to display the whole header and all of the data (see Figure 4).

15. Return to the ex4_05_starter.mxml file.
16. Change the Evaluation GridColumn instance from single tag syntax to block syntax.

17. Within the GridColumn block, add an inline itemRenderer property block.

18. Within the itemRenderer block add a Component block.
19. Within the Component block, add a GridItemRenderer tag block.

20. Inside the GridItemRenderer block, add a Label control.
21. To the Label control, add a text property that binds the value of the data property referencing the evaluation data. All data stored in the dataProvider property is referenced through the data property of the DataGrid control.

You are adding the text property to the Label control and binding it to display the data from the dataField property in the GridColumn control. In this case, you are displaying the evaluation data.

22. Add the height property with a value of 100% and the right property with a value of 10.
23. Next, add the verticalAlign property with a value of middle, the fontWeight property with a value of bold, and the fontStyle property with a value of italic.

24. Save the file and run the application.

You can see that the text in the Evaluation column of the DataGrid control has been formatted and still displays the evaluation data (see Figure 5).

In this section, you will create a new component item renderer to display employee images.

1. Return to Flash Builder.
2. In the Package Explorer view, right-click the src folder and select New > Item Renderer.
3. Type components for the Package and type EmployeeDisplay for the Name.
4. For the Template, choose the Select the Item renderer for Spark DataGrid (MXML) option.

   The New Item Renderer dialog box should look like Figure 6.

5. Click Finish.

   The new EmployeeDisplay item renderer will open in the Editor view. Note that the EmployeeDisplay.mxml file extends the GridItemRenderer class.

6. To the opening GridItemRenderer tag, add the width and height properties and set their values to 100.
7. In the new EmployeeDisplay custom component file, remove everything within the GridItemRenderer tag block.
8. Within the GridItemRenderer block, create an instance of the VGroup.
9. Within the VGroup container, add a Label control.
10. To the Label control, add the text property and use the firstName and lastName data objects as the value.

11. Under the Label control, add a BitmapImage control and set the source property value to images/{data.id}.jpg.

12. Save the file and open the ex4_05_starter.mxml file.
13. Remove the labelFunction property from the GridColumn instance that displays the employee's name.
14. To the same instance of the GridColumn, add the itemRenderer property and set its value to point to the EmployeeDisplay custom component in the components package.

15. Save the file and run the application.

You should see the Name column of the DataGrid control, now displays both the employee names and images. Notice that the names and images are not centered within the column. Also notice that you may not be able to see the whole DataGrid control in the browser (see Figure 7).

16. Return to the ex4_05_starter.mxml file.
17. To the DataGrid control, add a height property with a value of 600.
18. Save the file.
19. Return to the EmployeeDisplay.mxml file in Flash Builder.
20. To the opening tag of the VGroup container, add the horizontalAlign property with a value of center and the verticalAlign property with a value of middle.
21. Next, add the width and height properties to the VGroup definition and set both values to 100%.
22. Save the file and run the application.

You should see that the employee data in the Name column is now centered within the column and the DataGrid control is contained within the browser (see Figure 8).

As you know, the display that you view in a cell of the DataGrid control is an item renderer. When you double-click on an editable cell, you are presented with the display for an item editor. Like the item renderer, by default, the item editor is a text field. In this section, you will apply the NumericStepper control as an item renderer and then set it to display as the item editor as well

1. Return to the main application file in Flash Builder.
2. To the DataGrid control, add the editable property and set its value to true.
3. Save the file and run the application.

Notice that every item in the DataGrid is editable if you double-click it (see Figure 9).

4. Return to the ex4_05_starter.mxml file.
5. To the GridColumn control with the Name headerText, add the editable property and set it to false.
6. Repeat step 5 for the GridColumn control with the Hire Date headerText.
7. Save the file and run the application.

   You should see that only the Evaluation column is editable.

8. Return to the main application file.
9. Locate the GridItemRenderer for the Evaluation column and comment out the Label control within the block.
10. Within the GridItemRenderer block, add an instance of the NumericStepper control.
11. Save the file and run the application.

    The Evaluation column now displays a NumericStepper control for the item renderer but all of the values are set to zero as shown in Figure 10.

12. Return to the ex4_05_starter.mxml file.
13. Add the value property to the NumericStepper control with a value that binds the data.evaluation data.

14. Save the file and run the application.

The Evaluation column now shows the correct data (see Figure 11). Notice that you can change the value in the NumericStepper, but if you change the value to a number larger than 10, it switches the value back to 10. This is because the NumericStepper has a default maximum value of 10.

15. Return to the main application file.
16. To the NumericStepper, add the width property with a value of 100% and add the maximum property with a value of 100.

17. Save the file and run the application.

    The maximum number in the NumericStepper is now 100. If you type a number greater than 100, the NumericStepper will switch the number to 100 as it did before.

18. Double-click on the NumericStepper.

    Notice that the item editor is still a text field (see Figure 12).

19. Return to the ex4_05_starter.mxml file.
20. To the GridColumn control, add the rendererIsEditable property and set the value to true.

21. Save the file and run the application.

You no longer see a text field when you double-click the NumericStepper control because the item editor is now the NumericStepper control defined in the item renderer.

In this section you will use the itemEditor property to create an inline item editor.

1. Return to the ex4_05_starter.mxml file in Flash Builder.
2. From the evaluation GridColumn instance, remove the rendererIsEditor property.
3. Locate the inline itemRenderer property and change it to the itemEditor property.
4. Change the GridItemRenderer instance to GridItemEditor.
5. Save the file.

   You should see a warning that says, "Data binding will not be able to detect assignments to 'data'."

6. Run the application.

   Notice when you try to edit the last column, the value in the NumericStepper is zero. Also notice that when you change the number, it returns to the original evaluation score.

7. Return to the main application file.
8. To the NumericStepper control, change the value property to @{value}.

The "value" in the binding is a property of the GridItemEditor instance and holds the value of the data for the data provider of this cell. In this case, that data is the evaluation value. You use @ to create a two-way binding so that when a user updates the NumericStepper, the data in the data provider updates, too.

9. Save the file.

   You should see the warning goes away.

10. Run the application.

    Now when you edit the Evaluation column, the value in the NumericStepper starts at the original evaluation score. When you change the value in the NumericStepper, the value is properly updated in the column.

In this section, you will create a new component file for the item editor you created in the last section.

1. Return to Flash Builder.
2. In the Package Explorer view, right-click the components package and select New > MXML Component.
3. In the New MXML Component dialog box, type EmployeeEvaluation for the Name.
4. In the Based on field type GridItemEditor to base the component on the GridItemEditor class.
5. Remove the Width and Height values.

   The New MXML Component dialog box should appear as shown in Figure 13.

6. Click Finish.
7. Return to the main application file.
8. Locate the GridItemEditor block within the itemEditor property block.
9. Cut NumericStepper control and paste it under the Declarations block in the EmployeeEvaluation.mxml file.
10. Save the file.
11. Back in the main application file, remove the itemEditor property block and its contents.
12. Modify the Evaluation GridColumn instance so that it uses single tag syntax.
13. To the same GridColumn instance, add the itemEditor property and set its value to reference the EmployeeEvaluation file in the components package.

14. Save the file and run the application.

    You should see that there is no change to the application.

In this section, you will add the selectionChange event to the DataGrid control and handle a user selection of a DataGrid item.

1. Return to the ex4_05_starter.mxml file.
2. To the DataGrid control, add the selectionChange event.
3. Use content assist (CTRL+Space) to generate an event handler.

4. Locate the generated datagrid1_selectionChangeHandler() method in the Script block.

5. Place a breakpoint on the same line as the closing brace of the function.
6. Save the file and debug the application.
7. Click one of the cells in the Evaluation column of the application.
8. Click Yes in the Confirm Perspective Switch dialog box.
9. Double-click the Variables tab to maximize the view.
10. Expand the event and inherited objects to reveal the currentTarget object.
11. Expand the currentTarget object to reveal the selectedItem object. Notice that the selectedItem object contains the data for the employee's evaluation score you selected (see Figure 14).

12. Double-click the Variables tab to minimize the view and Terminate the debugging session.
13. Return to the Flash Perspective and the main application file.
14. Within the datagrid1_selectionChangeHandler() function, remove the generated code stub and use content assist (CTRL+Space) to add the Alert.show() method.

15. If you used the content assist tool to add the Alert.show() method, then the Alertcontrol should have been automatically imported. If you do not see the import statement, manually add the import statement for the control.

16. Within the Alert.show() method, add the string You selected, followed by a literal space, concatenated with the value.
17. Separated by a comma, within the Alert.show() method, add a title heading that reads Employee Portal: Notification.

18. Save the file and run the application.
19. Double-click a cell in the Evaluation column.

You should see an alert message appear for the employee you selected (see Figure 15).

In this exercise you used multiple methods to apply item editors and item renderers to a DataGrid control.