Adobe Air allows web developers to build and deploy desktop applications using web based technologies including flash or HTML and Javascript. End users who wish to use your Adobe Air applications are required to download the Adobe AIR Client. Once the user has installed the client, they will be able to run AIR applications without the need to install anything again. AIR is cross platform meaning you can build an application and it will run on Windows, Linux or Mac. Air is still an emerging technology with the first version debuting in Feburay 2008. Before its official release adobe code named the project Apollo.
Building Your First AIR application.
For this tutorial we’ll build a Gmail Notifier for your desktop which will inform the user when they receive an email from the google email service. Remember you can program apps in flash or HTML and Javascript, but for this tutorial, we’ll be using HTML and Javascript. The Gmail Notifier will run in the background on the desktop and inform the user when an email is received using sounds and a desktop notification.
Downloading and installing the AIR Client.
Before we do anything else, we’ll need to install the AIR client so whether your running Windows, Linux or Mac you’ll need to download the Adobe AIR client (select your OS and version) the download will start automatically. Installation is straight forward and requires nothing additional from the user. Remember your users will need the Adobe Air client to run Air applications.
Downloading and Installing the AIR SDK.
Now as we are the developers of an AIR application we’ll need some additional software. The Adobe AIR SDK is a software development kit which allows developers to build and compile AIR applications. You can download the SDK from Adobe AIR SDK. For this tutorial we will be using Windows but the process is pretty much the same cross platform, please consult the SDK documentation for specific command line instructions if your not following this tutorial on Windows. I have installed the SDK in c:/air/ and will be using the following path conventions for the remainder of this tutorial. Once you have installed the SDK, you may like to check its installed by running the following test. Open command prompt and type:
cd c:/air/bin
> adl -help
If you see the usage for the ADL, Installation seems to have worked.
Creating our application directory structure.
Every AIR application written in HTML and Javascript requires a specific layout and application.xml file. First lets create our directory structure. You can download the source to this tutorial here. Go to c:/air/ then create the following folder c:/air/projects and add the directory structure below.
/gmailNotifier/
/gmailNotifier/source/
/gmailNotifier/source/icons/
/gmailNotifier/build/
Creating the Application Descriptor.
Next we create a file called application.xml. This the application config file and instructs the the ADL and ADT how to configure our application for processing during runtime. Create a file called application.xml and add the following code below. Most of the code is self explanatory. But I’ll explain the important parts in brief below.
- filename – is the name which the application will be installed and known as on the desktop.
- content – is the path to our base / initial file.
- width – is the width of the native desktop window.
- height – is the height of the native desktop window.
- icon – sets our icons for use on the desktop.
Planning Our Application.
As with any project we need to do some initial planning ahead of any actual programming. First lets consider the application and what we want it to achieve. The problem – While I’m working at the computer I constantly forget to check my emails then at the end of the day I’m left with an inbox full of emails which require reading. So to spread the work load out over the course of the day I’d like to be notified, then I can simply read each email as I receive them. I use gmail which is google’s email service. They offer an RSS / Atom feed which will simplify the task of accessing gmail in an automated and persistent way.
List of Requirements;
- On start-up verify the gmail account we’d like to connect to.
- Check every 5 minutes for new email.
- Play a sound when an email is received.
- Notify us on the desktop.
Building Our Application
Before we start with the actual code writing I’d like to explain briefly how adobe air works. The Adobe Air SDK contains two components the ADL and the ADT. Both of these applications are command line applications. The ADL is a debug launcher, this allows us to dynamically compile and execute our HTML and Javascript application into a native windows application while testing and building the application. The ADT is a compiler which allows us to certify and package our application into a distribution ready for your users to install and run on their computers.
Okay. Lets write some code, First we’ll build index.html which is our start file for this Adobe Air application.
Learn how to build more applications @ tutorialcadet.com Loading email data...
I’ll explain each piece of code in detail.
window.htmlLoader.navigateInSystemBrowser = true;
The line above is from window.htmlLoader class which makes all our URL’s within the application call the operating systems default browser. We call this from air.aliases.js.
function dateFormatter(str) {
newDat = str.replace(/(\d{4})-(\d{2})-(\d{2})T([0-9:]+)Z/, "$2/$3/$1 $4");
return newDat;
}
Lines: 1 – 7 makeup the function dateFormatter() which handles date formatting direct from gMail feed. Since the gmail feed is specific to the user, the timezone will be the same for each user and their desktop. So we simply replace the non required date information.
IMPORTANT: If you attempt to pass a JavaScript Date through the Adobe AIR SandboxBridge, it loses its type and appears only as Object. – This is a bug which affected both Adobe Air and flex. More
var urlRSS = 'http://mail.google.com/mail/feed/atom';
urlRSS is a variable which holds the URL to gmail’s feed.
function checkNew(xml,current) {
count = $(xml).find('fullcount').text();
if(current == count) {
var snd1 = air.File.applicationDirectory.resolvePath("sounds/alarm.mp3");
var btn1 = new air.Sound(new air.URLRequest(snd1.url));
btn1.play();
window.nativeWindow.notifyUser('critical');
current = count;
}
}
Lines 1-14: Contains program logic which will play a sound via the air.Sound() class and notify the user with nativeWindow.notifyUser when new email is received by checking if the held mail count is less then the new mail count using count and current variables.
function parseXML(xml) {
var loopRes = '';
count = $(xml).find('fullcount').text();
tagline = $(xml).find('tagline').text();
$('#tag').html(tagline + ' ('+ count +')' );
$('#orders').html(count);
//loop entry
$(xml).find('entry').each(function(){
id = $(this).attr('id');
title = $(this).find('title').text();
name = $(this).find('author').find('name').text();
email = $(this).find('author').find('email').text();
issued = $(this).find('issued').text();
dateRec = dateFormatter(issued);
//concat the entries
loopRes = loopRes + '
'+name+''+dateRec+'';
});
//Display the results
$('#result-wrap').html(loopRes);
}
parseXML() an important function in the application, whenever the function is called the gmail feed is parsed, loops each() xml node and displays a list of the feed contents. The feed is passed to an ajax handler to display to users. It also stores count variable which is passed to checkNew().
function persistCheck() {
current = count;
$.ajax({
type: "GET",
url: urlRSS,
cache: false,
dataType: "xml",
success: function(xml) {
parseXML(xml);
checkNew(xml,current);
}
});
}
A jQuery $ajax call which will request the XML feed, If the gmail server provides 200 = OK. The $ajax handle calls success() which in turn calls parseXML() and checkNew().
$(document).ready(function() {
count = 0;
//start initial run
persistCheck();
//set interval
setInterval("persistCheck()",300000); // 5 min betwewn
});
The last piece of code is the jQuery ready() which fires the initial call of persistCheck() and then using javascript’s interval function we set the script off on an infinite loop calling persistCheck every X seconds, I’ve set it to 5 mins.
Compiling Our Application during the build process
While your building and debugging the application, we can compile it on the fly to check our code works. From the command line run the following command:
cd c:/air/bin/
adt c:/air/projects/gmailNotifier/source/application.xml
This will compile and run the application dynamically. Providing error messages from within the command line.
Certifying and Packaging the Application
Before I continue, I want to talk about certifying an application, this is a certificate of trust between you and your user. You certify your application with a security certificate from a third-party provider, such as GlobalSign, Thawte, or VeriSign, they are a certificate authority (CA). All AIR applications must be digitally signed. Its common practice with desktop programming largely due to the unrestricted access desktop programming gives the developer. However we can self – sign a certificate for testing and will be suitable for this tutorial.
Creating a Certificate
From the command line type the following commands;
cd c:/air/bin/
adt -certificate -cn SelfSign -ou QE -o “TutorialCadet.com” -c US 2048-RSA MyCert.p12 mypassword
This will generate a certificate which is required for the next step of the tutorial. Be sure to include this file in /gmailNotifier/.
Packaging our Application.
Last we need to package our application into an .air file which is similar to a windows .exe file and will automatically execute providing the user has already installed the Adobe Air Client.
First add a path to your Environment Variables Path.
C:/air/bin/
On windows 7 you can find this in My Computer > Properties > advanced Settings > Environment Variables > Edit PATH.
Next, On the command line run the following commands.
cd c:/air/projects/gmailNotifier/
adt -package -storetype pkcs12 -keystore c:/air/bin/MyCert.p12 c:/air/projects/gmailNotifier/build/gmailNotifier.air application.xml index.html js sounds icons style images
Then goto c:/air/projects/gmailNotifier/build and execute gmailNotifier.air.
