Manifests, Namespaces and Flex Builder 2

I’ve been intrigued by the name spaces within Flex Builder and considering I add two to three at a time in most of my applications I was on the scout for a more efficient way in which to deal with them. I finally found time to have a hunt through the Flex directory on my Mac and over a conversation with a Simon Gregory, a fellow Flex 2 developer. I finally achieved my desire to reduce all of the namespaces and created one for the FlashGen.Com domain.

So how can you create one for yourself? It’s pretty easy once you know how and to be honest once you finish reading this you’ll be questioning why you hadn’t worked it out earlier.

The trick is that the URL is nothing more that a unique identifier – as anyone who has actually gone to http://www.adobe.com/2006/mxml will no doubt already have discovered there is nothing there (if memory serves you get their custom 404 page). So having established that there is “nothing to see here” in regards the the actual URL how does this relate to the namespace (xmlns:mx=”…”) and how can you make your own? Read on and you’ll find out..

All it relates to is a set of files called flex-config.xml and mxml-manifest.xml (in the case of Adobe and the mx name space). I’ve provided a snippet of both so you can see what they contain (if you really want to know more just have a sniff through your Flex SDK folder (search or spotlight will find them easily). DO NOT EDIT THESE. If you do you are likely to stuff up your Flex installation. So make copies of each of them and play around with those instead.

This is the flex-config.xml, cut down to show what we’re interested in (most of it you can ignore as we’re not interested in it beyond knowing it’s there).

Lets start with the flex-config.xml file. The default one that comes with Flex Builder 2 / 3 provides all of the compiler information that is needed to create your SWF’s via Flex Builder, it does a few other things but we are going to concentrate on specific elements enclosed within the <compiler></compiler> tags in this file, primarily <namespaces></namespaces>. If you look at the section I’ve extracted below you’ll see that I’ve started with the namespaces first. Now all this does is tell this config file what manifest file it needs to use (we’ll come on to the manifest file in a moment).

<flex-config>
   <compiler>
    ...
      <namespaces>
         <!-- Specify a URI to associate with a manifest of components for use as MXML -->
         <!-- elements.                                                                -->
         <namespace>
            <uri>http://www.adobe.com/2006/mxml</uri>
            <manifest>mxml-manifest.xml</manifest>
         </namespace>
      </namespaces>
</compiler>
...
</flex-config>

You’ll notice we define our URI base namespace in the <uri></uri> tag and our manifest in, you guessed it, the <manifest></manifest> tag. These are in turn enclosed within an individual <namespace></namespace> tag. This allows us to define a selection of namespaces and include them within the <namespaces></namespaces> tag for use by the compiler that way we can utilize more than one selection of code libraries within a single application. Well leave the flex-config file there for a bit and have a look at the manifest file now but don’t close this file as we’ll need to make a quick alteration at the end. You can pretty much delete everything else from the flex-config.xml file as you don’t need it.

The default manifest file for Flex Builder is called mxml-manifest.xml and it is very similar (read identical) to the manifest files created for packaging up SWC’s. It contains a single <componentPackage></componentPackage> tag that encloses all of the class descriptors for that namespace. i.e. When you create an app that uses a DataGrid in the MXML the compiler looks at this file to resolve what class that actually relates to and imports it. Below is a snapshot of part of the mxml-manifest.xml file.

<?xml version="1.0"?>
<componentPackage>
 
    <component id="Accordion" class="mx.containers.Accordion"/>
    <component id="AddChildAction" class="mx.effects.AddChildAction"/>
	<component id="AnimateProperty" class="mx.effects.AnimateProperty"/>
    <component id="Application" class="mx.core.Application"/>
    <component id="ApplicationControlBar" class="mx.containers.ApplicationControlBar"/>
    <component id="ArrayCollection" class="mx.collections.ArrayCollection"/>
    <component id="Blur" class="mx.effects.Blur"/>
    <component id="Box" class="mx.containers.Box"/>
    <component id="Button" class="mx.controls.Button"/>
    <component id="ButtonBar" class="mx.controls.ButtonBar"/>
    <component id="Canvas" class="mx.containers.Canvas"/>
    <component id="CheckBox" class="mx.controls.CheckBox"/>
    <component id="ColorPicker" class="mx.controls.ColorPicker"/>
    <component id="ComboBox" class="mx.controls.ComboBox"/>
    <component id="Container" class="mx.core.Container"/>
    <component id="ControlBar" class="mx.containers.ControlBar"/>
    <component id="CurrencyFormatter" class="mx.formatters.CurrencyFormatter"/>
    <component id="CurrencyValidator" class="mx.validators.CurrencyValidator"/>
    <component id="CreditCardValidator" class="mx.validators.CreditCardValidator"/>
    <component id="DataGrid" class="mx.controls.DataGrid"/>

That’s all we need to know about the manifest (see what I mean by how easy it is). If you haven’t already (and you really should have), make copies of both flex-config.mxml and mxml-manifest.xml and open them up in your favourite text editor. Right, now we have the copies let’s do a bit of editing. First lets make our namespace. locate the <namespaces></namespaces> tags in your flex-config.xml copy and change the URI to your own URL – if you have one, if not you can use mine.

<flex-config>
   <compiler>
    ...
      <namespaces>
         <!-- Specify a URI to associate with a manifest of components for use as MXML -->
         <!-- elements.                                                                -->
         <namespace>
            <uri>http://www.flashgen.com/2007/fgxml</uri>
            <manifest>mxml-manifest.xml</manifest>
         </namespace>
      </namespaces>
</compiler>
...
  </flex-config>

Whatever comes after the actual domain is purely subjective so feel free to use anything (except special characters etc as they won’t work correctly). Don’t feel you have to copy mine verbatim, however I would suggest keeping the year in there as it helps identify when you may have created this namespace, and again years are unique (so I’m told :p). The FGXML part is just illustrative and as I already mentioned, it can be whatever word or additional “folder” structure you wish to use.

Save the file (we’ll come to the actual file name in a bit), Now open up the mxml-manifest.xml copy you made. This is the really labourious bit of the process, you now need to go through your entire package structure and add in the id and the fully qualified path for each class in the same format as above. Now I know I said it was simple, but I didn’t guarantee it would be easy :p. Don’t worry though I have something to take the edge of this whole process.

OK, don’t worry about doing the whole of the manifest now just add in a couple of your components and their class paths and save the file (delete the rest of the content of the mxml-manifest.xml file so you are left with something like this:

<?xml version="1.0"?>
<componentPackage>
 
    <component id="MyComponent1" class="com.flashgen.display.containers.MyComponent1"/>
    <component id="MyComponent2" class="com.flashgen.display.containers.MyComponent2"/>
 
</componentPackage>

I’ve used the class names MyComponent1 and MyComponent2 for illustrative purposes you would obviously insert your actual class names.

So we have our copied flex-config.xml and mxml-manifest.xml files, How do we go about using them in our Flex projects? This is the really easy part, firstly we need to rename the mxml-manifest.xml file. For this example we’ll rename it to flashgen-manifest.xml. Now, you should still have the flex-config.xml open, if not open it again and locate the <manifest></manifest> tags, change the entry to read flashgen-manifest.xml instead of mxml-manifest.xml. Save and close the file. The final bit is to import them into the source root of your specific Flex project in Flex Builder 2 and rename the flex-config.xml to that of your default application-config.xml file (this is usually the same name as your project). So if your application file was called MyApplication.mxml we would name our flex-config.xml to MyApplication-config.xml.

The reason for doing this is so that the compiler picks it up and uses it in relation to that application.

Right thats it all set up to actually use it we just need to wire it into our MXML files like the example below:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
                           xmlns:fgx="http://www.flashgen.com/2007/fgxml" 
                           layout="absolute">
	<fgx:MyComponent1 width="200" height="200" borderStyle="solid" />
</mx:Application>

Ok so that’s it, now a few things to be aware of – these are compile time settings so don’t expect the code hinting to work (I’m currently looking into how this works and will hopefully have an answer shortly). Also I mentioned that I had a solution to the whole manifest creation issue and having to go through all of the packages and adding them. I wrote a shell script and a selection of Ant tasks to create these files (currently these will only work on Mac and *nix systems and don’t actually need to be used with Flex Builder. I’m looking at creating a Windows version as well so watch this space.

I’m a bit tied for time this morning (plus I need to clean up the scripts for distribution), but I will have them up after lunch – 1pm-ish BST