Create professional Flex components

Flex Builder has a great way to organize its components in tree mode, which is very a good way to organize things and make things clear to any user who are coming to Flex world.

By default, every component you create that is not part of default Flex components you will have placed in the [Custom] directory of Flex Components view in your Flex/Flash Builder, and no matter what properties you add to them, they will never be visible in the Flex Properties standard view.

But what if you want to customize that and create a component that have them all like flex components do? Well, it's not that hard so let's do that.

Create the Component

First, you have to create a new Flex Library Project. Do this by going to File->New and choose Flex Library Project. Give it a name, a location, choose whatever Flex SDK you wish to build this for and then click finish.

Now you have a blank library project in which you can create whatever components you want.
Is important to use packages correctly and namespaces and not just drop the component in the [src] folder (you'll see later why). First create a package (eg. com.adm.component) in which you can add your custom component.

package com.adm.component
{
      import mx.containers.Canvas;
 
      public class mycomponent extends Canvas
      {
      }
}

Okay, now let's create some methods to have something going. We'll make this component be a big button with a method to enable the button and one to change it's caption. We'll use setters and getter's for those properties because some other actions might be required when changing them. So:

package com.adm.component
{
     import mx.containers.Canvas;
     import mx.controls.Button;
 
      public class mycomponent extends Canvas
      {
            private var _title : String = 'Title';
            private var _active : Boolean = true;
 
            private var btn : Button = new Button();
 
            public function CustomComponent()
            {
                      super();
                      this.btn.width = 100;
                      this.btn.height = 100;
                      this.btn.label = this.label;
                      this.addChild(this.btn);
            }
 
            public function set title(val : String) : void
            {
                      this._title = val;
                      this.btn.label = val;
            }
 
            public function get title() : String
            {
                     return this._title;
            }
 
            public function set active(val : Boolean) : void
            {
                     this._active = val;
                     this.btn.enabled= val;
            }
 
            public function get active() : Boolean
            {
                    return this._active;
            }
      }
}

So, if you now build your project, a .swc file will be generated in your [bin] folder, which you can add in other projects and use. But now, the component will be placed in the [Custom] directory in the Components View and not the one you want. We'll do that a bit later now let's just....

Give it an icon

This is really simple. All you have to do is get a nice looking .png icon (16x16 pixels preferably) and place it next to your component. Then, use the IconFile metadata tag to link it to your component.

....
[IconFile("icon.png")]
public class mycomponent extends Canvas
{
       private var _title : String = 'Title';
       .......

Inspectable properties

If you have extra information about the property that will help code hints or the Property Inspector (such as enumeration values or that a String is actually a file path) then also add [Inspectable] metadata with that extra info. For our methods we have:

       ...
       [Inspectable(category="General", type="String", defaultValue="")]
       public function set title(val : String) : void
       .....
       .....
       [Inspectable(category="General", type="Boolean", defaultValue="true", enumeration="true,false")]
       public function set active(val : Boolean) : void

This will also help a lot when we'll add this properties in the Flex Properties panel. For more informations about the [Inspectable] metadata tag visit http://livedocs.adobe.com/flex/2/docs/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Parts&file=00001658.html

Create custom component folder

So, if you want to build a professional component, you can't leave Flex add your component in the default [Custom] directory in the Components tree. So, in order to create your own folder, we must use few tricks.

First of all, you need two .xml files to describe the structure you want flex to use and overide it's default behavior.
The first file is the manifest.xml which describes the components in the package and their namespaces. In our case we'll have:

< ?xml version="1.0"?>
<componentpackage>
    <component id="mycomponent" class="org.adm.component.mycomponent"/>
</componentpackage>

Second, we need another xml to describe the way the designer will interpret all this.

< ?xml version="1.0" ?>
<design>
	<namespaces>
		<namespace prefix="adm" uri="http://www.adm.org" />
	</namespaces>
	<categories>
		<category id="Test" label="Test Panel" defaultExpand="true" />
	</categories>
	<components>
		<component name="mycomponent" namespace="adm" category="Test" displayName="Rename Me" />
	</components>
</design>

In the design.xml, you can specify the namespaces you used for the components, in this case adm will point to components in the org.adm folder.

Categories tag describes the folders you want added in the Components panel. Each category must have an id which you'll use to tell components where they should reside, a label for the category to stand as the directory name in the Components panel. defaultExpand is an optional parameter which if set to true, the folder will be showed expanded by default.

In the components tag, you specify which component goes in what category and under what title. The name parameter must match the id of a component listed in the manifest.xml. All the other parameters are pretty self explanatory.

Next, you have to include this two files in .swc package. To do that, follow the steps:

* Right Click at your project and select Properties
* In the left choose Flex Library Build Path
* Select the assets tab and mark to include manifest.xml and design.xml files
* Now select the Flex Library Compiler and include your namespace URL (in this case http://www.adm.org)
* Include the manifest file .xml you've created
* Click apply and ok to finish

After this, you should end up with something like this

Add properties to the Flex Properties view

As I said before, no matter what properties you add to your component, they will never be visible in the Flex Properties standard view, only in the category view and that only if you use the [Inspectable] metadata tag. But few more lines in the design.xml file should take care of that.

	<component name="mycomponent" namespace="adm" category="Test" displayName="Rename Me">
		<mxmlproperties>
			<textfield id="title" name="Component Title:" />
			<combo id="active" name="Active:" />
		</mxmlproperties>
		<defaultattribute name="active" value="true" />
	</component>

The id of the mxmlProperties tag should be the function/variable names from your component you want to edit. You can also define default values for those properties using the defaultAttribute tag below. Here we've only used the textfield and the combo type but there are few more you can use.

<textfiled id="propertyOrStyle" name="Label:" [multiline="false"] />
<combo id="propertyOrStyle" name="Label:" />
<colorpicker id="propertyOrStyle" name="Label:" />
<filepicker id="propertyOrStyle" name="Label:" [wrapInEmbed="false"] />
<slider id="propertyOrStyle" name="Label:" min="0" max="10" increment="1" />

For combo boxes, if you use it for a Boolean property, it will automatically be populated with [true,false] values but if want something else, the [Inspectable] metadata tag has the enumeration property where you can define the properties from this combo.

Another thing you must do in order to apply the values as soon as you change them from the properties view, is to set the functions/variables as [Bindable].

    ....
    [Inspectable(category="General", type="String", defaultValue="")]
    [Bindable]
    public function set title(val : String) : void
	....
	....
    [Inspectable(category="General", type="Boolean", defaultValue="true", enumeration="true,false")]
    [Bindable]
    public function set active(val : Boolean) : void
	....
	....

One more thing

Now, compiling this will give you a 300 something KB .swc file which is a bit large to distribute. The user will use this component inside a flex component so embedding all the libraries and SDK inside your .swc is useless. So the next step is to go to Properties->Flex Library Build Path->Library path tab, expand the build path library try and edit everything inside the SDK tree on Link Type and choose External

Now the swc component only have 4KB. Big cut down, eh ?

Done

If this is to much trouble for you or you've missed something, I've attached the sources for this tutorial here. You can import this skeleton rename the package, namespace and the component and start building on this. I hope it all made sense and....happy coding.