By: Akash Mehta

June 13th, 2008

Reader Rating: 9.5

This is the winning article from the recent competition [1] we ran to promote Adobe AIR articles on sitepoint.com.

The Adobe Integrated Runtime (AIR) is quite a hot topic among web developers. And well it might be! With AIR, Adobe’s new desktop-based web application system, desktop applications can now be built with the technologies web developers have been using for years—plain old HTML, CSS, and JavaScript.

In this tutorial, I’ll show you how to do exactly that: build a simple web-based application for the desktop with Adobe AIR.

AIR 101

So, what is this Adobe AIR? At its most basic, AIR is a platform that provides a bridge between web technologies and desktop APIs. Where web developers once needed to use workarounds and talk back to the server to build client-focused applications, AIR provides a means for building building web applications that run from the desktop. AIR applications gives a user the best of both worlds—the rich interface and local resources of a desktop application, and the networked benefits of the Web. It also provides access to the client system, a feature sorely lacking in rich internet applications.

With AIR, web applications can now:

• work with the local file system
• integrate with the window manager (to allow modification of OS X dock icons and Windows system tray icons, for example)
• provide native menus
• store data securely on the local machine

The best part, however, is this: all of this functionality is available with JavaScript code. Any web developer with reasonable JavaScript skills can get started immediately. If you speak JavaScript, you could be building powerful desktop applications in a matter of minutes using only your existing skills.

But enough of the why—now let’s examine the what, and jump into the how.

Internals of AIR

The core of AIR is heavily web-oriented. AIR includes a web browser built on WebKit [2], the same rendering engine that powers Apple’s Safari browser. WebKit is as standards-compliant as any modern web browser, so it has terrific support for CSS and JavaScript.

The web browser is then linked to the OS-specific APIs. When your application is running on OS X, you may like to add dock icons or menus to the application menu bar—that’s what these APIs are for. Likewise, in Windows, you can create system tray icons and window menus.

Finally, AIR provides access to the more general operating system features through the desktop APIs, which are similar to those you might see in a desktop application framework. The basics are all in place: working with the file system, drag and drop, clipboard, networking. AIR goes one step further, though—since the platform is designed for rich web applications, it provides local SQLite-powered databases out of the box.

Anyone who’s done any object-oriented JavaScript programming before will immediately realize that, with all this functionality exposed to the AIR application, JavaScript developers should have no trouble at all making use of this immense power.

Getting Started

As a developer, there are two parts to AIR that you’ll need:

• the runtime [3], which lets you (and your users) run AIR applications
• the Software Development Kit (SDK) [4], which lets you test and package AIR applications

Before you read any further, I’d recommend you download both of these, so that you can play along at home. To build the sample application in this tutorial, I’ve used version 1.0.1 of the runtime (the latest available at the time of writing), but they should work on any 1.x runtime.

After installing the runtime, extract the SDK to a folder on your local file system. Because I’m on a Windows machine, I’ve used the path C:\air\sdk, but you can place it in another folder if you prefer.

From here on, if you’ve got the tools to build web applications, you have everything you need. I’m working with Windows and nothing but a text editor (Notepad2 [5] does the job), but if you use Aptana [6] or Dreamweaver CS3 [7] on any platform, there are some handy plugins for your IDE that you may like to try.

At this stage you’ll need to be on either a Windows or a Mac; AIR for Linux is in alpha but available [8]. Feel free to give it a go, but since it’s alpha software, I can’t guarantee it will run these samples.

Your First AIR Application

Let’s cut to the chase and build our first AIR application! We’ll start by putting together a simple “Hello World” to demonstrate the basics, and move on to a simple to-do list application. While not the first time [9] that such an application has been created in AIR, it’s perfect for an introductory level project.

First, create a new folder for the project, to help organize all the bits and pieces that make up your AIR application—I’ve used C:\air\projects\hello_world.

The Application Descriptor File

An AIR application in its simplest form is just a collection of HTML files. An XML configuration file informs the runtime of the application entry point—usually an HTML file or a Flash/Flex file. This configuration file is called the application descriptor file, and includes some basic metadata like the name of the application, a unique ID, and the current version of the application.

Let’s make one now. Type the following into a text file:

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://ns.adobe.com/air/application/1.0">
   <id>examples.sp.helloworld</id>
   <filename>HelloWorld</filename>
   <initialWindow>
       <content>index.html</content>
       <visible>true</visible>
   </initialWindow>
</application>

Save this file with the name application.xml in the project folder that we created earlier. At the moment, this application descriptor file is quite minimal; our final application will specify a few more parameters. For now, we’ve got ourselves an application ID, a package filename, and some details about our initial window.

The application ID is simply a unique string that identifies our application; it’s recommended that this be specified using reverse-domain dot syntax. For example, if I was building sitepoint.com’s Test application, I’d specify an ID of com.sitepoint.Test. Here, we’ve used examples.sp.helloworld, which should avoid clashes with any other AIR samples you may try out. This refers to the final application executable filename, as well as the name of the install directory and a few references to the application. Finally, the initialWindow section defines how our application will start—in this case, with the index.html page visible.

The Application Front End

Next, we have to put together the HTML file that will serve as the front end. We’ll start with a basic “Hello world” in HTML:
 
<html>  
<head>  
   <title>Hello World</title>  
</head>  
<body>  
   <h1>Hello World</h1>  
</body>  
</html>

Copy the above markup into your text editor and save it as index.html, in the same folder as application.xml.

Once we’ve got our application descriptor file and initial HTML page ready, we’re all set. Run your first AIR application by typing the following at the command line:

/path/to/adl /path/to/application.xml

Because I’m on Windows, I would type this:

C:\air\sdk\bin\adl C:\air\projects\hello_world\application.xml

Of course, you should substitute the appropriate paths to both the adl binary and the application.xml file). And if you’re working in Windows, you can even just drag your application.xml file onto the adl executable to achieve the same thing.

This results in a console window opening, with our “Hello World” web application displayed in a basic window, as shown here.

Congratulations—your first AIR application is complete!

This mysterious adl executable is the AIR Debug Launcher (ADL). The black console window that opens with it allows the ADL to provide you with debug information—for example, most JavaScript errors will produce one or two ADL console messages. You can also generate your own debug messages for the ADL.

Working with AIR

As we’ve just seen, getting started with AIR is easy. However, the fun really begins once you’ve found your way around the runtime. Let’s build a simple to-do list application, using a sampling of HTML, CSS, and JavaScript.

Interface Niceties

We’ll need our application to look a little more glamorous than our “Hello World” page. I won’t worry much about CSS styling in this tutorial, as that’s something you can easily add to your application later. We’ll just put together a bare-bones interface to demonstrate the basics.

If you’re retro-fitting a web page into an AIR application, chances are your existing web page styles will render just fine. Be wary of copying your web site design entirely, though—desktop applications have rather different user interface needs. Keep in mind that a desktop application will probably be run in a window, whereas a web browser window is often maximized to fill the entire screen. Another point of difference is that, on the desktop, users scroll smaller elements and input fields, whereas on the Web users (generally) scroll the entire page.

Open up the index.html file from earlier, and update it with our new to-do list layout code, shown below:

<html>  
<head>  
   <title>Todo List!</title>  
   <style type="text/css">  
   body {  
       margin: 20px;  
   }  
   h1 {  
       font-family: sans-serif;  
   }  
   </style>  
</head>  
<body>  
   <h1>Todo Items</h1>  
   <p><input type="text" id="new_text" />  
      <input type="submit" id="add_item" /></p>  
   <ul id="todo_items">  
       <li>Learn AIR</li>  
       <li>Buy milk</li>  
       <li>Stock up on coffee</li>  
   </ul>  
</body>  
</html>

Run your application again (either from the command line or by dragging your application.xml onto adl.exe) and your application should look like this figure.

Now hover over the input box and the Submit button—you’ll notice the AIR runtime has applied some styles to both, including a nice hover effect. If you want to, you can override these styles just as you would override any web browser’s default styles, but we’ll stick with this effect.

JavaScript: AIR Gone Wild!

Next, we need to add our actual list management functionality. By allowing us to code in JavaScript, AIR provides us with immense power; just take a look at the size of the JavaScript Language Reference for AIR [10]. From working with the file system to checking the contents of the clipboard and even interfacing with attached cameras and microphones, it’s all there. There’s just so much available to you, courtesy of AIR!

For now, we’ll perform some basic interface bindings to create our to-do list functionality. We’ll create a simple list of items, and allow the user to remove each item from the list by clicking on it. The JavaScript is fairly straightforward; here’s the interface code:

function remove_todo(element) {  
   element.parentNode.removeChild(element);  
}  
 
window.onload = function() {  
   document.getElementById('add_item').onmousedown = function() {  
       item_text = document.getElementById('new_text').value;  
       new_item = document.createElement('li');  
       new_a = document.createElement('a');  
       new_a.onmousedown = function() {  
           remove_todo(this.parentNode);  
       }  
       new_a.innerHTML = item_text;  
       new_item.appendChild(new_a);  
       document.getElementById('todo_items').appendChild(new_item);  
   }  
}

This is all very standard DOM stuff, and could just as well have been written for a web application. In fact, I used Firebug and Firefox to do some quick checks on this same page while putting it together. The code isn’t pretty, and it probably isn’t as fast as it could be, but it’ll do for now. Stick this into a <script> tag in the head section of your index.html.

Putting it All Together

Here’s our final UI code:

<html>  
<head>  
   <title>Todo List!</title>  
   <style type="text/css">  
   body {  
       margin: 20px;  
   }  
   h1 {  
       font-family: sans-serif;  
   }  
   </style>  
   <script type="text/javascript">  
   function remove_todo(element) {  
       element.parentNode.removeChild(element);  
   }  
     
   window.onload = function() {  
       document.getElementById('add_item').onmousedown = function() {  
           item_text = document.getElementById('new_text').value;  
           new_item = document.createElement('li');  
           new_a = document.createElement('a');  
           new_a.onmousedown = function() {  
               remove_todo(this.parentNode);  
           }  
           new_a.innerHTML = item_text;  
           new_item.appendChild(new_a);  
           document.getElementById('todo_items').appendChild(new_item);  
       }  
   }  
   </script>  
</head>  
<body>  
   <h1>Todo Items</h1>  
   <p><input type="text" id="new_text" /><input type="submit" id="add_item" /></p>  
   <ul id="todo_items">  
   </ul>  
</body>  
</html>

Update your index.html file with this code, run it through ADL—and voila! Our application is fully functional! It should look something like this.

If the user inserts items, they are added to the list, and clicking on them causes them to disappear from the list, as expected. Our interface could certainly do with some improvements, but overall the application was quick and easy to build, and we have a reasonable Adobe AIR application ready.

But wait—what do we do now?

Finishing Touches

With our to-do application almost ready, we can now add the finishing touches and package it up into an .air file for distribution.

Tweaking Our Application Descriptor File

Here’s our current application.xml:

<?xml version="1.0" encoding="UTF-8"?>  
<application xmlns="http://ns.adobe.com/air/application/1.0">  
   <id>examples.sp.helloworld</id>  
   <filename>hello_World</filename>  
   <initialWindow>  
       <content>index.html</content>  
       <visible>true</visible>  
   </initialWindow>  
</application>

We could start by updating the Hello World data! Next, before we go to production, we should definitely add a version number, so that the runtime on the end user’s machine will be able to recognize updates. We can also add <name> and <description> tags with some useful info.

Also, our to-do list window is designed to be very narrow. We can restrict the width to, say, 200 pixels, via the <width> property node inside <initialWindow>. <height> works for restricting the window height as well; both tags are optional.

The manual page [11] contains thorough documentation on all the available options. Here’s our updated configuration file:

<?xml version="1.0" encoding="UTF-8"?>  
<application xmlns="http://ns.adobe.com/air/application/1.0">  
   <id>examples.sp.todo</id>  
   <filename>TodoList</filename>  
   <version>1</version>  
   <name>SitePoint.com AIR Example: Todo List</name>  
   <description>This application helps you manage your pending tasks.</description>  
   <initialWindow>  
       <content>index.html</content>  
       <visible>true</visible>  
       <width>200</width>  
   </initialWindow>  
</application>

Packaging Our Application for Distribution

Alongside the ADL, the Adobe AIR SDK includes the AIR Developer Tool (ADT) utility to package AIR applications and generate certificates. AIR applications should be digitally signed—users will receive a warning when installing applications not properly signed or are not signed at all.

We’ll need to jump to command line to generate a certificate—so pull up a console window in the same folder as your AIR application and type the following:

adt -certificate -cn SelfSigned 1024-RSA testCert.pfx some_password

Substitute “some_password” with a password of your choice. After a few seconds, ADT should complete its certificate generation process and you should have a new testCert.pfx file in your application directory.

Next, use ADT to package the application into an .air file:

adt -package -storetype pkcs12 -keystore testCert.pfx TodoList.air application.xml index.html

This tells ADT to package your application, using the key file in testCert.pfx. In the line above, we’re instructing the ADT to package our entire application into a file named TodoList.air, and to include the files application.xml and index.html. Any other files you may need to include in your application (such as JavaScript, CSS, or the like) can be added to the end of this command.

As part of this process, you’ll be prompted for the password that we set for your new certificate file. Enter it, wait a moment, and a TodoList.air file should appear in the same directory as your project files.

The only task remaining is to test out your new AIR application! Double-click on the TodoList.air file to launch the AIR installer. The application will take a moment to install, and display the name of our application (as defined in application.xml) during the process. Finally, once the installation is complete, the application will launch. Ta da! Your first real AIR application is complete!

Further Reading

Adobe has prepared some invaluable resources on getting started with AIR. If you’re interested in exploring the area further, head over to their developer center, where they’ve got AIR HTML tutorials [12], a JavaScript Language Reference for the AIR APIs [13], and a complete manual on building AIR applications with HTML and AJAX [14].

You should also get set up with an IDE; Aptana [15] provides great AIR support, and even has a screencast [16] on building applications using Aptana and AIR.

While this is a very simple application, I hope you can see the potential that Adobe AIR brings to the table. The grey area between web applications and desktop applications just got a whole lot greyer; I look forward to seeing what amazing creations you can fill it with!

[1] http://www.sitepoint.com/blogs/2008/05/26/adobe-flexair-article-competition-and-the-winners-are/
[2] http://webkit.org/
[3] http://get.adobe.com/air/
[4] http://www.adobe.com/products/air/tools/sdk/
[5] http://flos-freeware.ch/notepad2.html
[6] http://www.aptana.com/air
[7] http://labs.adobe.com/wiki/index.php/AIR:Dreamweaver_CS3_Extension
[8] http://labs.adobe.com/downloads/air_linux.html
[9] http://24ways.org/2007/christmas-is-in-the-air
[10] http://livedocs.adobe.com/labs/air/1/jslr/index.html
[11] http://livedocs.adobe.com/air/1/devappshtml/help.html?content=File_formats_1.html
[12] http://www.adobe.com/devnet/air/ajax/quickstart/
[13] http://livedocs.adobe.com/labs/air/1/jslr/index.html
[14] http://livedocs.adobe.com/air/1/devappshtml/
[15] http://www.aptana.com/air
[16] http://www.adobe.com/devnet/air/ajax/articles/building_on_air_in_aptana.html