Flash Builder - Design View Extensibility

The Design View Extensions Kit for Flex 4.5 contains ActionScript source files that provide a bridge to the Design Model API. Using this kit, you can write extensions for custom components to enable DesignView features typically found with Flex native components. For example, you can implement typical operations such as outline drag and drop or you can define custom drop targets. You can also customize Design View to enable custom behavior not otherwise provided by Flash Builder.

Note: Changes from Flex Builder 3 Extensibility Kit

Download

The Design View Extensibility Kit for Flex 4.5 is available for download here. There are four Flex projects in the kit:

DesignExtensions
Defines the extensions API. Use this project when developing your own design extension classes.
Picnic
A Flex Library project that defines seven simple components based on a picnic basket metaphor. This project, along with PicnicExtensions and DV4ExtensionKit projects, demonstrate how to implement and use design view extensions.
PicnicExtensions
A Flex Library project that defines the design view extension classes for the Picnic components.
DV4ExtensionKit
Contains the Tilden application that uses the Picnic classes. The Picnic and PicnicExtensions projects are on the Library Path of this project.

Instructions for importing the projects into Flash Builder and running the sample projects.

ASDoc for Design View Extensions

DesignExtensions Project

DesignExtensions is a Flex Library project that defines the Design View Extensions API.

IComponentExtensions.as defines the interface for extension classes. (The previous extension API was IExtension.as.)

IComponentExtensions.as is at the following location:

	com/adobe/flexide/extensions/components/IComponentExtension.as

The other classes in the project are stub implementations of the extensions for the built-in Flex classes. Your extension classes inherit from the appropriate classes. For example, if your component class is a subclass of Canvas, your extension class inherits from com.adobe.flexide.extensions.components.mx.containers.CanvasExtension.

In general, the hierarchy inside com.adobe.flexide.extensions.components matches that of the Flex SDK.

DesignUtils.as defines functions that extension classes call to get/set information from design view. These include functions for hit testing, determining if an item is selected, and setting the value of an attribute in the MXML code. DesignUtils.as is at the following location:

	com/adobe/flexide/extensions/components/DesignUtils.as

Sample Projects

Picnic

Picnic is a Flex Library project that defines seven simple components:

Basket
Subclass of VBox

Lettuce
Subclass of Button

Mustard
Subclass of Label

Salad
Subclass of Tile, populated by a dataProvider

Sandwich
Subclass of Canvas, with a special condiments bar for Mustard

SandwichPile
Subclass of VBox, behaves similar to a ViewStack of Sandwiches

TableCloth
Subclass of VBox

The Picnic project contains two special xml files:

design.xml

Defines the "picnic" namespace.
Defines a "Picnic" category for the Components panel.
Specifies which components to add to the Picnic category.
Associates each component with a design extension class.

picnic-manifest.xml

Associates a short name with a fully-qualified class name for each component.

The Picnic project has the following settings in the Flex Library Compiler properties panel:

Namespace URL
http://www.adobe.com/flexbuilder/picnic

Manifest file
picnic-manifest.xml

In the Flex Library Build Path properties panel ("Assets" tab), design.xml is checked. This forces design.xml to be included in the library SWC file.

PicnicExtensions

PicnicExtensions is a Flex Library project that defines the design view extension classes for the Picnic components. Note that the DesignExtensions and Picnic projects are on the Library Path of this project.

Many IComponentExtension functions are implemented by one or more of these extension classes. All class definitions are preceded with an [ExcludeClass] metadata tag so that the class is not included in code hints. This way, client projects that use the Picnic classes will not receive code hints for these design extension classes.

The design.xml file in the Picnic project sets up the associations between the Picnic components and the corresponding design extension class in this project.

DV4ExtensionKit

DV4ExtensionKit contains the Tilden application that uses the Picnic classes. The Picnic and PicnicExtensions projects are on the Library Path of this project.

After you have installed Flash Builder, launch Flash Builder and import the DV4ExtensionKit.fxp sample project into your workspace (this includes three other projects it depends on). Open the Tilden.mxml file in design mode and verify that the behaviors defined in the extension classes are in effect. Specifically:

A Lettuce component can only be dropped inside a Sandwich component
Dragging Mustard into a Sandwich places the Mustard in the Sandwich's condiments bar
Click the "Front" or "Back" button of a TableCloth switches to that background
Cursor changes when over the "Front" or "Back" button of a TableCloth
Double-clicking the "Front" or "Back" button lets you edit the name of the button

Read the comments in the various extension classes to see what other behaviors they support.

Once this is working, you are ready to modify the picnic components and extensions and to add your own components and extensions.

Packaging your Components

Putting the PicnicExtensions project on the Library Path of the project is convenient during development of your components. You can make changes to the extension classes and immediately see the effect of those changes a project that uses them. However, you may wish to package your components as a single swc file, rather than as separate swc files for the component classes and the extension classes. To do this, you need to extract the library.swf file from the extension swc, rename it to something such as design.swf, and then put that swf into the components swc file. For example, for the Picnic sample, you would do the following.

Unzip PicnicExtensions.swc (A SWC file uses the zip file format). Depending on which unzip tool you use, you might have to rename PicnicExtensions.swc to PicnicExtensions.zip.
The unzipped archive contains a file called library.swf. Rename it to design.swf.
Copy design.swf into the Picnic folder (the same place where the design.xml file is).
In Flash Builder, refresh the Picnic project (so that FB detects that the design.swf file has been added to the Picnic folder).
For the Picnic project, choose Project > Properties > Flex Library Build Path > Assets and place a check mark by design.swf. There should already be a check mark by design.xml.

With these settings, the Picnic.swc file contains both the code for the components and the design extensions. You will no longer need the separate PicnicExtensions.swc file. Of course, if you make changes to the Picnic extensions, you would need to repeat these steps.

Changes from Flex Builder 3 Extensibility Kit

Flash Builder 4 has two separate Design View architectures. The Design View that loads for Flex 3 projects uses the old Design View Extensions Kit. You do not need to make any changes to your extensions for that SDK. However, you should recompile them, as Flash Builder 4 includes the Flex SDK version 3.5.

The Design View that loads for Flex 4 projects has a new architecture and requires a new Design View Extensions Kit. Design View has been completely rewritten to support new features in Flex 4. Your extensions need some modifications, which are noted below.

IExtension -> IComponentExtension

The component extension interface's name has changed. The methods in the class have been revised and refined. Refer to IComponentExtension.as for detailed documentation on the new methods. Several have been renamed. Here are the most important changes:

(old) IExtension: function createComponent():DisplayObject;
(new) IComponentExtension: function createComponent( inItemType:String ):DisplayObject;
createComponent now takes a fully qualified name for the class to create. This allows UIComponentExtension.createComponent to be able to create a component for any UIComponent subclass.
(new) IComponentExtension - These functions replace a number of IExtension functions, including resetProperty, addDataToItem, deleteDataItem, updateDataItem:

function setProperty( inComponent:DisplayObject, inProperty:String, inValue:* ):Boolean;
function setPropertyWithDataBinding( inComponent:DisplayObject, inProperty:String, inValue:String, inValueType:String ):Boolean;
function setStyle( inComponent:DisplayObject, inStyle:String, inValue:* ):Boolean;

AIR components

Design View now can load AIR components.