Section 2.6. Creating a Simple AIR Application with HTML and JavaScript

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:

1. Create a new folder called AIRHelloWorld.

2. Inside this folder, create two new files called AIRHelloWorld.html and AIRHelloWorld.xml.

3. Open each file using your favorite text or HTML
   editor/IDE.

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.

NOTE

You can find a sample application descriptor file in the AIR
SDK in the templates
folder.

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.

NOTE

The application descriptor file and root content file must be
in the same folder.

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.

NOTE

Notice that the default value of the visible element is false. This means that if you do not
explicitly set the element to true, your application will have no UI
when it launches. In this case, you will have to programmatically
set the visible property to
true.

This can be useful if the application needs to perform some
initialization or layout when it first launches. You can allow the
application to do its layout first, and then only display the UI to
the user once the layout is complete.

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.

NOTE

Checking for the existence of the runtime property is a simple way to
determine whether your HTML and JavaScript application is running
within Adobe AIR. To check for the property, run the following
code:

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.