Friday, April 20, 2012

Using manifest.xml Files in Flex Library Projects


Have you ever wondered why the spark, mx, and fx libs in your MXML files get pretty url-like namespaces while your own library projects are given package-like namespaces? Using a manifest.xml file you can choose a custom namespace of your own. Plus, there's benefits for doing so.

First, why would you want to (other than the professional aesthetics of your awesome library)? I see two main problems with the default package-like namespaces.

  1. Since the namespace is tied to a specific package structure, any time you modify the package structure of the library or move components around in it, you have to go through and update all your namespaces.
  2. If you use more than one component from your library in the same MXML file, in which those components exist in different packages in your library, you end up with multiple namespaces -- one for each package from which the components came from.
A custom namespace has no ties to a package structure in your library allowing to re-arrange things as often as you'd like and separate them into as many packages as you want, all with a single namespace that never needs updated. Any of these changes to your library simply requires updates to the manifest file.

Although the manifest file can be named whatever you want, it's customary to name it "manifest.xml". You can place it anywhere you want. I suggest keeping it somewhere in the project but above the source directory (such as in the root of the project).

The content of the manifest consists of XML nodes for each component you want to expose in the namesspace. For example, the source of the manifest for the ShinyLib library looks like this:


<?xml version="1.0"?>
<componentPackage>
    <!-- components -->
    <component id="CollapsiblePanel" class="com.shinynet.shinylib.components.CollapsiblePanel"/>
    <component id="FieldSet" class="com.shinynet.shinylib.components.FieldSet"/>
    <component id="FormattedTextInput" class="com.shinynet.shinylib.components.FormattedTextInput"/>
    ...
</componentPackage>


To apply the manifest to your library and give it a custom namespace, from FlashBuilder, go to the library's properties and to the compiler options. Towards the bottom you'll see a space for specifying a custom namespace and browsing to your manifest file. The namespace you choose can be anything you want, but it should be something unique as well as providing some insight to what the namespace points to. In the case of the ShinyLib library, I'm using library://ns.shinynet.com/flex/shinylib

That's really all there is to it. However, you may notice a couple less-than-ideal situations. First, the benefits I mentioned above (being able to reorganize your library with no changes to the MXML files using the library) is only valid for... you guessed it, when defining your components using MXML syntax. When you instantiate the components in actionscript it still requires a package-specific import which would require updating anytime your library's package structure is changed.

Also, you have no control over the namespace identifier that FlashBuilder automatically generates for you. It's usually "ns1", such as xmlns:ns1="library://... and then "ns2" followed by "ns3" and so on. I tend to update the identifier to whatever I want after the first time FlashBuilder adds it for me, and then each additional use of a component from the library in that same MXML file will use the same identifier/namespace combination.


As Tink mentioned in the comments, you can control the namespace prefix that gets automatically added to your MXML file by utilizing a design.xml file. You can look at the design.xml file in the ShinyLib library to see an example of how to create it. The design.xml needs to be placed in your library's source root and you need to make sure it's compiled into your library.

Overall, it's a handy mechanism to utilize.


2 comments:

  1. You can control the namespace identifier by adding in a design.xml file.

    ReplyDelete
    Replies
    1. Thanks Tink, I wasn't aware of this. I'll do some research and see what I can find out. I'm thinking I need to start sending my posts to you for review before submitting them :)

      Delete