About metadata tags

Metadata tags provide information to the compiler that describes how your components are used in an application. For example, you might create a component that defines a new event. To make that event known to the Flex compiler so that you can reference it in MXML, you insert the [Event] metadata tag into your component, as the following ActionScript class definition shows:

[Event(name="enableChanged", type="flash.events.Event")] 
class ModalText extends TextArea { 
    ... 
}

In this example, the [Event] metadata tag specifies the event name and the class that defines the type of the event object dispatched by the event. After you identify the event to the compiler, you can reference it in MXML, as the following example shows:

<?xml version="1.0"?> 
<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/mx" xmlns:MyComp="*"> 
 
    <fx:Script> 
        <![CDATA[ 
            function handleEnableChangeEvent(eventObj:Event):void { 
                ... 
            } 
        ]]> 
    </fx:Script> 
 
    <MyComp:ModalText enableChanged="handleEnableChangeEvent(event);"/> 
</s:Application>

If you omit the [Event] metadata tag from your class definition, Flex issues a syntax error when it compiles your MXML file. The error message indicates that Flex does not recognize the enableChanged property.

The Flex compiler recognizes component metadata statements in your ActionScript class files and MXML files. The metadata tags define component attributes, data binding properties, events, and other properties of the component. Flex interprets these statements during compilation; they are never interpreted during run time.

Metadata statements are associated with a class declaration, an individual data field, or a method. They are bound to the next line in the file. When you define a component property or method, add the metadata tag on the line before the property or method declaration.

Metadata tags in ActionScript

In an ActionScript file, when you define component events or other aspects of a component that affect more than a single property, you add the metadata tag outside the class definition so that the metadata is bound to the entire class, as the following example shows: 

// Add the [Event] metadata tag outside of the class file. 
[Event(name="enableChange", type="flash.events.Event")] 
public class ModalText extends TextArea { 
 
    ... 
 
    // Define class properties/methods 
    private var _enableTA:Boolean; 
 
    // Add the [Inspectable] metadata tag before the individual property. 
    [Inspectable(defaultValue="false")] 
    public function set enableTA(val:Boolean):void { 
        _enableTA = val; 
        this.enabled = val; 
     
        // Define event object, initialize it, then dispatch it.  
        var eventObj:Event = new Event("enableChange"); 
        dispatchEvent(eventObj); 
    } 
}

In this example, you add the [Event] metadata tag before the class definition to indicate that the class dispatches an event named enableChanged. You also include the [Inspectable] metadata tag to indicate the default value of the property for Adobe® Flash® Builder™. For more information on using this tag, see Inspectable metadata tag.

Metadata tags in MXML

In an MXML file, you insert the metadata tags either in an <fx:Script> block along with your ActionScript code, or in an <fx:Metadata> block, as the following example shows:

<?xml version="1.0"?> 
<!-- TextAreaEnabled.mxml --> 
<mx:TextArea xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <fx:Metadata> 
        [Event(name="enableChange", type="flash.events.Event")] 
    </fx:Metadata> 
 
    <fx:Script> 
        <![CDATA[ 
 
            // Import Event class. 
            import flash.events.Event; 
 
            // Define class properties and methods. 
            private var _enableTA:Boolean; 
 
            // Add the [Inspectable] metadata tag before the individual property. 
            [Inspectable(defaultValue="false")] 
            public function set enableTA(val:Boolean):void { 
                _enableTA = val; 
                this.enabled = val; 
     
                // Define event object, initialize it, then dispatch it.  
                var eventObj:Event = new Event("enableChange"); 
                dispatchEvent(eventObj); 
            } 
        ]]> 
    </fx:Script> 
</mx:TextArea>

A key difference between the <fx:Metadata> and <fx:Script> tags is that text within the <fx:Metadata> tag is inserted before the generated class declaration, but text within <fx:Script> tag is inserted in the body of the generated class declaration. Therefore, metadata tags like [Event] and [Effect] must go in an <fx:Metadata> tag, but the [Bindable] and [Embed] metadata tags must go in an <fx:Script> tag.