Migrating Flex 3 applications to Flex 4.5 – Part 4: Using Spark Panel, List, DataGrid, and VGroup components and adding custom skins and states

This article is Part 4 of a four-part series in which you import the Flex 3 Dashboard demonstration application available on the Flex Developer Center into Flash Builder 4.5, and then migrate the application to Flex 4.5 to take advantage of the Flex 4.5 Spark architecture and components.

Although a key feature of Flex 4.5 is its support for creating mobile applications in Flex, this article series does not cover converting the Dashboard application to a mobile application. A future article series will cover creating a mobile Dashboard application. Also, although Flex 4.5 introduces locale-aware formatters, they will not be used in this article series because the Dashboard application does not involve localization.

Part 1 of this series described how to import the Flex 3 Dashboard into Flash Builder 4.5 make just enough changes to get it to compile and run. Part 2 began the process of migrating the Dashboard code to Flex 4.5 by modifying the application background and TabBar to make use of the new Flex 4.5 Spark components. Part 3 continued the migration and described changes required to have the application's ViewStack use the new Flex 4.5 Spark NavigatorContent container. Part 4.5 (this article) completes the migration by adding Spark Panel, List, DataGrid, and VGroup components as well as custom skins and states.

If it has been a while since you completed Parts 1 and 2, you may want to quickly refer to the opening sections of those articles for a review of the Dashboard application, how the conversion is organized, and some tips for following the steps.

The sample files for this article include Dashboard-Part4-Start.fxp, which you can use as a starting point for the steps that follow. This Flex project file includes all the steps through Part 3 in this series.

In this section you'll create two custom button skin classes for the maximize and minimize buttons located in the Pod title bar area. These skins will implement the maximizeRestoreButton and minimizeButton styles from styles.css.

1. Right-click the skins folder in Package Explorer and select New > MXML Skin.
2. For the maximize button, type CustomMaximizeButtonSkin as the Name, and select spark.components.ToggleButton as the Host Component.
3. Ensure the Create As Copy Of setting is spark.skins.spark.ToggleButtonSkin and select Remove ActionScript Styling Code.
4. Click Finish.
5. Right-click the skins folder in Package Explorer again and select New > MXML Skin.
6. For the minimize button, type CustomMinimizeButtonSkin as the Name, and select spark.components.Button as the Host Component.
7. Ensure the Create As Copy Of setting is spark.skins.spark.ButtonSkin and select Remove ActionScript Styling Code.
8. Click Finish.

Note: Recall that the maximize button uses the ToggleButton control because the Spark Button control does not support the selected property as the MX Button does. This property is necessary to switch between the maximized and restored states for the button display.

9. To use these custom skin classes, set the skinClass properties for the buttons in CustomPanelSkin.mxml in the controlsHolder HGroup:

10. Open the CustomMinimizeButtonSkin.mxml and CustomMaximizeButtonSkin.mxml files.
11. In both files, remove minWidth="21" minHeight="21" from the opening <s:SparkButtonSkin> tag.
12. In both files, remove everything in layers 1 through 8. Basically, remove everything from the ending </s:states> tag until just before the ending </s:SparkButtonSkin> tag.
13. In CustomMinimizeButtonSkin.mxml only, add the following, directly after the ending </s:states> tag:

14. In CustomMaximizeButtonSkin.mxml only, add the following, directly after the ending </s:states> tag:

15. Save your changes and build the project.

When you launch the Dashboard you'll see that the Pod title bar area looks very much like the corresponding area in the Flex 3 Dashboard application.

Changes are necessary in CustomPanelSkin.mxml to support displaying pods in a minimized state. Some of these steps are intricate, so follow along carefully.

1. Add support for the new minimized state by adding this line to the <s:states> tag:

2. Add excludeFrom="minimized" to the following three visual elements, which should not display in the minimized state:

You'll need to modify the updateDisplayList() function to check for null objects, because in the minimized state, excluded visual elements will not exist and will cause null object runtime errors.

3. You can just replace the entire function definition in CustomPanelSkin.mxml with the one below:

4. Save your changes and build the project.

Now you can minimize, maximize, and restore the Dashboard pods, in the same manner as the Flex 3 application. However, dragging the pods does not work, which will be fixed when you convert the DragHighlight component next.

The next step is to convert the DragHighlight component, which displays a highlight box when pods are dragged, to Flex 4.5. You will use a Spark BorderContainer to define the visual aspects of the drag highlight defined in the DragHighlight style in styles.css.

1. Open src/com/esria/samples/dashboard/view/DragHighlight.mxml.
2. Replace the <mx:Box> tag with the following:

3. Save your changes and build the project.

This is the only change necessary for the DragHighlight component. If you run the application now, you'll be able to drag Pods without a runtime error.

In the Flex 3 Dashboard application, the PodContentBase class extends the Flex 3 MX VBox container. To migrate to Flex 4.5, it will need to extend the Spark VGroup instead. Because it does not use a skin, the VGroup container has a lighter weight than the VBox container. The PodContentBase class is the base class of the ChartContent, FormContent, ListContent, and PieChartContent components, which represent the actual data for the pods.

1. Open src/com/esria/samples/dashboard/view/PodContentBase.as.
2. Locate the following line:

3. Replace it with this line:

4. Locate the following line:

5. Replace it with this line:

6. Save your changes.

These are the only two changes necessary to the PodContentBase class. Note that launching and using the application now might result in empty pods or runtime errors, because although you have modified the PodContentBase class, you have not yet modified its subclasses.

This is the first of four sections in which you make changes to the ChartContent, PieChartContent, FormContent, and ListContent components, which extend the PodContentBase class and represent the actual data for the pods. All of these components are located in src/com/esria/samples/dashboard/view/.

Several steps in these sections are the same, but you will make changes to each component separately, because making changes to all four files at the same time would make it impossible to launch the application for an extended period of time due to multiple errors.

1. To begin, open ChartContent.mxml.
2. Update the namespace definition in the root tag by replacing: xmlns:mx=http://www.adobe.com/2006/mxml with the following lines:

3. Change the namespace prefix from mx to fx for the <mx:Script> tag.

Note: When changing a tag from mx to fx (or in some cases, from mx to s ) here and throughout these steps, remember to change the associated closing tag as well; for example, change </mx:Script> to </fx:Script> .

4. Change the namespace prefix from mx to fx for all <mx:Component> tags.
5. Enclose the two effects defined in the file within an <fx:Declarations> tag, so non-visual elements can be distinguished from visual elements:

6. To use the Spark DropDownList instead of the MX ComboBox, replace the entire MX ComboBox declaration with this:

7. Delete import mx.controls.ComboBox; . It is no longer needed.

A Spark DropDownList is used instead of a Spark ComboBox because the Spark ComboBox items are editable by default, and the Dashboard items should not be editable. Also, notice that the DropDownList width is specified because the default behavior of the Spark DropDownList in the Dashboard does not respect the size of the largest item.

8. Locate the onChangeComboBox() function and update the event type. Change ListEvent to IndexChangeEvent .
9. At the top of the file, remove import mx.events.ListEvent; and add import spark.events.IndexChangeEvent; .
10. Inside the onChangeComboBox() function locate the following line:

11. Replace it with this line:

12. Add fontFamily="verdana" to the <mx:ColumnChart> and <mx:LineChart> tags.
13. Replace the <mx:HBox> tag with <s:HGroup> .
14. Replace all <mx:Canvas> tags with <s:NavigatorContent> .
15. Save your changes.

In this section, you'll update the PieChartContent component.

1. To begin, open PieChartContent.mxml update the namespace definitions:

2. Remember to remove the MX namespace:

3. Then change the namespace prefix from mx to fx for the <mx:Script> tag and for the <mx:Component> tag.
4. Enclose the two effects defined in the file within an <fx:Declarations> tag.
5. Lastly, add fontFamily="verdana" to the <mx:PieChart> tag.
6. Save your changes.

In this section, you'll update the FormContent component. Several steps in this section are identical to steps in the section on modifying the ChartContent component.

1. To begin, open FormContent.mxml and update the namespace definitions as you did for ChartContent.mxml.
2. Update the namespace prefix for the <mx:Script> tags to fx .
3. Add gap="7" to the <PodContentBase> root tag near the top of the file. This adds vertical space between elements in the PodContentBase container.
4. Replace the entire MX ComboBox declaration with the following:

5. In the onChangeComboBox() method, locate this line:

6. Replace it with this line:

7. Change the event type in the onChangeComboBox() function from ListEvent to IndexChangeEvent .
8. Change import mx.events.ListEvent; to import spark.events.IndexChangeEvent; .
9. Replace all <mx:HBox> tags with <s:HGroup> tags.
10. Remove the horizontalGap="0" property from the <s:HGroup> tag that has it.
11. Add the gap="10" property to each <s:HGroup> tag.
12. In the <s:HGroup> containing the newButton and deleteButton buttons, set gap="2" .
13. Replace the <mx:VBox> tag with a <s:NavigatorContent> tag.
14. Add the following immediately after the opening <s:NavigatorContent> tag, because it defaults to BasicLayout, and you want its children to have vertical layout:

15. Replace the <mx:Canvas> tags with a <s:NavigatorContent> tag.

Note: Do not add the layout tag inside this instance of <s:NavigatorContent> , because in this case it is replacing a Canvas, which uses BasicLayout.

16. Replace all <mx:Label> tags with <s:Label> .

Note: If you build the project now, you will see three warnings because the Spark Label control does not support data binding to its text property. You can ignore these warnings.

17. Add the following to all <s:Label> tags:

These attributes ensure the application's Label components look like their counterparts in the Flex 3 version.

18. Replace all <mx:TextInput> tags with <s:TextInput> tags.
19. Add the following to all <s:TextInput> tags:

20. Replace the <mx:TextArea> tag with a <s:TextArea> tag.
21. Add the following to the <s:TextArea> tag:

22. Replace all <mx:Button> tags with <s:Button> tags.
23. Add fontSize="10" fontWeight="bold" fontFamily="verdana" only to <s:Button> tags that have the label property defined.
24. Add fontSize="10" fontFamily="verdana" to the <mx:DateField> tag.

The Spark DataGrid, new to Flex 4.5, requires several changes when migrating the Dashboard application.

25. Replace the <mx:DataGrid> tag with a <s:DataGrid> tag.
26. Add fontSize="10" fontFamily="verdana" to the <s:DataGrid> tag.
27. Change the namespace prefix for the <mx:columns> tag to s .
28. Replace the <mx:DataGridColumn> tags with <s:GridColumn> tags.
29. In the <s:DataGrid> tag, change the itemClick event to a gridClick event.
30. Replace this:

With this:

30. Change the itemDoubleClick event to a gridDoubleClick event.
31. Replace this:

With this:

31. Because the Spark DataGrid control deals with its data in a slightly different way, you need to add an <s:ArrayList> tag just after the opening <s:columns> tag, and add an </s:ArrayList> tag just before the closing </s:columns> tag.
32. In the second <s:GridColumn> tag, change rendererIsEditor="true" to rendererIsEditable="true" .
33. Because Spark DataGrid columns do not set their default width exactly like MX DataGrid columns, you need to add width="80" to the first and second <s:GridColumn> tags to set the initial width of the columns.
34. In the formatDate() method, change the data type of the second parameter from DataGridColumn to GridColumn :
35. Toward the top of the file, remove the following line as it is no longer necessary:

Next you'll create two custom button skin classes for the left and right buttons, which enable the user to move through the data items. These skins will implement the leftArrowButton and rightArrowButton styles in file styles.css.

36. Create two copies of CustomMinimizeButtonSkin.mxml and rename them CustomLeftButtonSkin.mxml and CustomRightButtonSkin.mxml respectively.
37. To use these custom skin classes in FormContent.mxml, locate the buttons that have styleName="leftArrowButton" and styleName="rightArrowButton" respectively. Remove the width , height , and styleName properties, and set the skinClass properties for the buttons as follows:

38. Save your changes to FormContent.mxml.
39. Open CustomLeftButtonSkin.mxml, and replace the two BitmapImage elements with the following three tags:

40. Open CustomRightButtonSkin.mxml, and replace the two BitmapImage elements with the following three tags:

41. Save your changes.

In this section you'll update the ListContent component.

1. To begin, open ListContent.mxml replace the namespace definitions as you did for ChartContent.mxml.
2. Change the namespace prefix for the <mx:Script> tag to fx .
3. Replace import mx.controls.Label; with import spark.components.Label; .
4. Replace <mx:List … /> with <s:List … > . (Remember to remove the slash before the closing angle bracket.)
5. Replace borderStyle="none" with borderVisible="false" in the <s:List> tag.
6. Add fontSize="11" in the <s:List> tag.
7. Add a closing </s:List> tag.
8. Add the following between the opening <s:List> tag and the closing </s:List> tag:

9. Save your changes.

Your <s:List> tag should now be similar to the following:

The Flex 3 Dashboard ListContent component displays only a vertical scrollbar, and does not display a horizontal scrollbar. It achieves this by setting the horizontalScrollPolicy property in the custom item renderer for the ListContent List subcomponent to "off" . To remove the horizontal scrollbar in the Flex 4.5 it is necessary to create a custom skin class for the ListContent List subcomponent.

The custom skin will also be used to remove the border from the List control.

1. Right-click the skins folder in Package Explorer and select New > MXML Skin.
2. Type CustomListSkin for the name and select spark.components.List as the Host Component.
3. Verify that the Create As Copy Of setting is spark.skins.spark.ListSkin, and select Remove ActionScript Styling Code.
4. Click Finish.
5. To use this skin class, set the skinClass property for the <s:List> tag in ListContent.mxml:

6. In this custom skin file, set the alpha property of the borderStroke SolidColorStroke to a value of 0 , to remove the List border:

7. Set the horizontalScrollPolicy property of the Scroller subcomponent in the skin class to "off" to remove the horizontal scroll bar:

8. Save your changes.

In this section, you'll update the ListPodRenderer, which is used to render list items in the ListContent component.

1. To begin, open src/com/esria/samples/dashboard/renderers/ListPodRenderer.mxml and replace the namespace definitions as you did for ChartContent.mxml.
2. Change the namespace prefix for the <mx:Script> tag to fx .
3. Replace <mx:HBox> with <s:ItemRenderer> .
4. Remove the backgroundColor and horizontalScrollPolicy properties from the ItemRenderer tag, as they are not supported by the ItemRenderer class.
5. Add the following immediately following the opening <s:ItemRenderer> tag:

6. Add the following immediately following the closing </s:layout> tag:

7. Add the following lines to the onInitialize() function:

8. Replace <mx:Label> with <s:Label> throughout.
9. Remove the truncateToFit="true" property from the final Label, as it is unnecessary.
10. Add the following in the <s:Label> tags:

11. In the nameLabel <s:Label> , replace rollOver="Label(event.currentTarget).setStyle('textDecoration', 'none');" with textDecoration.over="none" .
12. In the same <s:Label> tag, remove this:

13. Save your changes and build the project.

If you launch the Dashboard and click the links in the Company News, a new browser window opens but the page fails to load, because www.esria.com no longer exists.

Follow these steps to fix this:

1. Open data/news.xml.
2. Replace all occurrences of www.esria.com with www.adobe.com.
3. Save your changes.
4. Launch the completed application and try it out!

That's it! You've finished porting the Adobe Flex 3 example Dashboard application to use the Flex 4.5 Spark controls and architecture.

It's important to note that the resulting application is not necessarily coded as it would be if you were to develop the Dashboard from scratch using Flex 4.5. Rather, the goal of the exercise was to migrate an existing application from Flex 3 to Flex 4.5, while changing as little as possible. Now that that has been achieved, you may want to look for opportunities to improve the overall quality of the Flex 4.5 Dashboard and its application architecture.

In fact, the best way to learn even more about the Dashboard application is to think of things it does not do, or limitations or problems you see in the Dashboard, and then try to understand and modify the code. Just remember to periodically export your project to an archive folder just in case you need to revert to an earlier version.

For more information on Flex 4.5—and in particular features relevant to the Dashboard application—see the following resources:

For more information on Flex 4.5—and in particular features relevant to the Dashboard application—see the following resources:

• Flex 4.5 Help - Introduction to Charts
• Flex 4.5 Help - Drilling Down into Data
• Flex 4.5 Help - Drag and Drop
• Flex Developer Center - Introducing Adobe Flex 4.5 SDK
• Flex in a Week video training (free)

Note: You may use the sample code in your products, commercial or not.