Richard Leggett on New Media

This article is about creating Flex Gumbo (Flex 4) application that run in either Flash Player 10, or AIR 1.5. I also describe how to upgrade an existing FP9/AIR 1.0 application to use the new SDK. In my case I also had to upgrade a Flex Library project so that’s also covered.

Word of warning: before you jump in please refer to the section entitled “Problem: Losing Syntax Highlighting in Script Tag” near the end. As this could affect you if you make use of Script tags rather than the “code-behind” technique (I now use the former strategy to save on files and promote simpler View classes).

Why use Gumbo?

Follow up:

It’s important to note here that we’re changing the SDK being used, not just the Flash player version. You can happily target Flash Player 10 and AIR 1.5 with the standard Flex 3.2 SDK, you just don’t get the new SDK stuff but you do get goodies like unloadAndStop(). If that’s for you, some of these instructions are still relevant (See Upgrade a Flex Project).

With that said, Gumbo (Flex 4) provides a whole raft of improvements, from FXG (graphics markup), Bi-Di text (a requirement for me), CSS improvements, to a whole new component set dubbed “Spark” which aim to be far easier to skin. There’s still a lot of decisions going on about how Spark will be named so that it doesn’t conflict with the existing Flex 3 “Halo” components as there is obviously a huge overlap, right now Spark components are prefixed with “Fx” e.g. “FxButton” (- UPDATE: Via Ryan Stewart’s twitter, “Fx” is no more, instead a dual/tri namespace solution will be used). In my case I’ve built this application using the Halo components already but plan to migrate to Spark over time.

Pre-requisites

First thing’s first, if you want to target Gumbo, you’ll need to download the Flex Gumbo SDK, add this to your choice of SDKs in the Flex Builder “Installed Flex SDKs” window available in the Preferences dialog. For simplicity, I’m assuming you’ve set the new SDK as your default one. The screenshot below shows this setup (click to enlarge).

Name-spaces

One of the most confusing aspects of the changes from Flex 3 to 4 is with the namespaces. The new Flex 4 namespace is “http://ns.adobe.com/mxml/2009″, and this is merely a unique string that essentially “points” the compiler to a manifest file which is an XML file listing the available tags. However unlike in Flex 3, this namespace doesn’t contain everything you will need, such as the UI controls, like the Button, the Application and so on, it just contains the core types like Array and uint. In Flex 4 you’ll also need to specify a controls namespace, either Spark ("library://ns.adobe.com/flex/spark") or Halo ("library://ns.adobe.com/flex/halo” which is for legacy Flex 2 or 3 applications.

If you want to see what these manifest files contain, you can actually open up these manifest files, they are found in FlexSDK_Install/frameworks/mxml-XYZ-manifest.xml to see what’s included yourself. You’ll find the old mxml-manifest (mx), mxml-2009-manifest, spark-manifest, halo-manifest and also fxg-manifest which contains graphics tags.

The Flex 2/3 Halo namespace was “http://www.adobe.com/2006/mxml", and you’d almost always see it mapped to the “mx” prefix. For example:


<Application xmlns:mx="xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
<mx:Button label="Hello World" />
</mx:Application>


For a Flex 4/Gumbo project you will likely see the MXML 2009 namespace along with the one for new Spark controls:


<s:Application xmlns="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" >
<s:Button label="Hello World" />
</s:Application>


Notice how in this case I’ve missed out the “mx” and mapped it directly to the default namespace, hopefully that’s the way things go, no need for an extraneous prefix. Of course you can mix and match components from both sets (and indeed must at present to get a full set). A project that mixes Gumbo components with Halo would then look like:


<s:Application xmlns="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/halo" >
<s:layout>
<s:VerticalLayout />
</s:layout>

<s:Button label="New school" />
<mx:Button label="Old school button" />
</Application>


Upgrade a Flex Library Project

I’m using a Flex Library project to build a SWC that contains the core code used in my application, and also several other applications. My project consists of an AIR application, a Flex deployable version of that, and a Zinc 3 helper application, these all share this code library. This step applies just the same to a regular Flex project.

In FlexBuilder, click on the arrow icon in the Flex Project explorer, and turn off the filter that hides files who’s name begins with a dot (see image).

Now find the “.actionScriptProperties” file, and inside that the compiler tag. You’ll see a value for “htmlPlayerVersion", probably set to 9.0.28. This value is used when compiling even if you’re making an AIR application, so set it to:

htmlPlayerVersion="10.0.0"

This will now target Flash Player 10, which will rid you of any errors like: “1046: Type was not found or was not a compile-time constant: Matrix3D.” and allow you to access all the new FP10 features like z, rotationZ etc.

Upgrade an AIR application

For AIR, repeat what you did above for the Flex app in order to target FP10, and then all you need to do is change a namespace in your “APPNAME_HERE-app.xml” file, found in your project’s main source folder. It might looks something like:

<application xmlns="http://ns.adobe.com/air/application/1.1">

Change that to:

<application xmlns="http://ns.adobe.com/air/application/1.5">

Your AIR application will now target the AIR 1.5 runtime. Although this generally works, it’s safer to actually copy the new AIR 1.5 app.xml template file from Flex4SDK_Installation/templates/air/descriptor-template.xml and fill out the values afresh because there are some new features that won’t be in your existing AIR 1.X application descriptor.

There were a couple of problems encountered after the upgrade, and I’ll take those in turn here…

Problem: My components are incorrectly styled

First of all. Flex 3 used the “Halo” components where as Flex 4 uses the “Spark” components. To use the Halo component skins you need to set the “theme=halo.swc” (see Joan’s post). If you are using CSS you may also want to set the namespace so that it is recognised for your Halo components (same post). You may alternatively need to add the compiler flag: “-compatibility-version 3″ which reverts to Flex 3 style CSS and so on.

Secondly CSS. CSS now needs @namespace declarations before styles that are to be applied to components in those namespaces (e.g. set the halo namespace before defininf a style for Button).

Problem: New States Syntax

This one wasn’t a huge deal. The States syntax from Flex 3 had been deprecated, but this article shows how to migrate which took just a couple of minutes as I only really used them for the main Application “screens".

Problem: Losing Syntax Highlighting in Script Tag

Unfortunately when you switch to using the Gumbo SDK in Flex Builder 3 it appears to choke on the Script tag. Whilst things compile fine, it no longer syntax highlights/colorises the code, and code completion fails completely. As far as I’m aware, we have to wait to FlexBuilder 4 to have this working unless someone comes up with a workaround, so for now stick with SDK 3.2 unless you have the MAX preview of FB4.)

Conclusion

I’m on a project where I know I will need the features of AIR 1.5.X, FP10 and Gumbo in order to complete all the necessary features so for me this is something I’ll have to do. The good news is it all went smoothly, except the Script tag problem, which for me is going to mean holding off on updating to Spark/MXML2009 until FlexBuilder 4 comes out.

Best of luck playing with Gumbo and please feel free to post and corrections, problems or successes in the comments.

Update:

I have updated this post from time to time as the Flex 4 SDK changes are made. For example at one time component names were prefixed with “Fx” and you only needed to use one namespace (MXML 2009) for everything, not so now, now we have 3 or 4 namespaces in use depending on what tags you are after.

If you are having problems migrating/updating to Flex 4, for example all your Flex 3 Halo components look messed up but it all compiles and runs “ok", be sure to check out Joan Lafferty’s blog which has 4 or 5 posts on this topic. (The problem described here can be fixed by telling the compiler to use the halo.swc skins via the compiler arguments until you can fully migrate to the Spark namespaces and components.)