RShieldsLab

Organization... what a PITA. Typically in the past I've simply dragged required libraries into my src folder. But since others here at work have begun developing in flex builder I needed to come up with a system that would meet the following requirements:

• Allow anyone working on a project to gather or write to base class libraries through cvs
• Utilize these base classes as either source or reference; ie classes for projects can either extend the base classes or the base class can be copied and pasted into a project's working package as a new class and heavily modified
• Give contributers the freedom to use the base classes as much or as little as they want
• Provide a means of documenting these classes so others can use them without having to decypher them

I had a few ideas, mostly bad ones (aliases, continue to copy and paste, etc), but decided to try out the Flex Builder Library project. Looks like it's going to handle all of the above requirements with ease.

 
Setup: These instructions assume that you have an existing project and want to move some of the more popular classes out of the project src folder and into your new library. If not you can just follow the instructions with the exception of the copy-and-paste portion.

First, under File, select New Flex Library Project. Give it a unique, clever name (I used "Library"). It will now appear in the Flex Navigator. Be sure to tell the library to include your src folder; in this case it's referring to the src of your Library Project.

Within Flex Navigator, select the folder in your project's src that you want to move to the library. Right click and copy it. Then select the src folder of your Library Project. Right click and paste. Hmm, could these instructions be any simpler?

I had a lot of time invested in my classes, so I took precautionary measures before taking the next step. From Finder (not within Flex Navigator), drag your class library out of your project folder (not your Library Project, just the project you'd copied the packages from) and put them on, say, your desktop. With your classes safe and sound we are now ready to try to use the library...

In your original project's properties (look in your menu bar for Project, Properties), add the new library to your current project. In other words, select Flex Build Path on the left, then Library Path on the right, then Add Project and select your Library Project.

We're close now, but chances are pretty good that your original project can't build. If there are any errors in the library from moving it you won't be able to build the library's swc, so it won't be available to the original project. My personal problem was that I had a bunch of embedded font classes that referenced the original .otf files through an /assets directory in the project's src folder. In the interests of keeping everything neatly together in the library I decided to move the .otf's into the fonts directory (for me, com/rshields/fonts), then repoint the embed tags to the new path(/com/rshields/fonts/myFont.otf). Once I'd corrected all of the movement issues my swc compiled (it's now in the Library Project's /bin folder) and, unsurprisingly, my project compiled. It is now safe to delete the copy of your classes off the desktop.

For documentation, I simply call the following from terminal (assuming the path to your Flex sdk's bin is in your $PATH variable):

This generates an /asdocs folder in your Library Project. Note that if you aren't using AIR you should call asdoc, not aasdoc.

I can't remember if this was something enabled by a plugin or if Flex Builder has this functionality built in, but if you right click /asdocs/index.html you might have an option to open it in Flex's web browser. Now you have your API reference available to you while you work; just select the tab running the browser. The browser might have been part of Aptana, so if you don't have this option just open the file /asdoc/index.html with your web browser. It won't be in a tab within flex, but you'll still have a readily available reference just by switching to your browser.

We will most likely integrate the asdoc functionality into our cvs; ie, I'll grab the most recent cvs commits, run the asdoc script, then commit the output back onto cvs. Automated would be nice but it's not really essential. We're not planning on making daily changes to our base classes. If you plan on creating documentation in this way I highly recommend having a look at Adobe's asdoc documentation and that you begin using asdoc notation in your classes.

CVS instructions to follow, as soon as we decide where we want to put our repository...