Migrating Flex 3 applications to Flex 4.5 – Part 2: Beginning migration of the Dashboard application to Flex 4.5

This article is Part 2 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.

Part 1 of this series described how to import the Flex 3 Dashboard into Flash Builder 4.5 and make just enough changes to get it to compile and run. Part 2 of the series (this article) begins the process of migrating the Dashboard code to Flex 4.5.

Before you complete Part 2, you must complete the steps in Part 1. Alternatively, you can download the Dashboard-Part2-Start.zip sample file, unzip it, import it into Flash Builder, and continue from there. The other sample file for this article, Dashboard-Part2-End.zip, contains a project in which all the steps in Part 2 have already been completed. You may use this project as a reference if you wish.

Note: The Flex 3 Dashboard application hosted on the Adobe examples site does not display exactly the same (see Figure 1) as it will if you download the source code and compile it using Flex 3 (and the Flex 3.4 SDK). In this article series, you will migrate the Dashboard application to Flex 4.5 so it displays as it does when you compile it using Flex 3, not as it displays as hosted on the Adobe examples site.

The Dashboard application saves information on the location and the state of each pod to a Flex SharedObject, which is a similar concept to using cookies on a web page. As you go through the process of converting the Dashboard application to Flex 4.5, you may change the position of pods within the Dashboard, minimize or maximize pods, and so on. Runtime errors can also cause an unstable state to be saved in the SharedObject. In either case, you may need to reset the Dashboard to its initial state before continuing. You can do this by deleting the SharedObject file on your machine. The location of this file depends on the operating system you are using:

• On Windows 95/98/ME/2000/XP the file is at c:/Documents and Settings/username/Application Data/Macromedia/Flash Player/#SharedObjects
• On Windows Vista and Windows 7 it is at c:/Users/username/AppData/Roaming/Macromedia/FlashPlayer/#SharedObjects
• On Mac OS X it is at /Users/username/Library/Preferences/Macromedia/FlashPlayer/#SharedObjects/web_domain/path_to_application/application_name/object_name.sol
• On Linux/Unix it is at /home/username/.macromedia/Flash_Player/#SharedObjects/web_domain/path_to_application/application_name/object_name.sol

The Dashboard is a nontrivial application with code in 19 files (not including data and image files). The scope of the application presents a challenge in guiding you through the many changes required to migrate the Dashboard to Flex 4.5.

The general approach for the code conversion is to start with the top application object and proceed down through the various levels of the container hierarchy. However, changes in one file often make it necessary to make changes in other files to avoid errors and still be able to launch the application.

One goal of the approach followed in this series is to maintain the application, as much as possible, in a state in which it can be launched with no errors (warnings are acceptable).

Some sections include numerous steps for converting code, and missing or improperly applying one step can make it difficult to proceed. Take your time, read each step carefully, and keep these tips in mind:

• When replacing one MXML tag with another, replace only the tag name and namespace prefix, not the entire tag, unless the instructions indicate otherwise.
• Many steps are repeated in multiple files throughout this article series, so subsequent instructions may simplify or summarize steps you have already performed.
• The reference point for steps will often be a function name, the id of an MXML tag, or more generalized text such as, "near the top of the file".

You'll start with some basic changes to the main application file, main.mxml.

Changes to use the Spark Application container

In main.mxml begin by changing the namespace prefix in the opening and closing Application tags from mx to s , to use the new Spark application class.

1. Change <mx:Application to <s:Application and change </mx:Application> to </s:Application> .

Next, replace the one Flex 3 namespace definition with the three Flex 4.5 namespace definitions in the opening Application tag.

2. Replace xmlns:mx="/2006/mxml" with the following lines:

Script tag namespace prefix change

3. Change the namespace prefix in the <mx:Script> tag to use the Flex 4.5 fx namespace instead of the mx namespace.
4. Update the closing tag as well by changing </mx:Script> to </fx:Script> .

Specify VerticalLayout in the Application container

The Flex 3 Dashboard <mx:Application> tag defaults to vertical layout, but the Flex 4.5 Spark <s:Application> tag defaults to BasicLayout (the Flex 4.5 equivalent of absolute layout). You'll need to specify a vertical layout for the Application container.

5. Add the following code in main.mxml just before the <mx:TabBar> component:

1. Save your changes
2. Build and run the application.

The Dashboard application should compile with no errors and launch. Compared with the Flex 3 version, the application has some display issues, such as the background image not displaying (see Figure 2), but these will be eliminated as you continue to migrate the application to Flex 4.5.

You can see other differences when you compare the application with the Flex 3 version (see Figure 3).

Now that you've updated the main Application container and the namespaces, the next step is to implement a custom skin for the Application container.

The custom skin you implement will restore the Application container background image.

1. First create a new folder named skins for custom skins. Right-click the src folder in the Package Explorer, select New > Folder, type skins as the Folder Name, and click Finish. It should be at the same level as the default package (see Figure 4).

Next, you'll create the skin.

2. Right-click the skins folder and select New > MXML Skin.
3. In the New MXML Skin dialog box, type CustomApplicationSkin as the Name and spark.components.Application as the Host Component.
4. Select Create As Copy Of and verify that the copy will be made from spark.skins.spark.ApplicationSkin.
5. Select Remove ActionScript Styling Code (see Figure 5).

9. Click Finish.

Flash Builder will create a new file named CustomApplicationSkin.mxml in the src/skins folder.

10. To use this custom skin class, which you have not modified yet, add the following to the <s:Application> tag at the top of file main.mxml:

Next you'll modify the skin class to implement styles previously defined in styles.css, and also the backgroundSize style property you removed in Part 1. You may want to refer to the Application type selector in assets/styles.css, as its styles will be implemented in the skin. CSS styles are not used in Flex 4.5 as they are in Flex 3 because the Spark architecture strives to provide a cleaner separation of a component's visual elements from its logic.

11. To implement the background image in the skin, open file skins/CustomApplicationSkin.mxml and locate the Rect tag with the id backgroundRect . Replace the entire Rect tag and its contents with the following BitmapImage tag:

12. Save your changes and rebuild the project.

Notice that this skin sets the top , bottom , left , and right constraint properties to 0 , which causes the image to fill the entire application background and fulfills the role of the backgroundSize style property removed from the <mx:Application> tag.

The background-color and background-gradient-colors styles in styles.css (and the Application tag) are unnecessary because the default Flex 4.5 Spark application background is white. The color style in styles.css is likewise unnecessary, because the default text color for the application is black.

Launch the application and you will see the background image applied to the application as it was for the Flex 3 Dashboard application (see Figure 6).

Next you'll make changes to use the new Flex 4.5 Spark TabBar.

Make the following changes in main.mxml:

1. Change the namespace prefix of the TabBar component tag to use the Spark s namespace prefix instead of the mx prefix.
2. Enclose the TabBar dataProvider value in binding curly braces: {viewStack} .
3. Edit the TabBar to respond to the change event instead of to the itemClick event.

After completing these steps, the TabBar tag should look similar to this:

Now you need to make additional changes that are necessary because the Spark TabBar control dispatches a different event when the selected tab is changed.

4. Locate the following event import at the top of main.mxml:

5. Replace it with this:

6. Search for the definition of the onItemClickTabBar() function in main.mxml and in the function signature, replace ItemClickEvent with IndexChangeEvent :

7. Within the function definition, change e.index to e.newIndex because the IndexChangeEvent provides access to the clicked tab through a different property.
8. Locate the following line of code just above the onItemClickTabBar() function definition (near the bottom of the onResultHttpService() function definition).

9. Change this line to:

This change is necessary because the code creates an event instance to simulate clicking a tab when the application is first launched.

10. Save your changes and build the application.

It should compile with no errors. Launch the application and click on its tabs to ensure they still work.

This section and the next implement two custom skins so the tabs in the TabBar component display as they do in the Flex 3 Dashboard application. The skin in this section is for the TabBar component, and the skin in the next section is for the ButtonBarButton components making up the tabs.

To create the TabBar custom skin, follow these steps:

1. Right-click the skins folder in the Package Explorer and select New > MXML Skin.
2. For the name, type CustomTabBarSkin, and for the Host Component, type spark.components.TabBar.
3. Verify the Create As Copy Of value is set to spark.skins.spark.TabBarSkin and the option is selected.
4. Select Remove ActionScript Styling Code.
5. Click Finish.

Flash Builder will create a new file named CustomTabBarSkin.mxml in the src/skins folder.

6. To use this custom skin class, which you have not modified yet, add the following to the <s:TabBar> tag at the bottom of the main.mxml file:

7. In the skin file (CustomTabBarSkin.mxml), add focusThickness="0" to the <s:ButtonBarButton> tag, so the tabs do not display a focus border when leaving and returning to the Dashboard window:

8. Save your changes.

In this section you'll create a custom skin for the ButtonBarButton components that make up the tabs. There are more steps to creating this skin, so follow along carefully.

1. Right-click the skins folder, and select New > MXML Skin.
2. For the Name type CustomButtonBarButtonSkin, and for the Host Component, type spark.components.ButtonBarButton.
3. Select Create As Copy Of and type spark.skins.spark.TabBarButtonSkin. Note that unlike the other skins you've created thus far, this is not the default supplied by Flash Builder (ButtonSkin).
4. Also unlike the earlier skins, deselect Remove ActionScript Styling Code.
5. Click Finish.

Flash Builder will create CustomButtonBarButtonSkin.mxml in the src/skins folder.

6. To use this custom skin class, open skins/CustomTabBarSkin.mxml, and in the <s:ButtonBarButton> tag at the bottom of the file replace spark.skins.spark.TabBarButtonSkin with skins.CustomButtonBarButtonSkin .

The tag will now be:

Next you'll apply some of the more general styles that were defined in styles.css, specifically the tabBarButton and tabBarButtonSelected class selectors.

7. Open CustomButtonBarButtonSkin.mxml
8. In the labelDisplay Label change the textAlign property value from center to left .
9. Implement the padding styles using the labelDisplay properties left , right , and top style properties. Keep the left property value at 10 , but change right to 20 , and change top to -4 .
10. Add the following style properties to the labelDisplay Label tag:

11. Add fontWeight="bold" to the same tag. The Flex 3 Label control text is bold by default, but in Flex 4.5 the default fontWeight is "normal" .

The next three general style properties require an explanation. In the tabBarButton style in styles.css, the text-roll-over-color property represents the tab text color when the pointer hovers over an unselected tab. In the tabBarButtonSelected style, the text-roll-over-color property represents the tab text color when the pointer hovers over a tab that is selected, and the color property represents the text color when the pointer is not hovering over a selected tab. Although the text-roll-over-color style property is used twice here, it is used in two different styles, so there is no conflict.

12. To achieve the same goal in the CustomButtonBarButtonSkin, add the following three skin state style property settings to the labelDisplay Label (this is an example of the new MXML states syntax at work):

The labelDisplay Label tag should now look similar to the following:

Lastly you need to apply the six graphic image styles for the actual tab display. Actually, only two individual images are used, one for the up , over , and down states of unselected tabs, and another for the up , over , and down states of the currently selected tab.

13. First, delete all the code in the CustomButtonBarButtonSkin <fx:Script> tag except the following lines, which should remain:

14. Next, delete all of the graphical content up to and including layer 7. Basically you'll delete everything from just after the </s:states> closing tag to the end of layer 7. Layer 8, which contains the labelDisplay Label, will remain.
15. Add the following code just before the layer 8 labelDisplay element. This adds two <s:BitmapImage> components, one for each of the tab images.

Notice the use of the includeIn property, which allows you to specify the states for which each image should display. Also notice that the width is set using binding to a variable named labelDisplayWidth ; this is necessary so the TabBar tabs adjust their size as appropriate for the text of each tab.

16. Add the following code to declare the labelDisplayWidth variable and a method to set its value at the beginning of the <fx:Script> tag:

Note: The labelDisplay skin part has a type of IDisplayText, so you need to cast it as Label in the skin ActionScript code.

17. Finally, add the following code to the end of the <s:Label id="labelDisplay"> tag:

18. Save your changes and build the application.

When you launch the application, you'll see that the tab text is not positioned exactly as it was for the Flex 3 Dashboard application. In the Flex 4.5 Dashboard, the text is slightly lower than in the Flex 3 Dashboard (see Figure 7).

19. To correct this minor difference, modify the contents of the <s:states> tag as follows:

20. Next, delete the horizontalCenter and verticalCenter properties of the labelDisplay tag, change the left property to 12 , and replace the top property with top.selectedStates="0" top.nonSelected="-2" so the labelDisplay Label tag is similar to the following:

These changes specify a different position for the tab label when the tab is selected.

21. Save your changes and rebuild the project.

You are done with skinning the TabBar. The tabs should display as they do in the Flex 3 Dashboard, even when you hover over the tabs.

You've now completed Part 2 of this four-part series, which included the first code changes to migrate the Flex 4.5 Spark controls and architecture. In Part 3, you'll make the changes needed to have the application's ViewStack use the new Flex 4.5 Spark NavigatorContent container.

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.