2.6. Creating a Simple AIR Application with HTML and JavaScript

Now that we have installed and configured Adobe AIR and the Adobe AIR SDK, we are ready to build our first AIR application.

We will build a very simple "Hello World" example. Once we have built and tested the application, our development environment will be set up and ready to build more complex and functional AIR applications.

2.6.1. Creating the Application Files

Every Adobe AIR application contains a minimum of two files. The first file is the root content file. This is the main HTML or SWF file for the application, and is the file that will be displayed/executed when the application first starts up.

The second file is called the application descriptor file, and it is an XML file that provides metadata to Adobe AIR about the application.

Let's create these files for our application:

2.6.1.1. Understanding application descriptor files

The application descriptor file is an XML file required for each AIR application. It provides general metadata (such as the application name and description) to Adobe AIR, as well as information on how the application should be run. This includes specifying the root application file for the application and the window mode that the initial application window should use.

First, let's look at the entire application descriptor file (AIRHelloWorld.xml) for our application, and then we will go into more detail regarding each item within the file.

Open AIRHelloWorld.xml and type in the following text:

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

    <id>com.oreilly.AIRHelloWorld</id>
    <filename>AIRHelloWorld</filename>
    <name>AIR Hello World</name>
    <description>A simple AIR hello world application</
    description> <version>1.0</version>

    <initialWindow>
         <content>AIRHelloWorld.html</content>
         <title>AIR Hello World</title>
         <systemChrome>standard</systemChrome>
         <transparent>false</transparent>
         <visible>true</visible>
         <minimizable>true</minimizable>
         <maximizable>true</maximizable>
         <resizable>true</resizable>
    </initialWindow>
</application>

The content should be pretty self-explanatory, but let's go through it line by line to understand what is going on.

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

The namespace specifies the version of Adobe AIR that the application targets—in this case 1.0.

Lets look at the next element:

    <id>com.oreilly.AIRHelloWorld</id>

The id element is important; it specifies a unique ID for the application. Adobe AIR uses this ID to differentiate one application from another.

As you can see, it uses the reverse domain format, which you may be familiar with from some programming languages such as Java, ActionScript, and some JavaScript frameworks. You can create your own ID using your domain name and application name.

The next section of elements specify general metadata about the application:

    <filename>AIRHelloWorld</filename>
    <name>AIR Hello World</name>
    <description>A simple AIR hello world application</
    description> <version>1.0</version>

Table 2-2 lists each element and provides a description.

Table 2-2. Application Meta Data Elements

Element	Description
filename	The name of the native application executable that will be created.
name	The name of the application. This is the name that will be exposed to the operating system and user.
description	Optional. A human-readable description of the application that will be presented to the user during the installation process.
version	Required. Specifies the version of the applications (such as "1.0", "v1", etc.).

The next element is the initialWindow tag, which contains the elements that specify how the application should be run by the runtime:

    <initialWindow>
         <content>AIRHelloWorld.html</content>
         <title>AIR Hello World</title>
         <systemChrome>standard</systemChrome>
         <transparent>false</transparent>
         <visible>true</visible>
         <minimizable>true</minimizable>
         <maximizable>true</maximizable>
         <resizable>true</resizable>
    </initialWindow>

The content element is required and points to the main root file of the application, which in this case is an HTML file.

The initialWindow element has a number of other elements that specify the initial window parameters and chrome of the application when it is first launched (see Table 2-3).

Table 2-3. initalWindow elements

Element	Description
title	The title that will appear in the main application window. Optional.
systemChrome	The type of the system chrome that the application should use (standard or none).
transparent	Whether the application background should be transparent. This option is applicable only if systemChrome is set to none. Optional. Default value is false.
visible	Whether the application is visible when it is first launched. This is useful if your application needs to perform some complex initialization before displaying the UI to the user. Optional. Default is false.
minimizable	Whether the application can be minimized. Optional. Default is true.
maximizable	Whether the application can be maximized. Optional. Default is true.
resizable	Whether the application can be resized. Optional. Default is true.

For our example, we will use the operating system's window chrome.

This is all that is required for the application descriptor file for our application. At this point, we are ready to create the main HTML file for our application.

2.6.1.2. Creating the root application file

The root application file is the main file for the application that will be loaded when the application is launched. This file can be either a compiled Flash file (SWF) or an HTML file.

For this chapter, we will create a very simple HTML file to ensure that our development environment is configured correctly. We will cover more advanced AIR API usage in Chapter 3 and Chapter 4.

<html>
<head>
    <title>AIRHelloWorld</title>

    <script>
        function init()
        {
            runtime.trace("init function called");
        }
    </script>

</head>
<body onload="init()">
    <div align="center">Hello World</div>
</body>
</html>

As you can see, this is a very basic HTML file that displays "Hello World" and calls a JavaScript function once the file has loaded and initialized.

A couple of lines are worth pointing out:

<body onload="init()">

This line says we are just using the standard onload event on the body element to get an entry point for JavaScript into our application.

    <script>
        function init()
        {
            ...
        }
    </script>

This line says we are using a standard JavaScript function to capture the onload event.

2.6.1.3. Accessing Adobe AIR APIs

Looking at the init JavaScript function, you'll see some code you may not be familiar with:

runtime.trace("init function called");

This is the only AIR-specific code/markup in the entire application. The runtime property is a property placed on the window object by Adobe AIR and provides an entry point into the Adobe AIR engine and APIs. The trace function is a top-level AIR API that takes a string and prints it out to the command line (when the application is launched via the command line).

All access to AIR-specific APIs (including Flash Player APIs) is accomplished from JavaScript via the runtime property. We will cover this in more detail throughout the rest of the book.

if(window.runtime)
{
 //running within AIR
}

Now that we have created both the application descriptor file and the root HTML application file, we are ready to run and test our application within the runtime.