Prerequisite knowledge

To make the most of this tutorial you’ll need to know how to build applications in Flash Builder and how to apply the Spark skinnable component pattern. Because you’ll spend most of your time for this article in Flash Builder, you don’t need extensive knowledge of Flash Catalyst, but knowing the basics will help.

User level


Adobe Flash Catalyst enables designers to produce high-fidelity component skins, animations, and layouts that can flow directly into production. As a developer, this can improve your productivity by reducing the time you spend transforming UI mock-ups into working code. With Flash Catalyst CS5.5, you can now open and edit the design of a project in Flash Catalyst even after development has started.

This means that Flash Catalyst serves as a visual code editor, and like any visual code editor, it has limitations regarding what can be edited after you change code manually. However, while most visual code editors’ limitations are implicit, Adobe Flash Builder 4.5 features a compatibility checker that explains exactly which parts of your project can be edited in Flash Catalyst and which parts go beyond its current capabilities. This compatibility checker makes the editing experience in Flash Catalyst reliable and predictable.

In this article, you’ll learn:

  • How to run the compatibility checker and understand its results.
  • The main points of the compatibility schema, the formal specification for the compatibility checker.
  • Architectural best practices that help avoid compatibility problems.
  • How to work around some of the major compatibility limitations.

Extending a Flash Catalyst project and understanding compatibility

In this section, you’ll open a sample project, make changes that introduce compatibility problems, and see the impact of those changes in Flash Catalyst.

This sample project was started in Flash Catalyst. For prototypes and small projects, this is a very productive workflow. For larger projects, where more architecture is necessary, it’s better to start in Flash Builder and send specific parts to Flash Catalyst for design work. (To learn how to use Flash Catalyst to build an interactive UI, visit the Flash Catalyst Developer Center.)

Import the project

  1. In Flash Builder, choose Window > Open Perspective > Flash to ensure that the workspace is in the Flash perspective.
  2. Choose Project > Flash Catalyst > Import Flash Catalyst Project.
  3. Click Browse and navigate to DatePlanner1.fxp.
  4. Click Finish.
  5. Open Main.mxml.

This is the code for Plan-A-Date, an application that helps you figure out what to do with that special someone. Try running the application, logging in (any username and password will work), and clicking around to familiarize yourself with it.

Because this project was created in Flash Catalyst, it will automatically be checked for compatibility whenever it is built. To enable this option for other projects, you can go to the project properties, click Flash Catalyst, and select Automatically Run Flash Catalyst Compatibility Checker For This Project.

Add some incompatible code

  1. Find the line <!-- Logo--> in the code (line 100).
  2. Just above that line, type <s:DataGrid includeIn="DatePlan"/>. The DatePlan state will show an outline of all the parts of the date, with start/end times, locations, and prices.
  3. Save the file.

In the Problems panel, you will see a warning (see Figure 1). It doesn’t mean you did anything wrong—it just means you won’t be able to edit this project in Flash Catalyst.

The text of this warning describes why your code is incompatible. For many warnings, if you right-click and select More Information, you’ll be taken to the relevant part of the compatibility schema, which will explain exactly what was expected.

The Type column describes the effect of the compatibility problem. In this case, the problem is Flash Catalyst Project Incompatibility. This is the most severe form of compatibility problem, and it means that Flash Catalyst cannot open the project. Project incompatibilities always appear as Warnings in the Problems view; any other compatibility problem will appear as an Info.

This example illustrates an important point: the limitations of Flash Catalyst are not in any way related to best practices in Flex. You should not feel that you’ve done something wrong just because you’ve introduced a compatibility problem. Think of it this way: all visual code editing tools have limitations with respect to the code they can understand. Flash Catalyst just tells you what they are.

Address the project incompatibility and create a file incompatibility

To address this incompatibility, you can move the incompatible code into its own component, isolating it from the rest of the project.

  1. Choose File > New > MXML Component.
  2. Type DatePlan as the component name and type components as the package.
  3. Click Finish.
  4. In the new code file, add <s:DataGrid/> below the closing tag.
  5. In Main.mxml, replace <s:DataGrid includeIn="DatePlan"/> with <components:DatePlan includeIn="DatePlan"/>.
  6. Save all files.

In the Problems panel, the warning will be gone, and there will be several Infos (see Figure 2).

The first Info has the same message as the warning that is now gone. However, it has a different type: Flash Catalyst File Incompatibility. This means that Flash Catalyst will be able to open your project, but it will not edit the file containing the data grid (DatePlan.mxml). In general, most MXML-related compatibility problems will have the type Flash Catalyst File Incompatibility unless they occur in the main application file, in which case they will have the type Flash Catalyst Project Incompatibility. This is because Flash Catalyst can’t open a project for which the main application is not editable.

Note:There are four other compatibility notices in Figure 2. These simply tell you that unused files were not checked for compatibility. You will use these files later in the tutorial.

Create a design-time data incompatibility

This application contains two List components (the Category list and the Activities list). Because they were created in Flash Catalyst, they have hard-coded dummy data. Once you replace this with real data, the list and its item renderer can still be designed in Flash Catalyst, but the data won’t be editable.

  1. Find the following code in Main.mxml:
<s:List id="categoryList" x="19" y="58" skinClass="components.SimpleList"> <s:ArrayCollection> <fx:String>Dining</fx:String> <fx:String>Music</fx:String> <fx:String>Nightlife</fx:String> <fx:String>Entertainment</fx:String> <fx:String>Outdoors</fx:String> </s:ArrayCollection> </s:List>
  1. Replace it with the following:
<s:List id="categoryList" x="19" y="58" skinClass="components.SimpleList" dataProvider="{ActivitiesService.getAllCategories()}"/>
  1. Save the file.

You will see several new compatibility problems (see Figure 3).

Don’t be alarmed! All of the new problems are of the type Flash Catalyst Design-Time Data Incompatibility. Generally, these can be ignored. They simply tell you that if you select this particular list instance, skin, or item renderer in Flash Catalyst, you won’t be able to edit its data statically. That makes sense—the data is now provided by developer code, so it’s no longer dummy data.

If you want to hide these types of problems, click the triangle icon on the top-right of the Problems panel and select Configure Contents. In the Types tree, expand Flash Catalyst and disable any warnings you want to hide.

Create a skinnable component incompatibility

The single most important best-practice to streamline your design-development workflow is to have a clear contract between design and development. This design-development contract is discussed in more detail later in the tutorial.

One way to cleanly separate the design and development work is to use custom skinnable components. Skinnable components have UI logic and data, but no visual appearance. The new Spark controls in Flex are all skinnable components (which is why you see the skinClass property everywhere in code that was generated by Flash Catalyst), but you can also make your own skinnable components. This section assumes you understand the basic concepts of skinnable components. If you don’t, you may want to check out this page first.

Flash Catalyst enables designers to visually skin some custom skinnable components. The compatibility checker tells you exactly which components can be skinned.

To create a custom skinnable component:

  1. Choose File > New > ActionScript Skinnable Component.
  2. Type ReservationWidget as the component name and skinnableComponents as the package.
  3. Click Finish.
  4. Above the class constructor, add the following line:
[SkinPart(required="true")] public var partySizeCombo:ComboBox;

This declares that a skin for this component must have a ComboBox named partySizeCombo. You may need to add import spark.components.ComboBox;.

  1. Save the file.

You will see a new compatibility problem (see Figure 4).

If your component requires a skin part that is not supported by Flash Catalyst, then Flash Catalyst cannot skin your component. Compatibility problems of the type Flash Catalyst Skinnable Component Incompatibility tell you why your component cannot be skinned in Flash Catalyst.

Try out restricted editing in Flash Catalyst (optional)

If you have Flash Catalyst installed, you can see how the various types of incompatibilities affect the editing experience in Flash Catalyst.

File Incompatibility

  1. In Flash Catalyst, open DatePlanner2.fxp.
  2. In the States panel, click DatePlan.
  3. On the artboard, select the DataGrid. (It’s a small white rectangle. You can also find it under DatePlan in the Layers panel.)

Notice that the component appears (see Figure 5) with a gray shield, an FB icon, and an explanatory message in the HUD (heads-up display). You can move, resize, or change the properties of this component, but you can’t edit its definition by double-clicking.

Design-Time Data Incompatibility

  1. In the States panel, click the Browse state.
  2. In the Tools panel, switch to the direct select tool (click the white arrow).
  3. Select the list under Category in the artboard.

Notice that the Design-Time Data panel explains that you cannot edit the data of this list (see Figure 6).

  1. Double-click the list. You are now editing the List component’s skin.
  2. Double-click the first item that says "[Dynamic]". You are now editing the List component’s item renderer.

Notice that you can edit the design of the skin and item renderer, even though the data is dynamic.

Skinnable Component Incompatibility

  1. In the Breadcrumb Bar (just above the artboard), click DatePlanner2 to jump back to the main application.
  2. In the Tools panel, select the Rectangle tool.
  3. Drag out a rectangle.
  4. In the HUD, choose Choose Component > Skinnable Component.

This one is subtle—the important thing is what you’re not seeing. The dialog box (see Figure 7) shows all the custom skinnable components available for skinning. The list shows Compatible Skinnable Component, but it doesn’t show the reservation widget that you created earlier. Files with Skinnable Component Incompatibilities simply do not appear in this list.

Best practices and workarounds

As mentioned above, the single most important best practice to streamline your design-development workflow is to have a clear contract between design and development. Long before production assets are exchanged, the designers and developers on your team should discuss the different parts of the project, the various components, and their parts (subcomponents) and visual states.

Understanding the Flash Catalyst compatibility schema can help you decide who owns what, which parts will be edited in Flash Builder, and which parts will be edited in Flash Catalyst. However, there are also some simple best practices you can follow.

Best practices for projects

Flash Catalyst can edit Flex Projects and Flex Library Projects. In both cases, the projects must use a specific set of configuration options (generally the same as the defaults in Flash Builder), must use a limited library path, and must conform to some rules around file organization to be editable in Flash Catalyst.

For complex projects that cannot use the default project configuration, organize your project as a main project and a set of library projects (see Figure 8). Put only the code that you want to edit in Flash Catalyst in the library project. Enable Flash Catalyst compatibility checking for the library project, but not for the main project. For a detailed walkthrough, see the Flash Builder documentation.

Best practices for MXML files

Flash Catalyst only supports certain code constructs in MXML. If you break the rules for these constructs in your main application, Flash Catalyst cannot edit your project. If you break them in another MXML file, Flash Catalyst can edit your project, but cannot edit that file.

The rules for MXML files are complex and difficult to navigate when coding by hand. As much as possible, you should use custom skinnable components to separate UI logic from visuals, and avoid editing the visuals (skin files) in Flash Builder. This can dramatically reduce the time to skin simple components (such as buttons, scrollbars, and custom widgets) and medium-complexity components (including panels and dialog boxes). Beyond a certain level of complexity (for example, your whole application or an entire screen), the restrictions often become too onerous, and you will need to make your changes in Flash Builder, the old fashioned way.


Even if you obey all the best practices, you may still find that you cannot edit something in Flash Catalyst, but you’d like to. If all else fails, try the workarounds below. But beware; by working around the compatibility checker, you may sacrifice the reliability of the editing experience in Flash Catalyst.

Problem: The compatibility checker is slowing down compilation times.

Workaround: Deselect Project > Flash Catalyst > Automatically Check Compatibility. To check compatibility once, choose Project > Flash Catalyst > Run Compatibility Checker.

Problem: Flash Catalyst can’t edit server projects.

Workaround 1: If you are using Flash Catalyst on the same machine as Flash Builder, you can choose Project > Flash Catalyst > Edit In Flash Catalyst. In this mode, Flash Catalyst can edit server projects.

Workaround 2: Restructure your project into a main server project and subsidiary Flash Catalyst compatible library projects (see Best practices for projects ).

Problem: Flash Catalyst can’t edit AIR or LiveCycle projects.

Workaround: Restructure your project into a main AIR or LiveCycle project and subsidiary Flash Catalyst compatible library projects (see Best practices for projects ).

Problem: In Flash Catalyst, you want to edit a component that is contained within a managed layout group or incompatible file, and therefore can't be edited by drilling down from the main application.

Workaround 1: Drag an instance of the component from the Library panel, edit it, and then delete the instance.

Workaround 2: Add a new empty state to the main application and drag out instances of each component into that state. Of course, you should delete the state before deployment.

Problem: You import a library into Catalyst and want to edit various components. It's a hassle to drag out instances from the Library panel in order to edit them.

Workaround: Create a custom sampler component that contains an instance of every other component. After dragging out a single instance of this component, you can drill down into any other component.

Problem: You want to set a forbidden component property (such as minWidth), forbidden values (for example, width="nn%"), or forbidden combinations (such as omitting width on a skin root tag).

Workaround: The compatibility checker does not check ActionScript code. Set the values in a creationComplete handler. Remove numeric values by setting them to NaN; remove other types by setting them to null.

Problem: Flash Catalyst can only skin components whose parts are of certain types.

Workaround 1: Make the part a Group. You can put anything you want in a group. If the part you want is a type that can’t be created in Flash Catalyst, add the part in Flash Builder, and then continue editing the skin in Flash Catalyst.

Workaround 2: If you want to use a non-skinnable custom component as a part, you can create a SkinnableComponent subclass that has no states, no parts, and no code. Make as many different skins as you like, for use in different places in your project.

Problem: You can't put an ID on some tags and maintain compatibility.

Workaround: In ActionScript code, you can get to the tag in other ways. For example, to access the fill color of a rectangle, use myRect.fill.color. To access all the children of a group, you can iterate using myGroup.numElements and myGroup.getElementAt().

Problem: Skins must have <skin> as their root tag to ensure compatibility; you want to use a subclass of Skin so you can share functionality or graphics between skins.

Workaround 1: Consider putting the shared functionality into your SkinnableComponent instead.

Workaround 2: Put the shared functionality or graphics into a custom component, and then put an instance of this component into each skin. If needed, write some ActionScript glue code to communicate between this helper and the skin.

Where to go from here

In this tutorial, you learned about the Flash Catalyst compatibility checker. You also learned about the various levels of compatibility and how they manifest within Flash Catalyst. Finally, you learned about the importance of a design-development contract, best practices to help clarify that contract, and some workarounds for common compatibility problems.

If you want to learn how to build your own custom skinnable components, check out this page.

If you want to learn how to build your own custom skinnable components, check out this page.