Beginners Adobe AIR Tutorial – Part 2

November 10, 2008

This Beginners Adobe AIR Tutorial covers the fundamentals for creating a simple AIR application.

Getting Rich with Adobe AIR

Adobe AIR provides developers with a rich set of tools to build applications with web technologies. Alongside HTML, CSS and Javascript, AIR applications can use native menus, system tray / dock icons, drag and drop of files and other media, clipboard manipulations, and even file system APIs. In this tutorial, we’ll look at some of the many APIs that Adobe AIR provides.

Getting Started

To follow this tutorial, you’ll need a text editor, and a copy of the Adobe AIR SDK. A basic understanding of AIR is also helpful. We recommend you read through the first tutorial in our Adobe AIR series, “Getting Started with Adobe AIR“, to setup your development environment and explore the basics of the AIR platform.

To start the project, we need a folder to store our code files. I’ll be using C:\AIR\richair, and you can substitute this in examples with the path to your project folder. (If the path has spaces, remember to quote it when working in a terminal / command prompt.) Make sure you know the absolute path to bin/adl in your AIR SDK folder – for example, mine’s at C:\AIRSDK\bin\adl.

We’ll be using the jQuery Javascript framework for this application. Adobe AIR has excellent support for most major frameworks, and jQuery in particular is extremely popular for AIR applications. Grab a copy at jquery.com.

Building the application

We’ll build our application in three stages: we’ll start with the application descriptor file, construct a HTML framework, and then add behaviour in an external Javascript file.

Creating the application descriptor

Open your text editor and create an application.xml file in the project folder. This will tell AIR how to install and run our application. As usual, we don’t need too much meta data here – just copy in the following:

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://ns.adobe.com/air/application/1.0">
    <id>com.example.html.richair</id>
    <version>1.0</version>
    <filename>richair</filename>
    <initialWindow>
        <title>Rich AIR</title>
        <content>richair.html</content>
        <visible>true</visible>
        <resizable>false</resizable>
        <width>640</width>
        <height>480</height>
    </initialWindow>
</application>

This tells Adobe AIR that we are building an application named “Rich AIR” to be installed in /richair, and the entry point for the application will be the richair.html file. Additionally, the window will start out as 640×480 and be visible. We have a couple of extra properties this time: <title> and <resizable>. The first provides AIR with a general title to use for the application, e.g. when installing and when no title is provided by the HTML. The second tells AIR if it should allow end users to resize the application window: in this case, we’ve told it not to.

We’re only using a small subset of the configuration There are hundreds of options available – check out the samples/descriptor-sample.xml file in your AIR SDK folder for a full example.

Creating the HTML framework

We’re going to be exploring the various AIR APIs, by creating an application that records lists and saves them to the file system. We’ll need a fairly basic HTML structure – create richair.html with your text editor and copy in the following:

<html>
<head>
	<title>Rich AIR: Exploring the AIR APIs</title>
	<script type="text/javascript" src="AIRAliases.js"></script>
	<script type="text/javascript" src="jquery-1.2.6.min.js"></script>
	<script type="text/javascript" src="behaviour.js"></script>
</head>
<body onload="Run()">
	<p>Existing items:</p>
	<ul id="items"></ul>
	<p>
		<button onclick="Save()">Save</button>
		<button onlick="Quit()">Exit</button>
	</p>
</body>
</html>

We reference our copy of jQuery (I’m using the minified and gzipped copy of 1.2.6), as well as “behaviour.js” which will contain our behaviour code. Create this file now, and leave it empty.

Also note we’re referencing AIRAliases.js, a framework included in Adobe AIR to provide easy aliases to common APIs. Most of the APIs are hidden under lengthy structures such as window.runtime.media and similar, and this file will give us abstracted, easy access to these functions. You’ll need to copy this from your AIR SDK directory – it’s under frameworks/ – and place it in your project folder.

Testing our application

It’s time to test that our application is working. We’ll need to run it from a command line using the adl utility we discussed in “Getting Started” above. It needs a single argument, the path to our application.xml file, so let’s switch to our project directory and run it from there.

Load up a command prompt and type the following:

C:\>cd C:\AIR\richair
C:\AIR\richair>C:\AIRSDK\bin\adl.exe application.xml

The application window will appear, with the text “Existing Items” and nothing else. We’re all set – let’s start adding behaviours with the APIs.

Adding menus

Load up behaviour.js in your text editor and add the following:

function addItem(event) { alert('clicked'); }

function Run() {
    nativeWindow.menu = new air.NativeMenu();
    fileMenu = nativeWindow.menu.addItem(new air.NativeMenuItem("Actions"));
    fileMenu.submenu = new air.NativeMenu();
    btnItem = fileMenu.submenu.addItem(new air.NativeMenuItem("New Item"));
    btnItem.addEventListener(air.Event.SELECT, addItem);
}

Remember we called the Run() function in our onload event back in our HTML? This will launch the function defined here, which for now simply creates our menu system. The AIR menu model is quite simple; windows or applications have menus, depending on whether the target platform is Windows or OS X.

The window menu is actually the menu bar, on which you place a menu as the submenu property, and items here are placed into the submenu of the menu itself. Each item, whether it’s a menu title or an option within a menu, is a NativeMenuItem, while the container for items is a NativeMenu. Be aware that on OS X an application menu is already present, and this poses certain other challenges. The manual has an excellent platform sniffing workaround sample.

Linux would function similarly to Windows; AIR is quite effective in this regard, as we don’t really have to worry at this stage, and when AIR for Linux is out of beta our applications will still run fine.

Working with the clipboard

We then need to allow the user to add an item. Remember that addItem()function we used earlier? It will show a prompt for the text of the item, but first we’ll check the clipboard to see if the user has copied text that they want to use.

AIR provides a simple API to access the OS clipboard, but we have to remember that not all content on the clipboard is plain text; for example, the current clipboard item could contain images, one or more files, or maybe even rich HTML text. For now, we’ll just look for plain text.

Head back to behaviour.js and update our addItem function with this code:

function addItem(event) {
    var defaultText = "";
    if(air.Clipboard.generalClipboard.hasFormat(air.ClipboardFormats.TEXT_FORMAT)) {
        defaultText = air.Clipboard.generalClipboard.getData(air.ClipboardFormats.TEXT_FORMAT);
    }

    itemText = prompt("Enter item text:", defaultText);
    newItem(itemText);
}

This will check if any “text” is stored on the clipboard, and if so create a copy before passing on to prompt(). We then hand over to the newItem() function, which we should define now:

items = new Array();

function newItem(text) {
    if (text) {
        items.push(text);
        $("<li></li>").html(text).appendTo("#items");
    }
}

Now when we enter a new item, we will store the item text in our items stack, as well as add a new entry to the <ul> on the page.

Saving our list

Once we’ve worked out our list of items, we’ll want to save it somewhere. Let’s provide a simple save mechanism to store the data on the filesystem, inside the user’s home directory. Add this to the end of your behaviour.js:

function Save() {
    var data = "";
    for (i=0;i<items.length;i++) {
        data += items[i] + "\n";
    }
    var target = air.File.documentsDirectory.resolvePath("airitems.txt");
    if (target.exists) {
	    alert("File exists!");
	    return;
	}
	var fileStream = new air.FileStream();
	fileStream.open(target, air.FileMode.WRITE);
	fileStream.writeMultiByte(data, air.File.systemCharset);
	fileStream.close();

    while(items.pop());
    $("#items").empty();
}

This will save each item, one per line, to a file called “airitems.txt” in our documents directory. If the file exists, it will alert us first, to avoid overwriting any critical data. Notice we use a file stream here – we can keep pushing data to the file, e.g. when streaming the data over a network. The AIR manual has further information on file workflow.

Exiting

Finally, we need a way for the user to quickly exit. Our exit button already calls the Exit() function, so we simply have to define it in behaviour.js.

AIR provides a sophisticated event framework for everything from opening a file to terminating the application. Part of events, however, is checking if we need to stop an event, and terminating the application is a good example. What if we are in the middle of an important operation? Thankfully, AIR provides a simple framework to prevent actions, and check if actions are prevented. Copy this into the end of behaviour.js:

function Quit() {
    var event = new air.Event(air.Event.EXITING, false, true);
    air.NativeApplication.nativeApplication.dispatchEvent(event);
    if (!event.isDefaultPrevented()) {
        air.NativeApplication.nativeApplication.exit();
    }
}

This way, if any part of your application (or of the AIR runtime) needs to prevent your app from exiting, the exit button is effectively disabled for as long as needed.

Wrapping up

Here’s our completed behaviour.js:

function addItem(event) {
    var defaultText = "";
    if(air.Clipboard.generalClipboard.hasFormat(air.ClipboardFormats.TEXT_FORMAT)) {
        defaultText = air.Clipboard.generalClipboard.getData(air.ClipboardFormats.TEXT_FORMAT);
    }

    itemText = prompt("Enter item text:", defaultText);
    newItem(itemText);
}

items = new Array();

function newItem(text) {
    if (text) {
        items.push(text);
        $("<li></li>").html(text).appendTo("#items");
    }
}

function Run() {
    nativeWindow.menu = new air.NativeMenu();
    fileMenu = nativeWindow.menu.addItem(new air.NativeMenuItem("Actions"));
    fileMenu.submenu = new air.NativeMenu();
    btnItem = fileMenu.submenu.addItem(new air.NativeMenuItem("New Item"));
    btnItem.addEventListener(air.Event.SELECT, addItem);
}

function Save() {
    var data = "";
    for (i=0;i<items.length;i++) {
        data += items[i] + "\r\n";
    }
    var target = air.File.documentsDirectory.resolvePath("airitems.txt");
    if (target.exists) {
	    alert("File exists!");
	    return;
	}
	var fileStream = new air.FileStream();
	fileStream.open(target, air.FileMode.WRITE);
	fileStream.writeMultiByte(data, air.File.systemCharset);
	fileStream.close();

    while(items.pop());
    $("#items").empty();
}

function Quit() {
    var event = new air.Event(air.Event.EXITING, false, true);
    air.NativeApplication.nativeApplication.dispatchEvent(event);
    if (!event.isDefaultPrevented()) {
        air.NativeApplication.nativeApplication.exit();
    }
}

Finalising, further reading

And we’re done! We can run the completed application at command line again:

C:\>cd C:\AIR\richair
C:\AIR\richair>C:\AIRSDK\bin\adl.exe application.xml

To explore further, the online documentation for AIR has a number of resources you might find handy:

In the next Adobe AIR Tutorial we are going to look at how to create a Personal Information Management application with AIR, SQLite and Jquery.

Entry Filed under: Adobe Air. Tags: Adobe AIR Tutorial, Beginners Adobe Air Tutorials.

3 Comments Add your own

1. Beginners Adobe Air Tutorial - part 1 « Video Training - Tutorials | November 10, 2008 at 1:51 pm

[...] Beginners Adobe Air Tutorial – Part 2 [...]
Reply
2. jason | December 8, 2008 at 4:47 pm

when i run this i get an error in dreamweaver
ReferrenceError: can’t find variable: $
Reply
3. shawn | January 21, 2009 at 6:19 pm

ReferenceError: can’t find variable $ explaination.

The dollar sign function has become a common way Javascript libraries (such a JQuery) encapsulate document.GetElementById().

If you are getting this error, it is probably caused by not having the correct JQuery js file referenced in your HTML document, or you did not download and copy the JQuery js file into the application directory.

Look at the following line in the richair.html file:

script type=”text/javascript” src=”jquery-1.2.6.min.js

It is trying to load the jquery-1.2.6.min.js file. Now look in the directory that contains the richair.html file. Do you see the same file? You should.

Note that the Jquery js file that you downloaded might be a more recent version. If so, simply edit the richair.html file and change the jquery-1.2.8.min.js reference to the new file name.
Reply

Some HTML allowed:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <pre> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Trackback this post | Subscribe to the comments via RSS Feed

Video Training – Tutorials