Requirements

Prerequisite knowledge

You do not need extensive knowledge of Flex 3 or Flex 4 to complete this tutorial, but if you intend to incorporate aspects of the Flex Dashboard application into your own projects, then having a good understanding of Flex 3, and at least a basic understanding of what’s new in Flex 4, is essential.

User level

Beginning

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, the latest version of Adobe’s IDE for developing applications for the Flash platform, and then migrate the application to Flex 4 to take advantage of the Flex 4 Spark architecture and components.

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 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 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—and provide enough information to help you migrate your own Flex 3 applications to Flex 4.

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

  • Differences in namespaces between Flex 3 and Flex 4
  • Significant differences in the Flex 4 Spark layout scheme
  • Significant differences in the Flex 4 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 containers and controls

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

Getting started

To complete this article series you need Flash Builder 4 or Flash Builder 4.0.1 installed. Flash Builder 4.0.1 is preferable, as you need the Flex 4.1 SDK (or a later version if one is available). Version 4.1 of the Flex SDK is necessary because it includes important improvements necessary to avoid run-time errors when launching the Dashboard application.

Getting the Flex 4.1 SDK

If you have Flash Builder 4 and do not yet have the Flex 4.1 SDK, you’ll need to download it (or latest more recent one, if available) and add it to your Flash Builder 4 installation. If you already have Flash Builder 4.0.1, it is not necessary to update the SDK.

Follow these steps to install the Flex 4.1 SDK:

  1. Visit the Flex 4 Downloads page.
  2. In the Latest Milestone Release Builds section, download the latest Adobe Flex SDK and Adobe Add-ons files, but do not download the Open Source Flex SDK file.
  3. After downloading the ZIP files, create a new folder named 4.1 in your Flash Builder 4 sdks folder. On Windows, the path of this folder is typically C:\Program Files\Adobe\Adobe Flash Builder 4\sdks.
  4. Extract the contents of the two ZIP files to the 4.1 folder.

Downloading the Dashboard source files

To get the Dashboard source files simply download the sample file for this article, Dashboard-Part1-Start.zip.

Alternatively you can download the Dashboard source file ZIP archive from the main Flex 3 Dashboard page:

  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.

The other sample file for this article, Dashboard-Part1-End.zip, contains a project in which all the steps in Part 1 have already been completed.  You may use this project as a reference if you wish.

Importing the Dashboard project

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 directly from the Dashboard.zip archive file, or you can import the project after extracting the contents of the ZIP file to a directory (see Figure 1). You may use either method.

Follow these steps to import from the ZIP file:

  1. Choose File > Import Flex Project in Flash Builder 4.
  2. In the Import Flex Project dialog box, select File and click the Browse button to the right.
  3. Navigate to the folder containing the Dashboard.zip file.
  4. Select the file and click Open.
  5. Back in the Import Flex Project dialog box, click Finish.

Selecting the Flex SDK version

After you click Finish, you’ll be prompted to choose which Flex SDK will be used to compile the project (see Figure 2). The Dashboard project requires at least Flex SDK 4.1, or you can select a more recent version of the Flex 4 SDK if one is available.

  1. If you just installed the Flex 4.1 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.1, select Use A Specific SDK and select the Flex 4.1 SDK.
  3. Ensure the Use Flex 3 Compatibility Mode option is not selected, because you will be migrating the Dashboard application to Flex 4.
  4. Click OK.
  1. If you import from the ZIP project archive file and you see a message that says the project will be upgraded (see Figure 3), just click OK.
  1. 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.

Fixing warnings and errors

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.x 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 top-level Flex globals warnings

After adding the libs folder, build the project again. The error for the missing folder will be gone, but you will have two new errors and two warnings (see Figure 7).

The two 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 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, add the following line at the top of PodLayoutManager.as near the other import statements:
import mx.core.FlexGlobals;

After making these two changes and rebuilding the warnings will no longer be present.

Addressing the IStroke and IFill interface changes

The two errors for incorrect number of arguments are due to API changes 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:
stroke.apply(g);

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:

apply(g:Graphics):void

Flex 3.5 and Flex 4:

apply(graphics:Graphics, targetBounds:Rectangle, targetOrigin:Point):void
  1. Replace stroke.apply(g); with stroke.apply(g, rc, new Point(rc.left,rc.top));.
  2. Add the following line to the top of the file with the other import statements if it is not already present:
import flash.geom.Point;
  1. Save your changes and rebuild the project. Only the second error will remain.
  2. Double-click the remaining error in the Problems view to open RollOverWedgeItemRenderer.as and position the cursor at the line causing the error:
f.begin(g,rc);

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:

begin(target:Graphics, rc:Rectangle):void

Flex 3.5 and Flex 4:

begin(target:Graphics, targetBounds:Rectangle, targetOrigin:Point):void
  1. Replace the line f.begin(g,rc); with f.begin(g,rc, new Point(rc.left,rc.top)); to resolve the error.
  2. Save your changes and rebuild the project.

    You should now see two new errors and multiple warnings (see Figure 8). You’ll fix these next.

Removing the Style tag

To eliminate the warnings, follow these steps:

  1. Open the main application file, main.mxml.
  2. Remove the <mx:Style> tag (near line 15):
<mx:Style source="/assets/styles.css" />
  1. 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.

Removing style property settings in the Application container and elsewhere

To fix the remaining two errors follow these steps:

  1. Double-click the first error and then remove the backgroundSize style property from the <mx:Application> tag in main.mxml.
  2. Double-click the second error and then remove the themeColor style property from the <mx:List> tag in src/com/esria/samples/dashboard/view/ListContent.mxml.
  3. Save your changes and rebuild the project.

At this point the most recent warnings and errors have been resolved, but you’ll now see a new error related to the HTML wrapper. You will fix that next.

Fixing the HTML wrapper error

The final error you need to fix indicates that Flash Builder cannot create the HTML wrapper (see Figure 9). This error occurs because the HTML templates were updated in Flex 4 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.

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.

Launching the Dashboard application

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

When the application launches, you’ll notice that the display is very different from the Flex 3 version of the application. One reason for this is because you deleted the <mx:Style> tag, so the application is no longer using the images referenced by the application CSS styles.

Another reason is that the application is now using the Flex 4.1 SDK. The default look and feel of the Flex 3 MX controls has been changed to more closely resemble the look and feel of the new Flex 4 Spark controls, and some properties of the MX controls and containers have changed in Flex 4.

Parts 2 through 4 of this article series lead you through migrating the application to use the Flex 4 Spark controls and containers, as well as the new Spark architecture. By the end of this series, the Dashboard application will be nearly identical to the Flex 3 version.

Where to go from 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, as the first step to migrating the application to Flex 4.

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

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