Migrating Flex 3 applications to Flex 4.5 – Part 1: Importing the Flex 3 Dashboard application into Flash Builder 4.5

This article is Part 1 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, the latest version of Adobe's IDE for developing applications for the Flash platform, 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 convert the Dashboard application to a mobile application. A future article series will cover creating a mobile Dashboard application.

I really love the Flex 3 Dashboard application. It's a great showcase for some compelling uses of Flex, including presenting data in charts, grids, and forms, as well as in pods that can be dragged around the UI. It's also a great starting point for incorporating some engaging Flex functionality into your own applications.

Flash Builder 4.5 ships with both the Flex 3.x SDK and the Flex 4.x SDK. While you could continue developing Flex 3 applications in Flash Builder, there are clear advantages to moving to Flex 4.x. First, the compiler is faster. Second, the new Spark component architecture, together with the new skinning and states model, is a significant improvement. When you consider the other new features available as well, using the Flex 4.x SDK is the clear choice.

Part 1 of the series (this article) describes how to import the Flex 3 Dashboard into Flash Builder 4.5 while changing as little as possible. The Flex 4.x SDK ships with a new compiler, so importing the Dashboard requires a few additional steps.

This article series does not attempt to improve the overall quality of the Dashboard application architecture. The goal is simply to provide an example of modifying an application created in Flex 3 to use Flex 4.5—and provide enough information to help you migrate your own Flex 3 applications to Flex 4.5.

Here are some of the Flex 4.5 and general Flex topics that are covered in this series:

• Differences in namespaces between Flex 3 and Flex 4.5
• Significant differences in the Flex 4.5 Spark layout scheme
• Significant differences in the Flex 4.5 Spark skinning model
• Creating and editing custom component skins, including states in skins
• Moving CSS styles into custom skins
• Adapting Flex 3 applications to use Flex 4.5 containers and controls

To try out the Dashboard application, visit the Flex 3 Dashboard page and click the Experience The Application link.

To complete this article series you need Flash Builder 4.5 installed. You can buy Flash Builder 4.5, or download the trial version.

Downloading the Dashboard source files

To download the Dashboard source file ZIP archive:

1. Visit the Dashboard source page.
2. Click the Download Source link in the lower-left corner of the page. You do not need to download the Flex 3 SDK.

When you import the Dashboard project, you must also select the Flex SDK version for the project. This section describes these two steps.

Importing from the ZIP file or a project folder

There are two ways import the Dashboard application project in Flash Builder. You can import the project after extracting the contents of the ZIP file to a directory, or you can import directly from the Dashboard.zip archive file (see Figure 1). You may use either method.

Follow these steps to import from the ZIP file:

1. Choose File > Import in Flash Builder 4.5.
2. Select Flash Builder > Flash Builder Project for the import source, then click Next.
3. In the Import Flash Builder Project dialog box, select File and click the Browse button.
4. Navigate to the folder containing the Dashboard.zip file.
5. Select the file and click Open.
6. Back in the Import Flex Project dialog box, click Finish.
7. If you import from the ZIP project archive file and you see a message that says the project will be upgraded (see Figure 2), just click OK.

Selecting the Flex SDK version

You will be prompted to choose which Flex SDK will be used to compile the project (see Figure 3). You can select the Flex SDK 4.5 that ships with Flash Builder 4.5, or you can select a more recent version of the Flex SDK if one is available.

Note: The steps in this article were tested using Flex SDK 4.5 and Flex SDK 4.5.1. When using a more recent SDK version you may encounter problems as you follow this four-part article series if there are API differences between Flex SDK 4.5.1 and the SDK you are using.

1. If you installed a more recent version of the Flex SDK for this tutorial, you'll need to click the Configure Flex SDKs link to add it as an option.
2. If your default SDK is not Flex 4.5, select Use A Specific SDK and select the Flex 4.5 SDK.
3. Ensure the Use Flex 3 Compatibility Mode option is not selected, because you will be migrating the Dashboard application to Flex 4.5.
4. Click OK.

5. After the import process completes, expand the Dashboard project and its src folder in the Package Explorer view (see Figure 4) to see the imported folders and files.

Note: After you have imported the Flex 3 Dashboard application into Flash Builder you may want to save the imported but unchanged project files to another location for reference.

Following a successful import of the project, you will need to make several code changes to correct for differences between the Flex 3 SDK and Flex 4.5 SDK.

Note: Some errors mentioned later in this article will not be displayed until the first few errors have been addressed, so you may not see them yet.

Adding an empty libs folder

If you try to build the project (by choosing Project > Build All) the first error you'll see notes that the libs folder is missing (see Figure 5).

The libs folder is created automatically by Flash Builder for new projects, but for imported projects that do not contain a libs folder, the folder must be created manually:

1. Right-click the project's top-level folder Dashboard in the Package Explorer view and select New > Folder.
2. Type libs as the folder name.
3. Click Finish.

The folder can remain empty (see Figure 6) but it must exist to remove the error.

Addressing a new error and warnings

After adding the libs folder, build the project again. The error for the missing folder will be gone, but you will have a new error and several warnings (see Figure 7). The next few steps eliminate this new error and new errors as they occur. After you reach a point when all errors have been fixed you will address the multiple warnings.

Removing the backgroundSize style property from the Application container

To fix the error:

1. Double-click the error to open main.mxml and position the cursor at the line causing the error.
2. Remove the backgroundSize style property from the <mx:Application> tag.
3. Rebuild the project.

You will now see two new errors (see Figure 8), which you will fix before you address the warnings.

Addressing the IStroke and IFill interface changes

The two new errors for incorrect number of arguments are due to API changes introduced in Flex 3.5 SDK (the Dashboard application was originally created using an earlier version of the Flex 3 SDK, before the Flex 3.5 SDK was released). The changes involve the IStroke and IFill interfaces. The problem is that the number of arguments passed to two methods defined in these interfaces has changed.

To fix the errors follow these steps:

1. Double-click the first error to open RollOverBoxItemRenderer.as and position the cursor at the line causing the error:

This first error occurs because the IStroke interface method apply() , which prior to Flex 3.5 took a single argument, now takes three arguments.

Flex 3.4 and earlier:

Flex 3.5 and Flex 4.5:

2. Replace stroke.apply(g); with stroke.apply(g, rc, new Point(rc.left,rc.top)); .
3. Add the following line to the top of the file with the other import statements if it is not already present:

4. Save your changes and rebuild the project. Only the second error will remain.
5. Double-click the remaining error in the Problems view to open RollOverWedgeItemRenderer.as and position the cursor at the line causing the error:

This error occurs because the IFill interface method begin() , which prior to Flex 3.5 took two arguments, now takes three arguments.

Flex 3.4 and earlier:

Flex 3.5 and Flex 4.5:

6. Replace the line f.begin(g,rc); with f.begin(g,rc, new Point(rc.left,rc.top)); to resolve the error.
7. Save your changes and rebuild the project. You will now see one new error (see Figure 9).

Eliminating the themeColor style error

The themeColor style was removed in the Spark skins, so you'll need to remove it as you migrate to Spark and Flex 4.5.

1. Double-click the error to open src/com/esria/samples/dashboard/view/ListContent.mxml and position the cursor at the line causing the error.
2. Remove the themeColor style property from the <mx:List> tag.
3. Save your changes and rebuild the project. You now see an error related to the project HTML wrapper (see Figure 10).

Fixing the HTML wrapper error

This next error to fix indicates that Flash Builder cannot create the HTML wrapper. The error occurs because the HTML templates were updated in Flex 4.5 to take advantage of SWFObject, which provides a more reliable way to do Flash Player detection.

This error is simple to fix:

1. Right-click the error message and select Recreate HTML Templates.
2. Rebuild the project.
3. Verify that no errors are reported in the Problems view.

Eliminate warnings by removing the Style tag

To eliminate most of the warnings, follow these steps:

1. Open the main application file, main.mxml.
2. Remove the <mx:Style> tag (near line 14):

3. Save your changes and rebuild the project.

The styles handled by this tag will be implemented in various custom skins in the later parts of this series. Do not delete the styles.css file as you will refer to it while creating the custom skins.

Eliminate warnings related to differences in accessing top-level application objects

The two remaining warnings occur because in the Flex 4.x SDK you reference top-level application objects and methods differently than with the Flex 3 SDK. Instead of using the mx.core.Application class (for example, Application.application.MY_TOP_VAR_OR_METHOD ) as you would in Flex 3, in Flex 4.5 you use the mx.core.FlexGlobals class (for example, FlexGlobals.topLevelApplication.MY_TOP_VAR_OR_METHOD ).

To eliminate the two warnings, follow these steps:

1. Double-click the first warning to open the relevant source code file and position the cursor on the line of code that is causing the warning.
2. Replace Application.application with FlexGlobals.topLevelApplication .
3. Repeat steps 1 and 2 for the second warning.
4. Save your changes.
5. If you see two new errors for access of an undefined property FlexGlobals , replace the following line at the top of PodLayoutManager.as near the other import statements:
6. replace this:

with this:

After making these changes and rebuilding you should have no errors or warnings.

Note: After you have resolved all the errors with the imported Flex 3 Dashboard application into Flash Builder you may want to save the project files to another location for reference.

Now that you've resolved all the build errors, you can launch the Dashboard application in Flash Builder 4 by choosing Run > Run or by pressing Ctrl+F11 (see Figure 11).

Note: If the application does not launch, you may need to install Flash Player 10.2. You can download Flash Player 10.2 here. If you have problems installing Flash Player 10.2, because you are told a newer version of the Flash Player is available, use the uninstall_flash_player.exe available here.

This article illustrated how to import the Flex Developer Center Dashboard demonstration application, which was written using the Flex 3 SDK, into Flash Builder 4.5, as the first step to migrating the application to Flex 4.5.

Now that you have imported the Dashboard project and resolved the initial errors that cropped up when switching to the Flex 4.5 SDK, you can proceed to Part 2 of this series and begin migrating the application to Flex 4.5.

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.