Create your first HTML-based AIR application with the AIR SDK

Create your first HTML-based AIR application with the AIR SDK

       For a quick, hands-on illustration of how Adobe AIR works, use these instructions to create and package a simple HTML-based AIR “Hello World” application.

      To begin, you must have installed the runtime and set up the AIR SDK. You will use the AIR Debug Launcher (ADL) and the AIR Developer Tool (ADT) in this tutorial. These programs can be found in the bin directory of the AIR SDK. 

Creating the project files

      Every HTML-based AIR project must have at least two files: an application descriptor file, which specifies the application metadata, and a top-level HTML page. This Hello World example also uses a file containing some HTMLformatted text to be loaded into the application by JavaScript. In addition, the project includes a JavaScript code file,AIRAliases.js, that defines convenient alias variables for the AIR API classes.

To begin:

1 Create a directory named HelloWorld to contain the project files.
2 Copy AIRAliases.js from the frameworks folder of the AIR SDK to the project directory.

      In a larger-scale application you will most likely have a more complex directory structure and this will change some of the parameters you must pass to the command-line tools. However, for this introductory exercise, a single directory is sufficient.

Creating the AIR application descriptor file

This section describes how to create the application descriptor, which is an XML file with the following structure:

<application>
   <id>...</id>
  <version>...</version>
  <filename>…</filename>
  <initialWindow>
     <content>…</content>
    <visible>…</visible>
    <width>…</width>
    <height>…</height>
 </initialWindow>
</application>
1 Create an XML file named HelloWorld-app.xml and save it in the project directory.

2 Add the <application> element, including the AIR namespace attribute:

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

The last segment of the namespace, “1.0.M6,” specifies the version of the runtime required by the application.

3 Add the <id> element:

<id>examples.html.HelloWorld</id>

The application id uniquely identifies your application along with the publisher id (which is assigned by ADT when your AIR application is packaged). The recommended form is a dot-delimited, reverse-DNS-style string, such as "com.company.AppName". The application id is used for installation,access to the private application file-system storage directory, access to private encrypted storage, and interapplication communication.

4 Add the <version> element:

<version>0.1</version>

Helps users to determine which version of your application they are installing.

5 Add the <filename> element

<filename>HelloWorld</filename>

The name used for the application executable, install directory, and similar for references in the operating system.

6 Add the <initialWindow> element containing the following child elements to specify how your application window will be displayed:

<content>HelloWorld.html</content> Identifies the root HTML file for AIR to load.
<visible>true</visible> Makes the window visible when it opens. In some cases, you might want to initialize the visible element to false so that you can alter the window before showing it to your user.

<width>400</width> Sets the window width (in pixels).
<height>200</height> Sets the window height.

7 Save the file. Your complete application descriptor file should look like this:

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

<id>examples.html.HelloWorld</id>
<version>0.1</version>
<filename>HelloWorld</filename>
<initialWindow>

<content>HelloWorld.html</content>
<visible>true</visible>
<width>400</width>
<height>200</height>

</initialWindow>

</application>

    This example only sets a few of the possible application properties. For the full set of application properties, which allow you to specify such things as window chrome, window size, transparency, default installation directory, associated file types, and application icons.

Creating the application HTML page

This section describes how to create a simple HTML page that uses both standard JavaScript and the AIR API.

1 Create a file named HelloWorld.html (the name must match the name you used in the <content> element of the application descriptor file). Using any HTML or text editor, add the following HTML code:

<html>

<head>

<title>Hello World</title>

</head>
<body onLoad="appLoad();">

<h1>Hello World</h1>
<p>Loaded text:</p>
<div id="display">
</div>

</body>

</html>

2 In the <head> section of the HTML, import the AIRAliases.js file:

<script src="AIRAliases.js" type="text/javascript"></script>

AIR defines a property named runtime on the HTML window object. The runtime property provides access to the built-in AIR classes, using the fully qualified package name of the class. For example, to create an AIR File object you could add the following statement in JavaScript:
var textFile = new runtime.flash.filesystem.File("app:/textfile.txt");

However, the AIRAliases.js file defines convenient aliases for the most useful AIR APIs. Using AIRAliases.js, you can shorten the above reference to:

var textFile = new air.File("app:/textfile.txt");

3 Below the AIRAliases script tag, add another script tag containing a JavaScript function to handle the onLoad event:

<script type="text/javascript">
function appLoad(){
air.trace("Hello World");
//Read the text file
var textFile = new air.File("app:/textfile.txt");
if(textFile.exists){
var textStream = new air.FileStream();
textStream.open(textFile, air.FileMode.READ);
if(textStream.bytesAvailable > 0){
var fileText = textStream.readUTFBytes(textStream.bytesAvailable);
textStream.close();
air.trace("Text read: " + fileText);
//Create a 'p' element to display the text
var displayDiv = document.getElementById('display');
var paragraph = document.createElement('p');
var textNode = document.createTextNode(fileText);
paragraph.appendChild(textNode);
displayDiv.appendChild(paragraph);
} else {
air.trace("File is empty.");
}
} else {
air.trace("File not found.");
}
}
</script>

The appLoad() function first calls the air.trace() function. The trace message will be printed to the command console when you run the application is using ADL, which can be useful for debugging. The function then reads a text file and inserts the file contents into a DIV element as a new paragraph.
   Reading a file is a three step process:

a Define a File object:

var textFile = new air.File("app:/textfile.txt");

b Create and open a FileStream using the file object:

textStream.open(textFile, air.FileMode.READ);

c Read the data from the file stream:

var fileText = textStream.readUTFBytes(textStream.bytesAvailable);
The rest of the function uses standard JavaScript to insert the text into the page.
The complete HelloWorld.html file now looks like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>Hello World</title>
<script type="text/javascript" src="AIRAliases.js"></script>
<script type="text/javascript">
function appLoad(){
air.trace("Hello World");
//Read the text file
var textFile = new air.File("app:/textfile.txt");
if(textFile.exists){
var textStream = new air.FileStream();
textStream.open(textFile, air.FileMode.READ);
if(textStream.bytesAvailable > 0){
var fileText = textStream.readUTFBytes(textStream.bytesAvailable);
textStream.close();
air.trace("Text read: " + fileText);
//Create a 'p' element to display the text
var displayDiv = document.getElementById('display');
var paragraph = document.createElement('p');
var textNode = document.createTextNode(fileText);
paragraph.appendChild(textNode);
displayDiv.appendChild(paragraph);
} else {
air.trace("File is empty.");
}
} else {
air.trace("File not found.");
}
}
</script>
</head>
<body onLoad="appLoad();">
<h1>Hello World</h1>
<p>Loaded text:</p>
<div id="display"></div>
</body>
</html>

Creating the sample text file

The sample text file contains a simple HTML-formatted string.

1 Create a text file named textfile.txt in the project directory. Add some text to the file, such as: Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.

2 Save the file and you are ready to test the application.

Testing the application

  To run and test the application from the command line, use the AIR Debug Launcher (ADL). (The ADL executable can be found in the bin directory of the AIR SDK.)
  First, open a command console or shell. Change to the directory you created for this project. Then, run the following command:
                                 adl HelloWorld-app.xml
  An AIR window opens, displaying your application. Also, the console window displays the message resulting from the air.trace() calls.

Creating the AIR installation file

When your application runs successfully, you can use the ADT application to package the application into an AIR installation file for distribution or testing from the desktop. An AIR installation file is an archive file that contains all the application files. You can distribute the AIR file to users.

All AIR installation files must be signed. For development purposes, you can generate a basic, self-signed certificate with ADT or another certificate generation tool, or you can buy a commercial code-signing certificate from a commercial certificate authority such as VeriSign or Thawte. When users install a self-signed AIR file, the publisher will be displayed as “unknown” during the installation process. This is because a self-signed certificate only guarantees that the AIR file has not been changed since it was created. There is nothing to prevent someone from self-signing a masquerade AIR file and presenting it as your application. For publicly released AIR files, a verifiable,commercial certificate is strongly recommended.
   When you create a self-signed certificate with ADT, the tool generates a random key pair. Because of this, no two certificates generated by ADT will ever be the same. If you wish to create an update for an application signed with an ADT certificate, you must use the same certificate file to sign the update.

To generate a self-signed certificate and key pair:

From the command prompt, enter the following command (the ADT executable can be found in the bin directory of the AIR SDK):
adt –certificate -cn SelfSigned 1024-RSA sampleCert.pfx samplePassword

This example uses the minimum number of attributes that can be set for a certificate. You can use any values for the parameters in italics. The key type must be either 1024-RSA or 2048-RSA.

To create the AIR installation file:
   From the command prompt, enter the following command (on a single line):

adt -package -storetype pkcs12 -keystore sampleCert.pfx HelloWorld.air HelloWorld-app.xml HelloWorld.html AIRAliases.js textfile.txt

You will be prompted for the keystore file password.

The HelloWorld.air argument is the AIR file that ADT produces. HelloWorld-app.xml is the application descriptor file. The subsequent arguments are the files used by your application. This example only uses three files,but you can include any number of files and directories.

After the AIR package is created, you can double-click it, CTRL-click it, or type the AIR filename as a command in the shell to install and run the application.