Most Flex developers have seen and used the [Bindable] tag but not many know what this tag does or even what it is. [Bindable] is what is known as a metadata tag. Metadata tags are special tags that are inserted in your source code that give the compiler information on how to compile the application. These tags aren't actually compiled into the generated SWF file but provide instructions on how the compiler should create the SWF. There are 12 documented metadata tags. This article will offer definitions of these metadata tags and give examples of their use. By the end of this article you will understand when and where to use metadata tags in your Flex 2 applications.
[ArrayElementType]
Defining an array is usually very generic in nature because the elements of the array can be any type. However, using the ArrayElementType metadata tag lets you define the data types of the array elements. Here is the sample syntax of [ArrayElementType]:
[ArrayElementType("String")]
public var arrayOfStrings:Array;
[ArrayElementType("Number")]
public var arrayOfNumbers:Array;
[ArrayElementType("mx.core.UIComponent")]
public var arrayOfUIComponents:Array;
[Bindable]
The Bindable metadata tag is one of the most used metadata tags because it allows for easy data synchronization within the components of your application. Bindable can be used to bind simple data, classes, complex data, and functions. To bind a simple piece of data, you must simply define the data with the metadata tag included, as shown in Listing 1. Figure 1 shows the results of Listing 1
Bindable also allows binding to events. Listing 2 shows how to bind a property using getters and setters, along with an event binding. This example has a private variable named phoneNumber, as well as a public getter and setter. The getter method uses the Bindable tag to bind to an event named phoneNumberChanged. This setter method dispatches the phoneNumberChanged even whenever its data changes. By using a setter method, the data can be manipulated before it's set to the private variable. In this example, the data is formatted only when the length of the value coming into the method is 10. When the phoneNumberChanged event is dispatched, the second TextInput component updates because its text property is bound to the phoneNumber variable.
Figure 2 and Figure 3 show the results of Listing 2.
[DefaultProperty]
The DefaultProperty metadata tag is used to set a single property as a default property of a class. This allows the property to be set within a container tag without needing to define the property name. A simple example of this would be a custom Button class. Listing 3 shows a simple Button class that has the label property set as the DefaultProperty. Listing 4 shows how the label is defined as a string within the custom Button container tags.
[Embed]
The Embed metadata tag is used to import images into your application. There are two ways to use Embed. You can either embed the image in ActionScript and assign it to a variable (as in the first example in the following code), or you can assign it directly to the component property (using the syntax shown in the second example of the following code).
[Embed(source="myIcon.gif")]
[Bindable]
public var myIcon:Class;
<mx:Button label="Icon Button 1" icon="{myIcon}"/>
<mx:Button label="Icon Button 2" icon="{myIcon}"/>
The output from the following is identical to the previous code block. The benefits of creating the myIcon class are that it can be defined one time in a single class and bound to multiple components in your application.
<mx:Button label="Icon Button 1" icon="@Embed(source=myIcon.gif')"/>
<mx:Button label="Icon Button 2" icon="@Embed(source=myIcon.gif')"/>
[Event]
The Event metadata tag is used to declare events that will be dispatched by your custom class. Adding this metadata tag to your class definition allows you to add an event handler function to the MXML tag used to instantiate your custom class. Listing 5 creates a custom Button class that will dispatch an event whenever its label property changes. The main application file shown in Listing 6 instantiates the custom Button and creates the event handler function, which dumps the new label property to a TextArea component to show the occurring changes.
Figure 4 shows the results of Listing 5 and Listing 6.
[Effect]
The Effect metadata tag is used to define a custom effect that will be dispatched when an event occurs. This can be easily demonstrated by building on the earlier Event examples. By simply changing a single line to the ButtonLabel class (Listing 7), an effect is defined that can be assigned to an Effect instance (Listing 8).
[IconFile]
IconFile is used to identify the
filename of a jpg, gif, or png file that will be used as the icon for
your custom class. While the [Embed] meta tag can be used to embed
images files, SWF files, music files, video files, etc, IconFile is
only used to embed a file that will be used as the icon for the custom
class. Here is the example of the IconFile syntax:
[IconFile("icon.png")]
public class CustomButton extends Button
{
}
[Inspectable]
The Inspectable metadata tag is used
to define the attributes of your custom component that you would like
to display in the code hints and property inspector of Flex Builder 2.
The example shown in Listing 9
defines a variable named ccType that is inspectable. It defines a
defaultValue of Visa, a category of Credit Card and enumeration values
of Visa, Mastercard, Discover, and American Express.
Figure 5 shows the example of the code hints being displayed as the component is added to an application.
Figure 6 shows the same example, but this time in design view, which exposes the property inspector. You can see that the category of properties is Credit Card with the property showing as ccType and the available values in the drop-down.
[InstanceType]
The InstanceType metadata tag is
used to declare the type of object that will be allowed when declaring
a variable as IDeferredInstance in a template object. The syntax of
InstanceType looks like this:
[InstanceType("package.className")]
[NonCommittingChangeEvent]
The NonCommittingChangeEvent is a metadata tag that will prevent a change from occurring when a specified event occurs. Listing 10
demonstrates how this works. A private variable named s of type String
is created and bound to the ti2 TextInput component. The other
TextInput component with the id of ti1 sets the value of s equal to the
value of its text property whenever the text changes. Additionally, the
Binding metadata tag attached to the s variable is set to bind when the
triggerBinding event is dispatched. The triggerBinding event is
dispatched only when the Enter key is pressed while typing in the ti1
TextInput component.
[RemoteClass]
RemoteClass can be used to bind an
ActionScript class to a Java class or a ColdFusion CFC. This will allow
for automatic data type conversions. Below is a sample of an
ActionScript class named MyClass in the package com.mydomain being
bound to a Java class named MyClass in the package com.mydomain:
package com.mydomain {
[Bindable]
[RemoteClass(alias="com.mydomain.MyClass")]
public class MyClass {
public var id:int;
public var myText:String;
}
}
[Style]
The Style metadata tag is used to define
custom style properties for your components. Simply add the Style
metadata tag or tags to your class definition and then use the getStyle
method to retrieve its value.
Listings 11 and 12 give examples of how to define two styles named borderColor and fillColor, both of which are defined as a uint data type. The styles are set in the component tag when the class is instantiated. The updateDisplayList function is overridden and the custom styles are used to draw the circle border and fill.
Figure 7 shows the results of Listing 12 and Listing 13.
By now you should have had a few "Wow, I know where I could have used that" or "Hmm, I think I will try this metadata tag in a new project." If you haven't, then you need to go back and read the article again. OK, so what I'm trying to say is that the metadata tags provided for us by the Adobe Flex team are not only extremely powerful, allowing us to extend and customize what we do with Flex, but are also very easy to use. They are a very quick way to accomplish a great deal with only a few lines of code. If you're not using these tags, you're working too hard to accomplish things that are built into Flex 2.
The content of this article is excerpted from the upcoming book titled Professional Flex 2 (ISBN 0470102675) by Rich Tretola, Simon Barber, and Renaun Erickson from Wiley Publishing, Inc./Wrox Press. To pre-order please visit www.everythingflex.com or www.amazon.com/Professional-Flex-2-Rich-Tretola/dp/0470102675.