Monday, August 15, 2011

Working with custom metadata in Flex

Flex logo by Adam Betts
If you ever developed using Adobe Flex you know that it's an easy to use and powerful framework to develop rich Internet applications (RIAs). I especially like the markup language MXML that allows you to separate design from implementation. Of course not everything about Flex is good. Even though ActionScript is a very nice programming language, there are many things you can't do or can only do using silly workarounds. For example abstract classes or private constructors – things you often use when developing complex applications.

But that's not what I want to write about. The core topic of this entry is about working with custom metadata:
Metadata is a very easy and powerful way to extend a programming language and that's exactly how it is using Flex: easy. But even though creating and using metadata in Flex is very easy, it's not well documented – at least I couldn't find all that I needed, so here's a short guide.

Applying metadata:
Applying metadata is very easy, just write the metadata tag surrounded by box brackets in front of the construct it should be applied to:
[Bindable] public var foo:Bar;
If the tag supports attributes, just add them inside the brackets so it looks like a constructor/function call:
[Event(name="name",type="flash.events.Event")] public class CustomClass extends EventDispatcher { }
Custom metadata:
For custom metadata tags it's just the same as with the built in tags: Just write them in from of any construct – you don't even have to create a special class like in C# or a special interface like in Java. If you want to read the metadata during runtime you also have to tell the compiler to include the custom tags in the resulting SWC. For this you have to add them via the compiler flag or the file flex-config.xml:
Compiler flag: -keep-as3-metadata+=TagName,TagName2,TagName3
flex-config.xml: <?xml version="1.0"?>
<flex-config>
    <compiler>
        <keep-as3-metadata>
            <name>TagName</name>
            <name>TagName2</name>
            <name>TagName3</name>
        </keep-as3-metadata>
    </compiler>
</flex-config>
When using the compiler flag, please remember to use += to append the specified tags. Otherwise the built in tags (Bindable, Event, ...) won't be recognized any more.
The flex-config.xml has to be in the src folder of your project.

Reading metadata during runtime:
Reading metadata during runtime is very easy too. There's a built in function that allows you to get a XML based description of a given datatype: describeType().
When using this function you'll get something like the following XML. I highlighted the parts where you can find the information about your metadata:

<type name="CustomClass" base="Class" isDynamic="true" isFinal="true" isStatic="true">
    <extendsClass type="Class"/>
    <extendsClass type="Object"/>
    <accessor name="prototype" access="readonly" type="*" declaredBy="Class"/>
    <factory type="CustomClass">
        <metadata name="TagName">
            <arg key="param1" value="value"/>
        </metadata>

        <extendsClass type="Object"/>
        <method name="someMethod" declaredBy="CustomClass" returnType="void">
            <metadata name="TagName2">
                <arg key="param1" value="value"/>
            </metadata>

        </method>
        <variable name="varOne" type="String">
            <metadata name="TagName3">
                <arg key="param1" value="value"/>
                <arg key="param2" value="value"/>
            </metadata>

        </variable>
        <accessor name="varTwo" access="readwrite" type="String" declaredBy="CustomClass">
            <metadata name="TagName2"/>
        </accessor>
    </factory>
</type>
Now you can use E4X to retrieve the values of your (and all the other) metadata.

Until now everything was quite well documented (flex-config.xml and Custom metadata) but now there's something that bothered me: Flash Builder doesn't know about all those custom metadata and won't autocomplete those tags. I found an article by Adobe that mentions something about a metadata.xml but doesn't describe the syntax of that file.

Autocompletion for custom metadata in Flash Builder:
This task is very easy too: just create a file called metadata.xml in the src folder of your project. The syntax of the file seems to be straight forward:

<?xml version="1.0" encoding="utf-8"?>
<annotations version="1.0">
    <metadata name="TagName" description="Does something.">

        <context name="class" />
        <attribute name="param1" type="String" required="false" />
    </metadata>
    <metadata name="TagName2" description="Another one.">
        <context name="getter" />

        <context name="setter" />
        <attribute name="param1" type="int" required="false" />
    </metadata>
</annotations>
As with the flex-config.xml you can find an 'example' file in the Adobe Flex Open Source project's source.


I hope this quick tutorial helped and I didn't forget anything or got my facts wrong ;)

Labels: , , ,

0 Comments:

Post a Comment

Subscribe to Post Comments [Atom]

Links to this post:

Create a Link

<< Home