Using the framework in Flex apps built on AIR

Enough talk; time to look at some code. For the first example I will use Flex and the Adobe AIR update framework library with the user interface. To be honest I always use the version with the UI; I am too lazy to bother with creating my own UI.

Note: If you use CSS files to change the appearance of your AIR application and you use general styles (for example, for the Button or Scrollbar) that are not set as a class name but apply across your application, then these changes will also apply to the UI provided by the update framework. Keep this in mind, and always check the update framework UI when you use CSS.

If you don't want to create the project step by step, you can use the archive file provided with this article. To import the file, choose Import > Flex Builder > Flex Project and select the air_updater_flex.zip file.

Creating the AIR project in Flex Builder

Although you can create an AIR application using the command-line tools provided with the AIR SDK and your favorite text editor, I prefer to use Flex Builder:

1. Open Flex Builder and choose New > Flex Project.

2. For the project name, type air_updater_flex. For the Application type, select Desktop application (runs in Adobe AIR) (see Figure 2).

   

   Figure 2. Creating the AIR project in Flex Builder

3. Now it is time to copy the Adobe AIR update framework SWC file to the library folder of the project. For this, unzip the update framework ZIP file, and copy the applicationupdater_ui.swc file to the libs folder (see Figure 3).

   

   Figure 3. Adding the update framework library to the project

4. Create a folder inside of your web server root named updater. Add this folder to your project in order to be able to create and edit the content easily. To do this, choose New > Folder.

5. In the wizard, select Advanced and then select Link to folder in the file system (see Figure 4). On my computer, the Apache web root is c:\htdocs, so for the folder path I typed c:\htdocs\updater. In this folder you will place the updater descriptor file and the application's AIR file.

   

   Figure 4. Creating the link resource

Creating the Flex code

With all the bits in place, it is time to add the ActionScript to implement the update feature:

1. Open the application file air_updater_flex.mxml and add a handler called checkUpdate for the event creationComplete of the WindowedApplication:

   <?xml version="1.0" encoding="utf-8"?>
   <mx:WindowedApplication xmlns:mx="/2006/mxml" layout="absolute" creationComplete="checkUpdate()">

   The function checkUpdate will be called every time the application is loaded.

2. Add the remaining code for air_updater_flex.mxml shown below:

   <mx:Script>
       <![CDATA[
           import air.update.events.UpdateEvent;
           import mx.controls.Alert;
           import flash.events.ErrorEvent;
           import air.update.ApplicationUpdaterUI;
    
   /**
    * @var the object that that handles the update related actions
    */ 
   private var appUpdater:ApplicationUpdaterUI = new ApplicationUpdaterUI();
    
   /**
    * This function is triggered when the application finished to load;
    * Here we initialize <code>appUpdater</code> and set some properties
    */ 
   private function checkUpdate():void {
       setApplicationVersion();
       // we set the URL for the update.xml file 
       appUpdater.updateURL = "http://localhost/updater/update.xml";
       //we set the event handlers for INITIALIZED nad ERROR
       appUpdater.addEventListener(UpdateEvent.INITIALIZED, onUpdate);
       appUpdater.addEventListener(ErrorEvent.ERROR, onError);
       //we can hide the dialog asking for permission for checking for a new update;
       //if you want to see it just leave the default value (or set true).
       appUpdater.isCheckForUpdateVisible = false;
       //if isFileUpdateVisible is set to true, File Update, File No Update, 
       //and File Error dialog boxes will be displayed
       appUpdater.isFileUpdateVisible = false;
       //if isInstallUpdateVisible is set to true, the dialog box for installing the update is visible
       appUpdater.isInstallUpdateVisible = false;
       //we initialize the updater
       appUpdater.initialize();
   }
    
   /**
    * Handler function triggered by the ApplicationUpdater.initialize;
    * The updater was initialized and it is ready to take commands 
    * (such as <code>checkNow()</code>
    * @param UpdateEvent 
    */ 
   private function onUpdate(event:UpdateEvent):void {
       //start the process of checking for a new update and to install
       appUpdater.checkNow();
   }
    
   /**
    * Handler function for error events triggered by the ApplicationUpdater.initialize
    * @param ErrorEvent 
    */ 
   private function onError(event:ErrorEvent):void {
       Alert.show(event.toString());
   }
    
   /**
    * A simple code just to read the current version of the application 
    * and display it in a label. 
    */ 
   private function setApplicationVersion():void {
       var appXML:XML = NativeApplication.nativeApplication.applicationDescriptor;
       var ns:Namespace = appXML.namespace();
       lblAppVersion.text = "App version:" + appXML.ns::version;
   }
       ]]>
   </mx:Script>

In this code, you add an mx:script tag and create a variable appUpdater that will keep a reference to the updater object (this object will be your interface to the framework). Then create the function checkUpdate(), which will be in charge of initializing and setting some values needed by the updater object. The updateURL property tells the updater where to find the updater descriptor file (you will create this file later). If you don't set the updateURL property correctly, the update will not work.

Next, you'll need to register two functions for the error event and initialized event. If the isCheckForUpdateVisible property is true, then the user is given the option to check for a new version or not. In this case, set it to false, which will bypass this dialog box when checking for a new version. The last function call, appUpdater.initialize(), does exactly what the name implies. When the updater is initialized it calls the listener you have registered for the initialize event, and inside this listener you start the process of checking for a new version.

The next two functions are the implementations for the event listeners for the error and initialize events. Once the onUpdate() listener gets called, it means the updater was initialized and it is ready to take commands. The onUpdate() function calls the method checkNow() on the updater, starting the update process.

The last function, setApplicationVersion(), just reads the current version of the app and displays it using a label.

Finally, add a label component to display the current version of the application:

<mx:VBox>
    <mx:Label id="lblAppVersion" width="300"/>
</mx:VBox>

Creating the updater descriptor file

You have all the code in the application in place; now it is time to put in place the bits you need on the server. First create the file update.xml inside the updater folder from the project:

<?xml version="1.0" encoding="utf-8"?>
<update xmlns="http://ns.adobe.com/air/framework/update/description/1.0">
    <version>2.9</version>
    <url>http://localhost/updater/air_updater_flex.air</url>
    <description><![CDATA[
         This version has fixes for the following known issues:
         *First issue
         *Second issue   
  ]]></description>
</update>

This file lets you define the URL where the new version of the application can be downloaded, set the version number, and specify the description text you want to display to the user.

Testing the code

All the code is in place but you are not finished yet. It is very important not to forget this: in order for the update to work you need to carefully set the same version number in two files—the updater descriptor file and the application descriptor (in my case, air_updater_flex-app.xml). In both these files you will find a version tag; what you put here needs to be exactly the same.

First, export the existing AIR application for release, and then install it. Now, you are ready to test the update:

1. Open the update.xml file and application descriptor file (air_updater_flex-app.xml). In both files set the same version number (make sure it is higher than the current one), for example 2.9.
2. Export the project for release and place it in the same folder as the update.xml file on your web server.

3. Finally, start the application. You should see a dialog box (example in Figure 5).

Figure 5. The Adobe AIR update framework in action

Page 3 of 5

Previous Page

Next Page