Beginners Adobe Air Tutorial – part 1

Getting Started with Adobe AIR
Adobe AIR is a Flash-style runtime for web technologies. It bridges the gap between desktop applications and web applications, enabling developers to work with HTML and JavaScript while still performing common desktop tasks such as clipboard manipulation and native menus. In this tutorial, we’re going to take a first look at building an application with Adobe AIR.

Introducing Adobe AIR
AIR application files are essentially “static” web application files packaged up for distribution. An end user installs the AIR runtime, just like the Flash runtime, and can then open up .air files containing HTML pages, CSS sheets and other resources. However, AIR applications are effectively “installed” to the end user’s computer – Adobe AIR provides a standard installation dialog, and HTML resources inside an .air application file are then extracted to a folder on the user’s computer (e.g. %PROGRAMFILES%\MyAIRApp under Windows).
As developers, we then build web application using JavaScript on steroids – AIR runs a Webkit-based browser with excellent support for XHTML, CSS and JavaScript, and provides various operating system APIs through JavaScript. For example, AIR developers can use JavaScript to create native menus and system tray / dock icons.

Setting up the SDK
To build applications with AIR, we’ll need to install the AIR software development kit, or SDK. This includes the tools we need to test and compile our applications, so that we can distribute them to our users as single .air files. The installer is available for Windows and OS X, and Adobe Labs is working on a Linux version currently in alpha. Head over to the download page to grab a copy, and install it somewhere handy; instructions are available on the AIR docs page.
We’ll need to jump to the command line to run some of the tools in the SDK. For this tutorial, we’ll assume your development machine runs Windows and the AIR SDK has been extracted to C:\AIRSDK, such that C:\AIRSDK\bin exists.

Building your first Adobe AIR application
Once we’ve installed the SDK, we’re all set to build our first AIR application. Here, we’ll build our application with a single HTML file, as well as an XML file called the application descriptor. This descriptor file, typically stored as application.xml in the main directory of the AIR app, is sort of the front line for the program and includes some meta data – in particular, the origin of the program, and how to open it.
We’re going to build a simple script to demonstrate the power of AIR. While we use all our standard web development tools – HTML, CSS, JavaScript and the like – AIR has in particular lifted various security restrictions (albeit introduced a few others) to suit the context. While retrieving content from other pages with AJAX isn’t normally possible on the web, any existing code will pull it off just fine in AIR, and we’re about to see how.

The application descriptor file
Let’s start by building the descriptor file. Open your favourite text editor and bash out the following:
<?xml version=”1.0″ encoding=”UTF-8″?>
<application xmlns=”http://ns.adobe.com/air/application/1.0″>
    <id>com.example.html.xdomainxhr</id>
    <version>1.0</version>
    <filename>xdomainxhr</filename>
    <initialWindow>
        <content>xdomainxhr.html</content>
        <visible>true</visible>
        <width>640</width>
        <height>480</height>
    </initialWindow>
</application>
There are all sorts of other options we could include, such as install directories, icon files, and even file type associations – check out the manual page for more info. Here, we’ve just defined the basic properties of our application, including a (generally) unique ID, and some info on what page to open in the AIR browser to start the application. When we refer to xdomainxhr.html, AIR will launch this app at this HTML page on starting, inside a 640×480 window with minimal chrome.
Create a new folder for your application – mine’s at C:\AIR\xdomainxhr – and save this XML as application.xml within that folder.

The application HTML/JS
Now we get to create our actual HTML file. Head back to your text editor and create a new file, the xdomainxhr.html we referenced earlier. Then copy this out:
<html>
<head>
<title>Cross-domain XHR Sample</title>
<script type=”text/javascript”>
  function xhr_run() {
   var xhr = new XMLHttpRequest();
   xhr.onreadystatechange = function() {
    if (xhr.readyState == 4) {
     alert(‘Cross-domain XHR complete!\n’ +
           ‘responseText: \n’ +
           xhr.responseText.substring(0,199));
    }
   };
   xhr.open(‘GET’, ‘http://www.example.com/’, true);
   xhr.send(null);
  }
</script>
</head>
<body>
<button onclick=”xhr_run()”>Start Request</button>
</body>
</html>

First, we have a standard HTML file. Running in the right conditions, this code would function just fine inside a web browser being served over the internet. However, it would need to be served from example.com, and since this is reserved (and not under our control!), this isn’t an option. Workarounds are available, but AIR allows us to simply execute as normal. Let’s have a look by running our application.
Running our AIR application
To test this app, we’ll need to jump to command line and use one of the utilities included in the SDK. The ADL binary represents the AIR debug launcher, enabling us to test our applications without actually installing them. The ADT script, on the other hand, is the AIR developer tool, and provides a number of handy functions from signing applications to actually packaging them for distribution. We’ll use ADL today.
Bring up a command line (Windows – Start > Run, ‘cmd’, Enter) and navigate to the folder with your application.xml and xdomainxhr.html files, then run the application descriptor through ADL within the bin directory of your AIR SDK. Here’s the commands under a DOS prompt:

C:\>cd C:\AIR\xdomainxhr
C:\AIR\xdomainxhr>C:\AIRSDK\bin\adl application.xml
Sure enough, running these produces the application window. When we click on the button inside, the AJAX request is dispatched, and upon completion will produce our alert window. Here’s how it looks on my machine:

Notice the window looks just like a typical application, blending in to the operating system chrome. Of course, within the application the default white background is quite apparent. Remember that this mini window is actually a complete Webkit-based browser with some handy extensions, which we’ll explore in a later article.
We used the standard AIR SDK to test run our application here. However, the SDK is already available within two excellent IDEs that you may be familiar with: Aptana and Dreamweaver CS3 both have AIR plugins that automate many development tasks, such as toolbar / keyboard shortcuts for running applications. Both even have interfaces for dealing with application descriptor files, which can get quite lengthy and complex in production. Have a look at the Adobe AIR Tools page  and Aptana’s AIR guide for more details.

Further Reading
Now that we’ve built a simple AIR application, it’s easy to explore the AIR runtime features. You might find these useful:

AIR 1.1 Manual

AIR/AJAX Developer Center

Developing on Adobe AIR with Aptana Studio

Finally, the various quirks of programming with HTML and JavaScript within the AIR runtime are covered in a seperate section on the developers guide.

Beginners Adobe Air Tutorial – Part 2

October 23, 2008 at 10:53 am 2 comments