This chapter discusses how to start developing applications for Adobe AIR using HTML and JavaScript. It covers:

• Installing Adobe AIR
• Configuring the Flex SDK and command-line tools
• Creating your first AIR application with the Flex SDK and Flex Builder 3
• Testing AIR applications
• Signing, packaging, and deploying AIR applications

Once you have completed this chapter, your environment for developing AIR applications should be configured correctly, and you should have a solid understanding of how to begin to build, test, and deploy Adobe AIR applications.

What Do You Need to Develop Adobe AIR Applications?

You need a number of items to begin developing AIR applications.

Adobe AIR Runtime

The Adobe AIR runtime is required to test application icons and install AIR applications. You can download the runtime for free from http://www.adobe.com/go/getair.

However, it is not required for general AIR application development.

Adobe Flex SDK

The free and open source Adobe Flex SDK contains all of the tools, libraries and other files that you need to develop, test, compile and deploy Flex based AIR (as well as browser) applications. In particular, it contains command line tools that allow the development, testing and deploying Flex based AIR applications from the command line, which allows development to do from virtually any text editor or IDE.

Currently the Flex 3 SDK has support for AIR 1.0 and not AIR 1.1. For AIR 1.1 development, you must use the 3.0.2 version of the Flex SDK.

You can download the Flex 3.0.2 SDK from http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+3

The Flex SDK 3.1 release is planned for mid-August 2008, and will contain complete support for AIR 1.1.

This book assumes that the Flex 3.0.2 SDK is being used.

Adobe AIR SDK

There is also an Adobe AIR SDK, which is targeted at developers building AIR applications with HTML and JavaScript, and which contains command-line tools, sample files, and other resources. In general, the Flex SDK contains all of the files from the AIR SDK. However, there are two cases where you may want to download both the AIR and Flex SDKs:

1. The AIR SDKs contains files and libraries targeted at making HTML and JavaScript based development for Adobe AIR easier. If your Flex based AIR application also contains HTML content, then you will probably want to download the Adobe AIR SDK.

   We will be using files from the AIR SDK later in the book.

2. If the Adobe AIR SDK is updated separately from the Flex SDK, then you can download the AIR SDK, and manually update the AIR support in the Flex SDK by copying files over from the AIR to the Flex SDK.

   As of the time that this was written, this step is not necessary.

You can download the AIR SDK for free from http://www.adobe.com/go/getairsdk.

Flex Builder 3 or another Flash or text IDE

If you are going to use the Flex SDK to develop your Flex based AIR application, then all you need is a text editor to create the MXML and ActionScript source files. You can simply develop the source files in a text editor (such as notepad or VIM) and then use the Flex SDK to compile, test and package your AIR application.

However, if you are going to be doing extensive Flex development, or you just want a richer development experience, you may want to leverage an IDE designed specifically for developing Flex and / or Flash applications.

Adobe Flex Builder 3 is a full featured, Eclipse based IDE for developing Flex based applications that contains full support for building both browser, and AIR based Flex applications. Flex Builder provides a number of features that make development much easier than using just a text editor. Some of these features include:

• Generate projects, and default application files.
• Visually layout UI using a design view.
• Full featured code editor, with code complete introspection and completion.
• Launch, debug and profile applications from with the IDE.
• Package AIR file to distribute the AIR application.
• Extend the IDE via Eclipse plugins.

In addition to showing how to develop AIR applications using just the SDK, we will also show how to build AIR applications using Flex Builder.

Flex Builder is available as both a standalone IDE and as an Eclipse plugin. You can download a fully functional free trial of Flex Builder 3 from http://www.adobe.com/go/flex_trial

Supported Operating Systems

Although it is possible to develop and package AIR applications on virtually any operating system (including Linux) using the Flex SDK, you can only test and deploy AIR applications on operating systems supported by Adobe AIR.

Adobe AIR 1.1 is supported on the following operating systems:

• Microsoft Windows XP SP2
• Microsoft Windows XP Tablet PC Edition
• Microsoft Windows Vista Home, Premium, Business, Ultimate and Enterprise (including 64-Bit editions)
• Microsoft Windows 2000 SP4
• Windows 2003 Server
• Mac OS 10.4.11 (Intel and PowerPC)
• Mac OS 10.5.2 (Intel and PowerPC)

Installing Adobe AIR

Although it is not necessary to have Adobe AIR installed on your computer to develop and test Adobe AIR applications, it is useful to have it to try other AIR applications and to test your final application's deployment and packaging.

Installing the runtime is simple, and requires downloading and running the Adobe AIR Installer.

1. Download the Adobe AIR Installer from http://www.adobe.com/go/getair.
2. Launch the installer. On a Mac, you must first mount the .dmg file, which contains the installer.
3. Follow the installation instructions.

As Adobe AIR is simply a runtime and not an application that can be launched, the easiest way to confirm that it is installed correctly is to try installing an AIR application. You can do this by either downloading an AIR application and installing it, or following the instructions later in the chapter to build a simple AIR application.

Uninstalling Adobe AIR

The process for uninstalling Adobe AIR is different depending on your operating system.

Uninstalling on Windows

On Windows, you can uninstall Adobe AIR the same way that you uninstall any other application. Just select Adobe AIR in the Add/Remove Programs section of the Control Panel.

Uninstalling on an Mac

The Adobe AIR installer places an uninstall application on the user's system when it is installed. To uninstall Adobe AIR, launch the uninstaller named Adobe AIR Uninstaller which you can find in the /Applications/Utilities directory.

Setting Up the Flex SDK and command line tools

The Adobe Flex SDK contains tools, samples, and code that make it possible to develop, test, and deploy applications from the command line (and thus from virtually any text editor or IDE). In particular, it contains a number of command-line tools that we will use (listed in table 2-1):

Table 2-1 Command Line Tools used to develop AIR Applications

Tool	Description
ADL	Launches AIR applications without having to install them first.
ADT	Packages and signs AIR applications into AIR files for distribution.
AMXMLC	A wrapper for the Flex command line compiler (mxmlc) that links in the ActionScript libraries for Adobe AIR development.

Installing the Adobe Flex 3 SDK

As discussed above, the Adobe Flex 3 SDK contains a number of command line tools that we will need to develop, test and package our Flex based AIR applications from the command-line.

To ease development, we will install the SDK, and place the command-line tools into the system's path, in order to allow the tools to be executed from anywhere by name.

Installing the SDK

The command-line tools are located in the bin directory within the SDK.

1. Download the Adobe Flex 3 SDK from http://www.adobe.com/go/flex3_sdk.
2. The SDK is a zip file. Uncompress this file.
3. Copy the contents of the SDK to a permanent location on your system (we will refer to this location as *<SDK_Path>*).
4. At this point, the SDK should be copied into *<SDK_Path> with the directories within the SDK containained with the <SDK_Path> like so: <SDK_Path>/bin, <SDK_Path>/frameworks, <SDK_Path>/lib and <SDK_Path>/runtimes*, etc... The ADL, ADT and AMXMLC command-line tools are located in the bin directory.

Placing the Command-Line Tools Within the System Path

All that is left to do is to place the *<SDK_Path>/bin* directory into your system path so that you can execute the command-line tools from anywhere on your system.

The instructions for this are different depending on whether you are on a Mac or Windows-based system.

Windows

If you are on a Windows system, follow these steps:

1. Open the System Properties dialog box and click the Advanced tab. You can find this in the System settings in the Control Panel. On Vista you can find this in Control Panel > System > Advanced Settings.

2. Click the Environment Variables... button.

3. In the System Variables section, select the PATH entry and then click the *Edit button. Add the path to the <SDK_Path>/bin* directory to the end of the current variable value, separating it from previous values with a semicolon:

   ; <SDK_Path>\bin
   

   For example, if you had placed the sdk in the *c:flexsdk\* directory, then you would enter:

   ; c:\flexsdk\bin\
   

4. Click OK to close the panels.

   [IMAGE] Figure 2-1. Placing command-line tools in the system path on Windows

5. To test the installation, open a new Windows Console (Start > Run > Console), and run the following command:

   adt.

   You should see output similar to this:

   No arguments were found
   usage:
     adt -checkstore SIGNING_OPTIONS
     adt -certificate -cn <name> ( -ou <org-unit> )? ( -o <org-name> )? ( -c <country> )? <key-type> <pfx-file> <password>
     adt -help
     adt -migrate SIGNING_OTIONS <air-file-in> <air-file-out>
     adt -package SIGNING_OPTIONS <air-file> <app-desc> FILE_ARGS
     adt -prepare <airi-file> <app-desc> FILE_ARGS
     adt -sign SIGNING_OPTIONS <airi-file> <air-file>
     adt -version
   
   SIGNING_OPTIONS: -storetype <type> ( -keystore <store> )? ( -storepass <pass> )? ( -keypass <pass> )? ( -providerName <name> )? ( -tsa <url> )?
   FILE_ARGS: <fileOrDir>* (( -C <dir> <fileOrDir>+ ) | ( -e <file> <path> ))*
   

   This means the tools are configured correctly.

If you get an error check the following:

• Make sure you copied all of the contents and directories of the Flex SDK onto your system, making sure to maintain their relative paths to each other.
• Make sure you included the path to the *<SDK_Path>* directory correctly in the PATH environment variable.
• Make sure you opened a new Console window before running the command.

Mac and Linux

There are a number of ways to add the path to the AIR SDK to your system path, depending on which shell you are using and how you specify user environment variables.

The following instructions explain how to modify your PATH environment variable if you are using the bash shell:

1. Open the Terminal program (on Mac OS X it can be found at /Applications/Utilities/Terminal).

2. Make sure you're in your home directory by typing cd and pressing Enter.

3. Check to see whether one of two files is present. Enter the command:

   ls -la.

4. Look for a file named either .profile or .bashrc.

5. If you have neither file, create the .profile file with the command:

   touch .profile.

6. Open the .profile or .bashrc file with a text editor.

7. Look for a line that looks similar to this:

   export PATH=$PATH:/usr/local/bin
   

8. Add the path to the *`/bin* directory to the end of this line. For example, if */bin'* is at /airsdk/bin, the export path should look something like this:

   export PATH=$PATH:/usr/local/bin:/airsdk/bin
   

   Make sure you separate the entries with a colon.

9. If the file is empty, add the following line:

   export PATH=$PATH:/airsdk/bin
   

10. Save and close the file.

11. Run the command source .profile to load the new settings (or .bashrc, if that is the file you edited).

12. To test the installation, open a Terminal window and type:

    adt.

    You should see output similar to this:

    No arguments were found
    usage:
      adt -checkstore SIGNING_OPTIONS
      adt -certificate -cn <name> ( -ou <org-unit> )? ( -o <org-name> )? ( -c <country> )? <key-type> <pfx-file> <password>
      adt -help
      adt -migrate SIGNING_OTIONS <air-file-in> <air-file-out>
      adt -package SIGNING_OPTIONS <air-file> <app-desc> FILE_ARGS
      adt -prepare <airi-file> <app-desc> FILE_ARGS
      adt -sign SIGNING_OPTIONS <airi-file> <air-file>
      adt -version
    
    SIGNING_OPTIONS: -storetype <type> ( -keystore <store> )? ( -storepass <pass> )? ( -keypass <pass> )? ( -providerName <name> )? ( -tsa <url> )?
    FILE_ARGS: <fileOrDir>* (( -C <dir> <fileOrDir>+ ) | ( -e <file> <path> ))*
    

This means the tools are configured correctly.

If you get an error check the following:

• Make sure you copied all of of the contents and directories of the Flex SDK onto your system, making sure to maintain their relative paths to each other.
• Make sure you included the path to the *<SDK_Path>/bin* directory correctly in the PATH environment variable.
• Make sure you either opened a new Terminal window, or ran source on your configuration file.

Checking the version of Adobe AIR

Once you have installed and configured the Flex SDK, you can check and confirm the version of Adobe AIR included in the SDK with the following command:

adt -version

If the SDK contains Adobe AIR 1.1 or above, you will see output similar to:

adt version "1.1.0.5780"

If the SDK contains a version of Adobe AIR older than 1.1, the -version argument is not supported, and you will see output similar to this:

unexpected argument -version

Building an AIR application

The process for developing a Flex based AIR application can be divided into four primary parts:

1. Create the application descriptor file.
2. Design and develop the application.
3. Test and debug the application.
4. Sign and create an AIR file for distribution.

AIR Application Descriptor File

The application descriptor file is an XML file required by all AIR applications. It contains both meta data about the application, such as name, description, etc..., as well as information on how the application should be launched and displayed.

When using Flex Builder to build an AIR application, Flex Builder will generate a fully commented application descriptor file for you. The Flex SDK also contains a fully commented application descriptor file template, which you can find in the SDK at *''air/templates/descriptor-template.xml*.

Both examples below will use the following application descriptor file:

<?xml version="1.0" encoding="utf-8" ?>
<application xmlns="http://ns.adobe.com/air/application/1.1">

    <id>com.oreilly.helloworld</id>
    <filename>HelloWorld</filename>
    <name>Hello World</name>
    <version>.85</version>

    <initialWindow>
        <content>HelloWorld.swf</content>
        <systemChrome>standard</systemChrome>
        <transparent>false</transparent>
        <visible>true</visible>
    </initialWindow>

</application>

To learn more about the options available within the application descriptor file, view the comments in the file, or read the Adobe AIR documentation.

Table 2-2 describes each top level element and its value:

Table 2-2 Hello World Application Descriptor file elements

Element	Description
id	The id element is a machine readable string (end users never see it) that uniquely identifies the application per publisher (which is determined by the certificate that the application is signed with). As a general rule, it is recommended that you use a reverse domain notation, similar to what is used in ActionScript packages.
filename	The name of the native executable file that will be created for the application when it is installed.
name	The human readable name of the application. This is the name that the end user will see for the application.
version	A String that is made available to the application at runtime, and can be used to determine whether the running version of the application is the most current version.

The intialWindow element contains additional elements that describe how the application window should be constructed when the application is launched. Table 2-3 describes the elements and their values that we use in our application descriptor file.

Table 2-3 Hello World initialWindow elements

Element	Description
content	This specifies the root content file of your application. Basically, this is the main application file.
systemChrome	Specifies whether the application window should use the operating system's standard system chrome (true) or just present an opaque region with no windowing controls for the application (false)
transparent	If the systemChrome element is set to false, this specifies whether the background of the application should be rendered by the runtime. This allows for the creation of custom chrome, and non-standard shaped UIs.
visible	Specifies whether the application is visible when it first starts. This defaults to false, which means the application will not be visible. This is useful if you need to do some application initialization prior to displaying the UI to the user.

AIR Files

An AIR file is a ZIP-based application distribution package that is used to distribute AIR applications. It contains all of the files necessary to install and run an AIR application, and Adobe AIR uses it to create and install an AIR application onto the user's system.

When using the Flex or AIR SDKs, AIR files are created using the ADT tool which is included in the SDKs.

An AIR file requires a minimum of two files: the application descriptor file and the root application file. However, you can also include other files, icons, directories, and assets that will be bundled with the AIR file and installed alongside your application. These files will then be available to the application at runtime.

In addition, you will also need a certificate to digitally sign your application.

Digitally Signing AIR Files

Adobe AIR requires that all AIR files be digitally signed. There are two ways to do this.

This provides a level of security by:

• Ensuring that the AIR file is not tampered with between the time it was created, and the time it is installed.
• If the AIR file is signed using a digital certificate from a trusted source (such as a Certificate Authority), then Adobe AIR can verify the publisher of the AIR file.

ADT provides two options for signing AIR files. You can either sign with a self signed certificate, which provides a minimal level of security, or you can sign your application with a digital certificate issued from a trusted certificate authority, which provides a higher level of security. Both options are discussed below.

Signing with a self-signed certificate

Developers can use ADT to digitally sign an AIR file with a self-signed certificate. You self-sign an AIR file by generating a self-signed certificate, and then signing the AIR file with it. While self signing AIR files does help the runtime determine if the AIR file has been tampered with, it does not provide the ability for the runtime to verify the author of the AIR file. When the application is installed, Adobe AIR will warn users that the publisher of the application cannot be verified.

AIR files signed with self-signed certificates are meant primarily for development purposes. If you plan to widely distribute your application to the public, you should sign your application with a certificate issued by a respected and well-known Certification authority (CA).

Signing with a CA-issued certificate

ADT also has support for signing applications using a verified certificate from an established CA. This allows Adobe AIR to verify the publisher of the application, and to reflect this information in the installation dialog.

With both types of certificates-self-signed and CA-issued-Adobe AIR can verify that the AIR file has not been tampered with.

Building a Hello World AIR application

This chapter walks you through these steps using a very simple Hello World example. Following these steps will help you verify that your AIR development environment is working. When you are done, you will have written a simple AIR application, and can be sure that your development environment is set up and configured correctly.

After building this simple application, you should be familiar with the following:

• How to write basic MXML code for an AIR application
• How to test and debug the application
• How to package the application into a distributable AIR file, which can be distributed to users for installation on their computers

The steps for building and debugging are different depending on whether you are using the Flex Builder tool or the Flex SDK. We will cover each scenario in its own section below.

Building your first AIR application with the Flex SDK

As discussed above, the Adobe Flex SDK contains all of the tools and files needed to build, test and deploy Flex based AIR applications from the command line. Among other things, this means that you can develop Flex based AIR applications using any editor or IDE that can work with text files.

This section will show how to build a Flex based AIR application using the Flex SDK. The next section will show how to use Flex Builder to build an AIR application.

Before starting, make sure that you have followed the instructions above to install the Flex SDK, and that you have confirmed that the system and SDK tools are configured correctly.

1. Create a new directory on your file system. This directory will contain all of the source files for the project. We refer to this directory as your project directory.

2. Copy the application descriptor file template from the Flex SDK (*''air/templates/descriptor-template.xml*) into the project directory and rename it to application.xml.

3. We don't need to set all of the elements in the application descriptor file, and can just ignore the one we don't need. Open the application.xml file and edit it so that it contains the values specified below (you can also just replace the entire template with the example below):

   <?xml version="1.0" encoding="utf-8" ?>
   <application xmlns="http://ns.adobe.com/air/application/1.1">
       <id>com.oreilly.helloworld</id>
       <filename>HelloWorld</filename>
       <name>Hello World</name>
       <version>.85</version>
       <initialWindow>
           <content>HelloWorld.swf</content>
           <systemChrome>standard</systemChrome>
           <transparent>false</transparent>
           <visible>true</visible>
       </initialWindow>
   </application>
   

4. Save the changes to the application.xml file.

Once we have created the application descriptor file, we are ready to write the code for our application.

1. Create a new file in the project directory named HelloWorld.mxml and open it with a text editor.

2. Add the following code to the file:

   <?xml version="1.0" encoding="utf-8"?>
   <mx:WindowedApplication 
       xmlns:mx="http://www.adobe.com/2006/mxml" 
       layout="absolute">
       <mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/>
   </mx:WindowedApplication>
   

   This defines the MXML source code for the application:

   • The WindowedApplication component is a subclass of the Flex Application component. It represents an application running within a native window on the desktop, and provides additional events and APIs to work with the window.
   • The Label component is used to display "Hello World".

3. Save the file.

At this point, we are ready to compile our source file into a SWF file. This is done using the amxmlc command which is included in the Flex SDK. The command is a wrapper for the mxmlc compiler (also included in the SDK), and links in the libraries for all of the Adobe AIR classes and components.

1. Open the Terminal application on Mac or Linux or the Command Prompt in Windows.

2. Navigate to inside the project directory.

3. Run the following command:

   amxmlc HelloWorld.mxml

4. You should see output similar to:

   Loading configuration file /Users/mesh/bin/flex/frameworks/air-config.xml
   /Users/mesh//helloworld_sdk/HelloWorld.swf (249753 bytes)
   

   This indicates that the application was successfully compiled. If you get any errors, then fix them in your source code, and compile the application again.

At this point, we have three files. HelloWorld.mxml, HelloWorld.swf and application.xml. HelloWorld.swf and application.xml make up our AIR application and are ready to be run and tested as an AIR application.

Now you can test the application, using the ADL tool which is included in the SDK:

1. Open the Terminal application on Mac or Linux or the Command Prompt in Windows.

2. Make sure that you are inside your project directory.

3. Run the following command:

   adl application.xml

4. This should launch the application within a native window with the operating systems standard system chrome.

   [IMAGE] Figure 2-3 Hello World

If you get any errors, then make sure you have entered the information in the application.xml file, and then try again.

Capturing Output from the Application at Runtime

When running applications from the command line via ADL, any runtime errors, or data passed to the ActionScript trace method will be displayed on the command line that launched the application.

Let's modify our application to send a string to the command line when the application starts. Change the contents of HelloWorld.mxml to the following

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="absolute"
    creationComplete="onCreationComplete()"
    >

    <mx:Script>
        <![CDATA[
            private function onCreationComplete():void
            {
                trace("Application Creation Complete");
            }
        ]]>
    </mx:Script>

    <mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/>

</mx:WindowedApplication>

The only change we made was to register for the creationComplete event broadcast by the WindowedApplication component. When the event is broadcast we use the trace function to print out a string to the command line.

Save the file, and run the application from ADL:

adl application.xml

The application should launch, and you should see the following string printed out in the Terminal:

Application Creation Complete

This functionality can be used to help test the application while it is running.

Packaging and Deploying the AIR Application with ADT

Now that we understand how to build and test an AIR application using the SDK, we are ready to create an AIR file that will allow us to deploy and distribute our application.

Because we will not be redistributing the application we are creating, we will be signing our AIR file with a self-signed certificate.

Creating an AIR File Using ADT

Creating a self-signed AIR file requires only two steps:

1. Use ADT to create a self-signed certificate.
2. User ADT to create the AIR file, digitally signed with the self-signed certificate.

Generating a self-signed certificate

Before signing an AIR file with a self-signed certificate, we need to first generate the certificate.

We can use ADT to generate a self-signed certificate with the following command-line options:

adt -certificate -cn COMMONNAME KEYTYPE CERTFILE PASSWORD

Table 2-4 lists and explains these command-line options.

Table 2-4. ADT Signing Options

Command-line option	Explanation
COMMONNAME	The common name of the new certificate. This is the name associated with the certificate.
KEYTYPE	The type of key to use for the certificate, either 1024-RSA or 2048-RSA.
CERTFILE	The filename in which the certificate will be stored.
PASSWORD	The password for the certificate.

To generate a self-signed certificate, follow these steps:

1. Open a Terminal (Mac OS X / Linux) or Console (Windows) window.

2. Make sure that you are in the project directory.

3. Run the following command:

   adt -certificate -cn foo 1024-RSA test_cert.p12 mypass

For this example, we will give the certificate a common name of "foo" with a password of "mypass".

This generates a self-signed certificate, and stores it in a file named test_cert.p12.

At this point, you should have a file named test_cert.p12 in the same directory as your application files. You can now use this file to digitally self-sign your AIR file.

Generating an AIR file

The ADT command-line tool included in the Adobe AIR SDK is used to create AIR files. Its usage format is:

adt -package SIGNINGOPTIONS AIRFILENAME FILESTOINCLUDE

To create an AIR file that is signed with a self-signed certificate, follow these steps:

1. Open a Terminal (Mac OS X / Linux) or Console (Windows) window.

2. Make sure that you are in the project directory.

3. Run the following command:

   adt -package -storetype pkcs12 -keystore test_cert.p12 HelloWorld.air application.xml HelloWorld.swf

4. Upon running the command, you should be prompted for the password for the certificate that the AIR file is being signed with. Enter the password for the certificate, which for this example is "mypass".

This should create a file named HelloWorld.air in your project directory. If the file is not created, or if you receive any errors, check the following:

• Make sure you have configured the SDK correctly, and that the ADT tool can be found on your system's path.
• Make sure you are running the ADT command from your project directory.
• Make sure your application descriptor file is valid.
• Make sure the HelloWorld.swf, test_cert.p12, and HelloWorld.xml files are all in the project directory.
• Make sure you entered the same password you used when generating the certificate file.

At this point, you now have a valid AIR file, which can be used to install your AIR application.

Building a HelloWorld AIR application in Flex Builder 3

Flex Builder 3 is a full featured IDE for ActionScript and Flex development. It includes full support for developing, testing, debugging and packaging AIR applications.

Creating an AIR application in Flex Builder is similar to creating a Flex application for the Web.

If you do not already have Flex Builder, you can download either a full featured trial (both standalone, and Eclipse plugin based) from: http:///www.adobe.com/go/flex_trial/

1. Open Flex Builder.
2. Select `File > New > Flex Project'. The "New Flex Project" dialog is displayed.
3. For the Project Name enter HelloWorld. Select a location to save your files (you can just use the default location by checking Use default location). Make sure that Application type is set to Desktop application (runs in Adobe AIR).
4. Click Finish. (If you click Next you can set other projects settings, which we do not need to modify for this example).

This will create a new AIR project named HelloWorld. It will also auto-generate two files for you in the /src sub-folder of your project.

Table 2-3 Flex Builder AIR Project Autogenerated Files

File	Description
HelloWorld-app.xml	The application descriptor file for the application. This file is fully commented and contains all possible options.
HelloWorld.mxml	The source file for the root content file for the application. This is the main application file.

Next we will enter the data into the application descriptor file for our application, using the settings discussed in the "Air Application Descriptor File" section above.

1. Open the HelloWorld-app.xml file by double clicking on it.

2. You can either replace the entire contents of the file with the XML below, or use the XML below to enter the data into the existing application descriptor file:

   <?xml version="1.0" encoding="utf-8" ?>
   <application xmlns="http://ns.adobe.com/air/application/1.1">
       <id>com.oreilly.helloworld</id>
       <filename>HelloWorld</filename>
       <name>Hello World</name>
       <version>.85</version>
       <initialWindow>
           <content>HelloWorld.swf</content>
           <systemChrome>standard</systemChrome>
           <transparent>false</transparent>
           <visible>true</visible>
       </initialWindow>
   </application>
   

   NOTE

   Make sure that the application tag specifies AIR 1.1. It should be:

   <application xmlns="http://ns.adobe.com/air/application/1.1">

   
   

   If you choose to use the auto-generated application descriptor file, then your file will contain the information above, as well as all of the commented elements which we will not be using.

3. Save the file by selecting File > Save.

At this point, we can test our application to make sure that we have created a valid application descriptor file. To test it, we can simply debug the application.

1. Select Run > Debug HelloWorld

   The application should launch, with no errors.

   If you receive an error, make sure that you have entered the information correctly in the application descriptor file, and that the file contains valid XML. Once you have done this, test the application again to confirm that the file is correct.

Now that we have created a valid application descriptor file for our application, we are ready to build out the rest of the example.

Now that the AIR project has been set up, you can write the MXML code for this application:

1. 1. Open the auto-generated HelloWorld.mxml file by double clicking on it. It should look something like this:

      <?xml version="1.0" encoding="utf-8"?>

2. Modify the file by adding a label component.:

       <?xml version="1.0" encoding="utf-8"?>
       <mx:WindowedApplication 
           xmlns:mx="http://www.adobe.com/2006/mxml" 
           layout="absolute">
           <mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/>
       </mx:WindowedApplication>
   

   This defines the MXML source code for the application:

   • The WindowedApplication component is a subclass of the Flex Application component. It represents an application running within a native window on the desktop, and provides additional events and APIs to work with the window.
   • The Label component is used to display "Hello World".

3. Save the file by selecting File > Save.

We are now ready to test our application.

1. Select Run > Debug HelloWorld

   The application should run, and look similar to Figure 2-2 (with the exact window chrome will depend on the operating system that you are developing on).

   [IMAGE] Figure 2-2 Hello World

If the application does not launch, check the following:

• Any compile errors will be displayed in the "Problems" panel, which can be opened by selecting Windows > Problems.
• Any runtime errors, or information sent to the trace function will be displayed in the "Console" panel, which can be opened by selecting Window > Console
• If a runtime error occurs while debugging the application, Flex Builder will switch to the debug profile, and you will be able to debug the application. You can also manually set breakpoints. Both of these topics are beyond the scope of this book.

Fix any errors, and debug the application again. Once everything is running, then we are ready to package our application into an AIR file for distribution.

Packaging and Distributing the Hello World Application

As discussed above in the "Packaging and Deploying the AIR Application" section above, all AIR applications are distributed as AIR files. An AIR file is a zip based package format that contains all of the files and information needed to install an AIR application on the user's system.

Flex Builder has built in support for creating and signing AIR files.

There are two primary steps when creating an AIR file in Flex Builder:

1. Specifying information about the AIR file, including the name, and which files it will include.
2. Signing the AIR file (either with a self-signed certificate, or a certificate issued by a Certificate Authority)

Creating and signing an AIR File in Flex Builder

1. Make sure that your project is selected in the "Flex Navigator" panel, and select Project > Export Release Build...*

2. This will open the "Export Release Builder" dialog. By default, the generated AIR file will be named HelloWorld.air and placed in the project directory.

3. Click the Next button which will take you the the "Digital Signature" dialog.

   Since this is not a production application, we will generate a self-signed certificate to sign our application with.

4. Make sure that the Export and sign an AIR file with a digital certificate radio button is selected.

5. Since this is the first time we are creating an application, we need to generate a self signed certificate. Click the Create... button.

   If you had created an AIR application, and self signed certificate before, then you would been able to browse to that certificate, enter the password for it, and then skip ahead to step 11.

6. For the Publisher name enter your name.

7. Select 1024-RSA for the encryption type.

8. Enter a password in the Password and Confirm password fields. This password will be used when signing the AIR file with the generated certificate.

9. Select a location to save the generated certificate. We will refer to this as *<CERTIFICATE_PATH>*

10. Click OK.

    The dialog will close, and you will be back at the Digital Signature dialog, with the information from the generated certificate filled in.

11. If you are currently online, then make sure that the Timestamp option is checked. Otherwise, uncheck it.

    NOTE

    When signing the AIR file, Flex Builder will attempt to connect to a timeserver on the Internet to timestamp the AIR file. If it cannot connect to the timeserver, you will receive an error.

    When developing and self-signing your AIR files, you can get around this error by telling Flex Builder to not timestamp the AIR file by unchecking the Timestamp Checkbox.

    However, if you disable the timestamp, the AIR file will no longer be installable when / if the certificate expires. In general, for production use, you should not disable time-stamping.

12. Click the Next... button.

    If you receive an error, make sure that:

    • The Certificate setting is pointing to the certificate that you just created.
    • The password for the certificate is entered correctly.

    This will switch to the AIR File Contents dialog, which allows us to select which files will be included in our AIR file.

13. Notice that both the application descriptor file, and HelloWorld.swf file are checked, and cannot be unchecked. This is because they are both required by the AIR file. The HelloWorld.swf file is the compiled application, generated from the HelloWorld.mxml source file which we created.

    If you wanted to include additional files or folders within the AIR file, you could do so, by copying them into the project directory, and then adding them in this dialog. The files and / or folders would be included in the AIR file, and then copied into the application directory when the application is installed on the user's system. The application could then reference those files at runtime.

14. Click the Finish button. This will generate an AIR file called HelloWorld.air in your project directory (or wherever you set the file to be saved).

If you have installed the Adobe AIR runtime, you can install your application by double clicking the HelloWorld.air file that you just created.

Distributing and installing your application

There are two primary ways to distribute an AIR application.

1. Distribute the AIR file via a web server, email, dvd, etc... This requires that the user has already installed the Adobe AIR runtime.

2. Use the badge install from a web page. If the user does not already have Adobe AIR installed, it will first prompt the user to install it, and then install the application. This will be discussed in the cookbook chapter.

   You can also find information on using the badge install at http://www.adobe.com/devnet/air/articles/air_badge_install.html.

Setting the MIME type

One thing to watch out for when distributing AIR files for download from a web server is that the MIME type is set correctly on the server. If the MIME type is not set correctly, web browsers may treat the AIR file as a ZIP file (and may rename it in the process), or may display the raw bytes of the AIR file in the browser, instead of downloading it to the user's system.

The correct MIME type for an AIR file is:

application/vnd.adobe.air-application-installer-package+zip

For example, to set the MIME type for the Apache server, you would add the following line to your Apache configuration file:

AddType application/vnd.adobe.air-application-installerpackage+zip .air

Check the documentation for your web server for specific instructions on how to set the MIME type.

Next Steps

At this point, you have all of the basic knowledge of how to develop, test, and deploy AIR applications. You should now be ready to begin to learn more about the AIR APIs and how to build more full-featured and advanced applications.