Walk on AIR: Create a To-do List in Five Minutes

This is the winning article from the recent competition 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, 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, which lets you (and your users) run AIR applications
• the Software Development Kit (SDK), 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 does the job), but if you use Aptana or Dreamweaver CS3 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. 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 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.