Intellisense – Making your components work with the Flash Builder IDE

You have made the most amazing component that does everything… seriously, this thing solved cancer, world hunger, and finally answered how unattractive guys end up with attractive women.

However there are a few things still left to do to really “finish” this component. Let’s go through those finishing touches that would really top it off. What I am going to do is go through my favorite set of metadata tags and find out what each of these tags gives us (and how we can protect ourselves from developers not as good as ourselves).

ArrayElementType
Your component expects an array of strings to handle some of it’s impressive magic. But now junior developer showed up and started using your component and the first thing said is “it doesn’t work”. You know it works, so as always the question is “what did the junior dev. do to mess up your component?” It doesn’t take long for you to see that junior dev. put in numbers where you were expecting strings, but we want to now protect against that and give junior dev. a compiler error when he tries to do it again. Very simply we are going to make one little change to our component and get this functionality.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package com.unitedmindset.components
{
  import mx.containers.Panel;

  public class AmazingComponent extends Panel
  {
  public function AmazingComponent()
  {
  super();
  }

  [ArrayElementType("String")]
  public var stringArray:Array;
  }
}

Now when junior dev. does this…

1
2
3
4
5
6
7
8
9
10
11

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mx="library://ns.adobe.com/flex/halo" minWidth="1024" minHeight="768" xmlns:components="com.unitedmindset.components.*">
  <components:AmazingComponent>
  <components:stringArray>
  <fx:Number>1</fx:Number>
  <fx:Number>2</fx:Number>
  <fx:Number>3</fx:Number>
  <fx:Number>4</fx:Number>
  </components:stringArray>
  </components:AmazingComponent>
</s:Application>

Junior Dev will get this pretty little error straight from the compiler.

1	In initializer for 'stringArray', type Number is not assignable to target Array element type String. MetaTagsBlog.mxml MetaTagsBlog/src line 5 Flex Problem

ArrayElementType Error

DefaultProperty
Now let’s say you want to simplify your component and have it’s visual children go right into the component without having to set the property. Your original code to add children may look as such…

1
2
3
4
5

  <components:AmazingComponent>
  <components:children>
  <mx:Label text="Hello World"/>
  </components:children>
  </components:AmazingComponent>

If you remove the <components:children> then you will get an error. Now we are going to add in our defaultproperty tag which will tell Flex where to put the information directly injected in the component without property tags.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

package com.unitedmindset.components
{
  import mx.containers.Panel;

  [DefaultProperty("children")]
  public class AmazingComponent extends Panel
  {
  public function AmazingComponent()
  {
  super();
  width = 300;
  height = 300;
  }

  //array
  [ArrayElementType("String")]
  public var stringArray:Array;

  private var _children:Array;
  public function get children():Array
  {
  return _children;
  }
  public function set children(value:Array):void
  {
_children = value;
  var i:int=-1;
  var l:int=value.length;
  while(++i<l){
addChild(value[i]);
  }
  }
  }
}

And your MXML can now look as such:

1
2
3

  <components:AmazingComponent>
  <mx:Label text="Hello World"/>
  </components:AmazingComponent>

If we change the default property to the stringArray you can put your array directly into the component without specifying the <components:stringArray/>.

Effect

Effect Intellisense

One thing that you made sure to program into your amazing component is a few effects so that when it displays the cure for cancer, everything lightens up. Effects are called when an event is fired, so we need to state the event and the effect that are called. Now the effect would still run with or without the metatag, the just metatag makes it so that other programmers can see your effect in the intellisense.

One more thing here, with Flash Builder 4 Adobe has been nice enough to make ASDocs actually make a difference in live programming without having to go and read the original component or compiled docs. Adding ASDocs to the effect metatag we get a bunch of extra information. Our metatag now looks like:

1
2
3
4

/**
* Effect run when the lighten event is fired.
*/
[Effect(name="lighten", event="flash.events.Event")]

And now we get…

Effect Metatag Intellisense

Events
Just like the effect metatag the event metatag helps other developers know what is going on in your amazing component. The event is going to fire whether the metatag is there or not, but the intellisense can now help other developers.

MXML Event Metatag Without ASDocs

AS Event Metatag without ASDoc

And just like our effect metatag we can add a bit of asdoc’ing to our tag to give future developers event more information.

Effect Metatag with ASDocs

AS Effect Metatag with ASDoc

And the code…

1
2
3
4
5

  [Event(name="customEventStart",type="com.unitedmindset.events.CustomEvent")]
  /**
* Event fired when when the component has ended.
*/
  [Event(name="customEventEnd",type="com.unitedmindset.events.CustomEvent")]

IconFile
Are you jealous that your amazing component doesn’t look pretty in the component list like Adobe’s component. Well you can get this same pretty custom icon by specifying the icon file metatag.

IconFile Metatag

1
2
3
4
5
6
7
8
9
10

  [DefaultProperty("children")]
  [IconFile("um.png")]
  public class AmazingComponent extends Panel
  {
  public function AmazingComponent()
  {
  super();
  width = 300;
  height = 300;
  }

Inspectable
This is my personal favorite. Do you like it when Flash Builder pops up a list options for a variable? I do. This isn’t a great feature out of your reach, it is right here for your taking. With the inspectable tag you can state where your variable goes in the property window along with intellisense.

Inspectable Metatag

Here is my code for my position string variable:

1 2	[Inspectable(defaultValue="up", category="Common", enumeration="up,down,left,right")] public var position:String = "up";

Notice that I added an array of strings with the different options that we are allowing in our variable, I stated which category it goes into in the property panel, and I even put the defaultValue for other developers to know right off the bat what is in our component.

And what it gives us…

MXML Inspectable

Property Panel

And for our specialColor variable…

1 2	[Inspectable(defaultValue="0x000000", category="Styles", format="Color")] public var specialColor:uint = 0x000000;

Here I stated that this variable will be in the styles category, and that the format is color, so we even get a color picker in the properties panel.

Properties Panel, Before Using Color Picker

Properties Panel, After Using Color Picker

Category options are “Common”, “Effects”, “Events”, “Layout Constraints”, “Size”, “Styles”, or “Other” (which is default).

Style
You have made your amazing component to have many different styles, but again we need to set up our component so that our junior developer can understand how our component styles are set up. With some simple coding we can have all of this taken care of…

1
2
3
4
5
6
7
8
9

  /**
* Our special color.
*/
  [Style(name="specialSelectedColor", type="Number", format="Color", inherit="yes")]

  /**
* Button Placement in component.
*/
  [Style(name="buttonPlacement", type="String", enumeration="top,bottom,left,right", inherit="no")]

And with these metatags we get all the following intellisense and property information.

MXML Style

Property Panel

ASDocs

Adobe ASDoc

Don’t you love how now you get REAL information about everything with just a roll over? This is easily accomplished with some simple asdocs. The panel has docs, the properties have docs, now your amazing component has it…

1
2
3
4
5
6
7
8
9
10
11
12
13

  [DefaultProperty("children")]
  [IconFile("um.png")]
  /**
* Amazing component that cures cancer, helps cats and dogs get along, and solves world hunger.
*
* <p>
* And if you use the right function this component will write whole applications for you.
* </p>
*
* @author jonbcampos
*
*/
  public class AmazingComponent extends Panel

And you get…

Amazing Component ASDoc

Closing
Now your amazing component has all the bells and whistles and your junior dev can keep developing with crutches and with every part of the component highly documented and laid out on a silver platter. On top of everything else, the component is compiler checked and input verified. Happy coding.