Setting Up an AIR Application with File Associations

WARNING: This was written for a BETA version of AIR and may not be valid for the most recent release

In case you were wondering, and I know that you were, AIR is not just another browser or an alternative stand along player for Flash movies. It is true that they run the same or similar content, but AIR is more. AIR is a complete desktop solution which uses web-based technologies for its development but goes beyond the capabilities that are currently available to them. A case in point: file association.

With AIR you can associate any file type with your AIR applications. This means, when opened, an associated file will open itself in your AIR application. This greatly streamlines your ability to work with external files when using them with AIR applications. This tutorial shows you how that can be done.

Requirements:

Note: Though this tutorial uses Flash CS3, the same ActionScript could be applied to an AIR project in Flex Builder.

Source files:

Setting Up File Associations

File associations for AIR applications are made when the application is installed. This means that file associations cannot be tested until you package and install your application through an AIR (.air) file. Just testing your application through Flash (or Flex Builder) will not set up those associations for you.

File associations themselves are defined in the AIR application's descriptor (or application XML) file. These settings are not available in the Application and Package Settings dialog available in Flash (provided by the AIR Update for Flash), so they will have to be added manually. Then, when the application is packaged, it reads the application descriptor file and identifies which file types should be associated with the application at the point when the generated AIR file is installed.

In the application descriptor file, the <filetypes> element contains a list of file associations that are to be made with the application. Any number of <filetype> elements are contained within this tag for each file association made. Inside the <filetype> element are 4 more elements that describe the file type. These include: <name>, <extension>, <description>, and <contentType>.

The following is an example of a filetypes element. It contains two file associations for the extensions .text and .binairy that would open with an AIR application called myAIREditor:

<fileTypes>
	<fileType>
		<name>myAIREditor.Text</name>
		<extension>text</extension>
		<description>myAIREditor text description file</description>
		<contentType>text/plain</contentType>
	</fileType>
	<fileType>
		<name>myAIREditor.Binary</name>
		<extension>binairy</extension>
		<description>myAIREditor project file</description>
		<contentType>application/octet-stream</contentType>
	</fileType>
</fileTypes>

When defining file associations for your AIR application, you would need to add a similar definition to your application descriptor file. In doing this with Flash, you should make sure you rename the descriptor to something other than the default or your changes may not be saved.

Handling the Opening of an Associated File

When creating an AIR application with a file association, your work doesn't stop with just setting up an association through the application descriptor file. Once that is done, you need to be able to handle the file data as your application is opened with it.

When an application is launched through a file associated with that application, the application receives the file path as an argument. In AIR, application arguments are recognized through an InvokeEvent.INVOKE (flash.events.InvokeEvent) event from the Shell.shell (file.system.Shell) singleton instance. This same event is used for when the application is launched through opening an associated file as well as when an associated file is opened while the application is already running. Because you cannot assign event listeners in ActionScript prior to an application being "invoked," The first INVOKE event will wait for the first event handler assigned to listen for the INVOKE event and call it directly after with the arguments that opened the application.

The instance of InvokeEvent passed into the INVOKE event handler contains an arguments property which contains the arguments used to launch the application as an array of strings. When a file is opened launching the application, the arguments array consists of one value, the full file path of the file opened. With this path, you can open the file and do with it as you see fit. Here is a simple example implementation:

function initializationHandler(event:InvokeEvent):void {
	trace("Application opened with: "+event.arguments[0]); // file path
}
Shell.shell.addEventListener(InvokeEvent.INVOKE, initializationHandler);

Note that with Shell.shell, shell is a static property from the Shell class so it is accessible from any class at any time.

Creating a File Viewer

The following will cover creating a file viewer from scratch that will work with a unique file type that will be associated with the application. To keep things easy, the file type being associated will just be a JPEG with a modified extension. Instead of an extension of .jpg this application will open JPEG files with the extension .airpg.

  1. Create a new AIR file in Adobe Flash CS3
  2. In the Property Inspector, click on the Settings next to Publish:
  3. Change the document size to be 400x264. This is so that the application size will match associated file size.
  4. Click OK

The content of this movie will consist solely of the images used to launch it (associated airpg files); there will be no other visual elements. Everything else from here on out will be mostly ActionScript. However, if you think users might need something to look at if the application is launched without a file, feel free to draw some hearts or flowers on the stage. I'm sure they will be appreciated.

ActionScript

For our ActionScript, the first thing to do is import the classes we need. The Flash Player classes natively available in ActionScript are imported automatically but any AIR-specific classes are not. For obtaining application arguments, two AIR classes are used, InvokeEvent and Shell.

  1. Select the first frame of the document and open the Actions panel (Window > Actions)
  2. Add the script to import the necessary AIR classes to the Actions Panel
    import flash.events.InvokeEvent;
    import flash.system.Shell;

Before we use any of these classes, we should set up the dependencies we have to displaying the image files. Since we're dealing with simple JPEG files, all we need is a simple Loader instance that can load in those files and display them on the screen.

  1. Add the following script creating a Loader instance to the Actions Panel
    var fileLoader:Loader = new Loader();
    addChild(fileLoader);

All that really remains is the event handling for the INVOKE event. When Shell.shell receives that event, the arguments should be checked for a file path and then loaded into the loader. It would be a good idea to make sure that there are arguments within the INVOKE's InvokeEvent event instance (via arguments property) before attempting to get the file path of a file from it first. But for now, we can assume that if there is an argument, it will be that of a valid file on the users computer and send it directly to the loader.

  1. Add the script that will handle the INVOKE event
    Shell.shell.addEventListener(InvokeEvent.INVOKE, handleInitializationArgs);
    function handleInitializationArgs(event:InvokeEvent):void {
    	
    	var args:Array = event.arguments as Array;
    	if (args.length) {
    		
    		var fileToOpen:String = String(args[0]);
    		fileLoader.load(new URLRequest(fileToOpen));
    	}
    }

Once that code has been added, the application coding is complete. Simply, an event is used to capture the path to a file that was used to open the application and then loaded into a loader instance on the display list. That's all it takes.

  1. Save your application a FileAssociationExample.fla in a folder of your choice
  2. Test your movie using Control > Test Movie opening it up in AIR making sure there's no errors.

All that remains is defining the association through the application descriptor file. Though this will have to be edited by hand, Flash can help us get started.

Application Descriptor XML

Once you've tested your movie in Flash, an application descriptor XML file will automatically be created. This will be created in the same directory as the FLA with the name <FLA filename>-app.xml. You can edit the basic properties of this file through Flash using the Application and Package Settings dialog available through Commands > AIR - Application and Package Settings. File associations will have to be made manually.

  1. Open the Application and Package Settings dialog using Commands > AIR - Application and Package Settings
  2. Modify the properties within that dialog to fit the desired description of your application
  3. While still in the Application and Package Settings dialog, click on the Select Icon Images button. This will let you select an application icon (and will also affect associated file icons)
  4. Copy icon.png in the source files into the folder where your FLA is located
  5. In the Icon images dialog in Flash, remove all of the default icons using the trashcan buttons and select icon.png for the 128x128 icon (the smaller icons will be generated automatically)
  6. Click OK to confirm the Icon images
  7. Test your movie using Control > Test Movie to make sure the changes take
  8. In the folder with the FLA, make a copy of the descriptor file naming it FileAssociationExample-app2.xml
  9. Open this file in a text editor (you can even open it in Flash). It should look something like this
    <?xml version ="1.0" encoding="utf-8" ?>
    <application appId="com.air.flash.FileAssociationExample" version="1.0" xmlns="http://ns.adobe.com/air/application/1.0.M4">
    	<name>FileAssociationExample</name>
    	<description>Viewer for airpg files</description>
    	<title>FileAssociationExample</title>
    	<copyright>2007</copyright>
    	<rootContent systemChrome="standard" transparent="false" visible="true">FileAssociationExample.swf</rootContent>
    	<!--<installFolder></installFolder>-->
    	<icon>
    		<image128x128>/icons/icon.png</image128x128>
    	</icon>
    	<!--<handleUpdates/>-->
    	<!--<fileTypes>
    		<fileType>
    			<name>adobe.FlashFile</name>
    			<extension>swf</extension>
    			<description>Adobe Flash File</description>
    			<contentType>application/x-shockwave-flash</contentType>
    		</fileType>
    	</fileTypes>-->
    </application>

The template used to generate the descriptor file from Flash already includes XML for making a file association only it's commented out. We can use this code to set up our assoication with airpg files removing the comments and changing the appropriate fields. The other properties were set through Flash where it was easier to do so, however you could also have done it by hand.

  1. Modify the commented filetypes element in the descriptor file to look like the following:
    <fileTypes>
    	<fileType>
    		<name>FileAssociationExample.Image</name>
    		<extension>airpg</extension>
    		<description>AIR application example file (JPEG)</description>
    		<contentType>img/jpeg</contentType>
    	</fileType>
    </fileTypes>
  2. Save

Now the descriptor file is complete. The association is correctly defined and we even have an application that will load and display these files when opened through them. All you need to do is package and install it.

  1. In Flash, open the Application and Package Settings dialog using Commands > AIR - Application and Package Settings
  2. Select and check the checkbox labeled Use custom application descriptor file and browse to and select FileAssociationExample-app2.xml

Now our custom application descriptor file is being used. It will set up the necessary associations when the AIR installer package is created. The files used in this package are at the bottom of the Application and Package Settings dialog. Since we're using a custom icon, that icon file will have to be included with the other included files before packaging.

  1. Use the plus (+) button to add the icon.png file used for the application icon into the included files
  2. Next, click the Package button at the bottom of the dialog
  3. An alert should appear confirming the AIR file has been created. Confirm it by clicking OK
  4. Exit the Application and Package Settings dialog by clicking OK

Development is complete! All you need to do now is install the application and test it out. There are some .airpg files (sporting a new icon after the AIR application installation) with the source files which you can try out. Try to open them and they should open in your new AIR application.

A completed version of the source files is available in the completed folder of the source files download.

Conclusion

The ability to associate files to AIR applications is a very handy feature. However, don't abuse or overuse this feature. Don't immediately assume that your users will want the file associations you set up, especially if they are of known file types.

This example used a custom file extension for the file association that was made. It's true that the files were no more than JPEG images, but because a custom extension was used for those files, this application did not hijack the normal association of regular JPEG files. Assuming you use a filetype or extension that is unique, you should be ok. Either that or at least make sure user's know what they're getting into when they install your application.