When building applications, especially those with a document-based model such as the Aviary apps, Odosketch, My Canvas, ZenStudio, the apps on acrobat.com, and many others, you need a file format for the document or project. Or some way to save it.

What Not To Do

You don’t want to save each item into a table in the database. I know a guy…who had a dream…that his friend did this. This guy’s friend in his dream had a table for each item that needed to be stored with foreign keys etc. When a project needed to be loaded, the server-side script did a ton of queries and created a sometimes-quite-large XML structure that it then sent to the Flash app. When saving, this XML was sent back and parsed back into the database with INSERTS and UPDATES.

That does not scale, and none of that data was needed to be pulled up in reports or anything that you might consider useful and require a database for. It was complex, hard to add features, and slow. That is, it would have been had that guy’s dream friend been real.

Warmer, warmer

Saving document/project files to disk is the way to go. You can store metadata about each project or document in a database if you are storing them server-side. If it is an AIR app, give it a unique extension and the user can double-click on the file to open it. If you are AIR only, you can save your file as a SQLite database file. Pretty sweet option, but doesn’t work for the browser ’cause Flash can’t do that. The format could be XML like OpenOffice documents and the new MS Office formats. You would need to parse the files in and out and they could get very large, so you’d want to compress them anyway.

Hot, burning, you’re on fire!

So, XML might be the most portable format, but hey, that’s what Import/Export dialogs are for, right? We’re talking about Save/Save As… :) Enter our new contender, AMF! AMF isn’t really new, however I haven’t heard of many people using it as their file format. The cool thing about using AMF is that after you’ve prepared your objects for it, you could store (in player 10) pieces of your document on the clipboard for copy/paste from one place to another (even after a page refresh or from AIR to browser!). You can do an auto-save of a document or page to the user’s SharedObject store.

Preparation and implementation

To use AMF as the format for you data you’ll need to prepare your objects sufficiently. Here are a few rules:

• No required parameters in your constructors. When AMF unserializes it has to create those objects and assign the public properties to it. You’ll get errors otherwise.
• Register your classes using flash.net.registerClassAlias or [RemoteClass(alias="...")]. This will store the registered alias name to map a class to a string for serializing and unserializing.
• Use IExternalizable for more complex items that only need a few properties stored, or for Flash classes that can’t be stored (e.g. BitmapData). This allows you to get around the constructor parameter issue, but it is more work. :)
• Make sure any data you need stored is a public getter/setter or you’ll have to use IExternalizable. AMF serialization will only store data that is public and read/write. If you think about it, it makes sense.

The way to store your document object or project object (or page, or widget, or whatever) to AMF depends on where you are storing it. There are a lot of Flash APIs that use AMF already. If you are storing it to SharedObject, just assign the item to the data property or one of its properties.

SharedObject.getLocal("_myProject").data.project1 = myProject;

To send it from one app to another over LocalConection is just as easy.

var conn:LocalConnection = new LocalConnection();
conn.send("_connName", "passProject", myProject);

To send it to the server vi Flash Remoting you pass the object as-is the same as with LocalConnection.

If you want to save the project to disk or pass it to the server in a RESTful manner or as a file upload, you’ll need to serialize it to AMF first. But that is pretty easy. Just remember to compress after you write it and uncompress before you read. This will save a lot of room.

var byteArray:ByteArray = new ByteArray();
byteArray.writeObject(myProject);
byteArray.compress();
// write the bytearray to file or send to server
// or we can pull it back out making a clone! (save as...)
byteArray.position = 0;
myProject = byteArray.readObject();

Easy cheesy. I will leave it as an exercise to the reader to figure out how to store it to the clipboard for copy/paste.

XML might be an easier format, though more verbose and prone to errors in the creation and parsing. Though it could allow for greater flexibility and accessibility to other programs to read the file.

Let me know if you use AMF for your document/project file storage. I’d be interested to hear how many people use this method and how well it has worked out for you.

Framerate makes great sense when doing games or timeline based animations, but in applications do we need it? We can update the screen on mouse moves, roll overs, etc. with the MouseEvent.updateAfterEvent instance method. And for transitions and tweening the class could use a Timer for the duration of the animation and again call Timer.updateAfterEvent. Then the screen would only refresh when it needs to. Performance would be greatly increased. Seems like it makes sense. Would this be something to add to Flex? Would it give us the performance we need/want for mobile applications and more responsive desktop applications?

Any foreseeable drawbacks? What do you think?

Update: I did some testing and it seems that the Timer class is directly influenced by the frameRate. With a frame rate of 0 a timer which should fire immediately (set to 0ms) doesn’t fire for 20 seconds! With the frame rate a 0.1 it happens at about 2 seconds, a frame rate of 1 is about 145 ms and a frame rate of anything over 4 seems to be around the same (10ms – 30ms probably depending on what the OS is currently doing).

MouseEvent updating and such happen as they should however, so as long as you start of with a frame rate of 4 so that the app can initialize visually, you could drop it down to 0 until a tween is needed and then bump it up to 4 for the duration of the tween. The rest of the visual changes can respond to mouse events (resize, click, rollover, etc). Or leaving it at 4 frames a second probably isn’t too bad on CPU, either way, you’d have to call updateAfterEvent when needed.

There have been a couple versions, the first was completely web-based using Ajax, the second a mix of Ajax and Flex. Both of these versions were browser based. Both of these versions had limitations and issues because they were browser based. Enter final version.

The final version will be in 2 parts, a server part and a client part. The server part will be a RESTful webservice using Atom Publishing Protocol, the same protocol Google uses for its Google App Data services. This allows other applications to hook into the CMS and export data and make changes with the appropriate permissions. It could even allow for mashups. I’m certainly interested to see what people will do with it.

The client part will be created using Adobe Integrated Runtime (AIR). This multi-platform (i.e. runs on Windows, Mac, and Linux) will give people the benefits of a browser-based admin along with the benefits of the desktop. I’ll have one browser to deal with and will be able to easily allow in-page editing. The javascript used will be much smaller and easier to deal with since I’m not worrying about cross-browser compatibility. And I’ll be able to add features such as drag-and-drop or client-side caching of the data in a local database.

I’ve almost got the server component done. It will be called Layered Content Server. Layered Content Client will run off of a server instance and together they’ll make Layered Content, a usable — as in easy to use while not limiting functionality and features — CMS.

You can learn more about the architectural decisions behind Layered Content which will allow it to be easier to use and still quite functional at the wiki. I’ll be asking for help once I get a pre-alpha version out so keep an eye out for it.

Update:

To use the ActiveRecord (sorry for the lack of documentation), you need to extend it with a class for each table you'll use. For example, if I wanted an employee table I would create an Employee class like this:

In the metadata, the name is the property name which will be auto-generated and auto-populated (when you access it) for the relation. The className is the full class path (e.g. com.foo.Bar). multiple is a flag that specifies whether it's a one-to-many relationship. You can have many-to-many relationships as well.

If you aren't creating the database yourself there is a handy-dandy feature which will do it for you off of code introspection. Many-to-many is not supported for creation this way unless you have a class for that join table and run it on that.

This will create the table if it doesn't exist, but it is also useful for updating the table if you've added new properties to the class. (right now it doesn't delete columns if you remove properties)

Then, you use it. You'll need to look at the code comments, or maybe generate the AS3 docs off of it to see all you can do, but this is some of what you can do (let's say you have an Employee class and a Task class):

Pretty cool stuff. Maybe someone should document it! :D Anyone interested in figuring out and documenting super-cool code, please apply!

It doesn't use any AIR specific features, just SharedObject, but I sure like to have it as a desktop application rather than in the browser. I always close browser versions on accident.

This application is provided as-is with no documentation, support, or guarantee of anything. Hope you find it useful. You can view Project Tracker in your web browser before you download it.

Update: Republished for the AIR 1.0 release and updated badge install.
Update 2: Found and fixed the problem reported in comments. Using a relative path in the badge installer for AIR apps results in some of the errors reported.

So I was thinking, it would be cool to write a DocBook editor in AIR. It might be the first DocBook authoring tool that looked nice. :) DocBook is an XML format for books or documentation. I won't go into why it's so great, but you can check it out yourself.

First I created a Menu class which extends NativeMenu. Because of the way MXML works we will need to set our menu's items in one go rather than using the addItem and addItemAt methods. So I created an items setter to complement the items getter which is part of NativeMenu.

I want all of the MXML tags under my <Menu> tag to be the MenuItems, so in order to tell the compiler where those go I also added a metadata tag at the top of my class.

Now moving on to the items themselves I created a MenuItem class. I wanted some more magic here since this is where all the hassle goes. First thing I wanted to do was to make a simple way to define the key shortcut. In code you have to add a keyEquivalent letter and a keyEquivalentModifiers entry for each modifier key. Way too complex for MXML. So I created a getter/setter called shortcut that parsed a string and added the pieces for you. Now I could have shortcuts that looked like "Ctrl+P" and "Cmd+Shift+F" in the MXML. Very readable. Much better. (I also set Cmd to Ctrl when on Windows since Mac Cmd shortcuts are usually the same as Windows Ctrl.)

Next I tackled submenus. I created a getter/setter called items (same as the menu now) which let you specify your submenu's items directly underneath the parent item. I figured it's not a common use-case to add listeners on the submenu itself. I also added the metadata to make MXML items inside of a MenuItem map to the "items" property.

Now our items can have their subitems directly under them in the MXML.

Finally I looked at adding support for the mnemonicIndex property to get set. For those of you who don't know what this is, it tells AIR which letter in the menu to underline and allow a key-stroke to select it (I believe it is a Windows feature, but may be supported on Mac as well....somehow). Very important for accessibility. So I figured I'll just have an underscore denote which letter should be, such as "_File" would say that "F" is the mnemonic letter.

Nicely done. We now have our label set and our mnemonic letter specified with just the label property, and this lends itself to setting the mnemonic letter separately for other languages as it is part of the label text.

I quickly added a MenuSeparator which just extended NativeMenuItem and set the isSeparator value in the constructor to true. This was for readability in the MXML.

The last thing I wanted to do is to add support for menu differences between Ma, Windows and Linux. This was a last minute idea because menus can look differently, behave differently, or have different shortcuts between the two systems. So I added a property to MenuItem called "os" which should be a string of "mac", "win", "lin" or a combination of them such as "win/lin". Then I added to the Menu items setter code that would skip over adding items which were set for an OS that was not the current one. This allows two items with the same name to be specified but with different shortcuts, or two submenus that are different on different OSes.

Now I could define menus in MXML like this:

The final result was:

Enjoy!

Update: I've put my code libraries up on Google Code. You can find the classes there. Following is an example app with a simple menu.

I have to use synchronous database connections for it so that everytime I access an object's related properties I don't have to use a callback, though it could be refactored to do that. Not my idea of fun though, and after an excellent presentation by Jason Williams, "Working with Persistent Data in AIR," where he showed how fast it was to retrieve data from an AIR database I figured it would be just fine.

Currently I don't have metadata allowing you to define how every property maps to a field in the database, nor do I have many "special case" hooks for this and that. I figured that any AIR app you write will be using a fresh database and not a legacy system. How many desktop apps using a SQLite database will you be updating with AIR and using the same database file? Maybe I'm wrong, but I don't think so.

I also added a piece that you can run which will create and update database tables based off the ActiveRecord object's properties. So you have a nice update mechanism for the database when you update your app using the updater api.

I'll be open-sourcing the code when I have time (isn't that always the case), but you can get the code now, test it out, and let me know what enhancements you'd like to see. Sorry, no documentation currently. If I like the ideas or they're requested enough I'll be sure to add them in. :)

Oh, and when you unzip it you'll see "flight" is the package Tyler (my twin) and I are using for our projects. It started when he and Rob Taylor started a component set in AS2 under the name but AS3 and Flex 2 came out and they never finished. Maybe an AS3 set will happen someday.

Update: AIR Active Record is open sourced.