Adobe AIR Tutorial for HTML / JavaScript Developers

I spent a some time this weekend preparing for the Adobe AIR & Flex 3 Launch Event at my ColdFusion user group. One thing I wanted to show people was how to build a simple Adobe AIR Desktop Application using HTML & JavaScript.

I found the AIR Platform to be both powerful, and very easy to develop with. You really just have to spend a few minutes to see how easy it is!

I mean no disrespect to Flash, and Flex but the single most appealing capability of Adobe AIR is that you can build desktop applications in JavaScript and HTML. Two languages that nearly everyone reading this blog has undoubtedly used, and is probably quite good at already.

Adobe AIR also has an embedded database SQLite, which is an SQL92 & ACID compliant database engine with support for storing databases of up to 1TB. You can use this embedded database in your AIR Apps, and send SQL queries to it using JavaScript!

The learning curve for building an Air Application if you already know JavaScript and HTML is quite small. Run through this quick tutorial and you will be unstoppable!

Step 1 - Install Adobe AIR & the Adobe AIR SDK

If you haven't done so already, head over to Adobe to download and install the Adobe AIR Runtime, and the Adobe AIR SDK.

When you install the Adobe AIR SDK, you will want to add it's bin/ directory to your environment path.

Step 2 - Create Some Directories

Next we need to create some directories for our code, create the following directories:

/appname/
/appname/source/
/appname/source/icons/
/appname/build/

Step 3 - Create an Application Descriptor

Your application descriptor is an XML file that sets some properties for your application.

Let's call this file application.xml and place it in /appname/source/

<application xmlns="http://ns.adobe.com/air/application/1.0">
  <id>com.example.appname </id>
  <version>1.0 </version>
  <filename>AppName </filename>
  <initialWindow>
    <content>index.html </content>
    <visible>true </visible>
    <width>600</width>
    <height>600</height>
  </initialWindow>
  <icon>
    <image16x16>icons/appname-16.png</image16x16>
    <image32x32>icons/appname-32.png</image32x32>
    <image48x48>icons/appname-48.png</image48x48>
    <image128x128>icons/appname-128.png</image128x128>
  </icon>
</application>

It should be pretty obvious what to put for all the values, the icon values will be used as your application icon, you can omit these if you don't really want to create the PNG's, but it's kind of cool to see your own icons.

There are a lot more optional tags you can add, check out the templates/descriptor-template.xml file in the Air SDK.

Step 4 - Create your Application

The next step can be as detailed as you like, but really all you need to do is create an index.html file.

<html>
<head>
  <title>My Window Title</title>
</head>
<body>
  <h1>Hello World</h1>
</body>
</html>

If you want to add CSS, JavaScript, or images, you can create subfolders in your /appname/source/ folder for those assets, and use them just like you would in a normal web application.

Step 5 - Test your Application

You are probably getting pretty anxious to test your new Adobe AIR application, to do that it's pretty simple.

Open up a command prompt, or shell and navigate to /appname/source/ then run the following command:

adl application.xml

If all goes well your application should launch. There is a good chance however that you ignored my suggestion to add the airsdk/bin directory to your system environment path, in which case you got something like adl not found. If that is the case then simply append the full path to your SDK bin to the command, for example:

c:\air\bin\adl application.xml

Step 6 - Package Your Application

Once you have tested your application, or are ready to show your friends, or just want see how your icon looks in the Dock you are ready to packing your Air Application.

This step will be a bit cumbersome the first time because all Adobe Air application code must be digitally signed. Code signing, is a bit like using SSL, you get a certificate from a trusted source, and then people will know who wrote the application. This is important because the Adobe AIR platform allows you to access local files, and do all sorts of things that could really screw things up.

Chances are you really just want to show your new application to a few people, and not the entire world. If that's the case then you can easily create a self signed certificate. It is important that the Certificate is not placed in your source directory, so let's place it in the root of our application: /appname/

adt -certificate -cn SelfSign -ou Dev -o "Example" -c US 2048-RSA cert.pfx password

Now once we have a code signing certificate we can create an Air application Package. Change directories back into source and run:

adt -package -storetype pkcs12 -keystore ../cert.pfx ../build/AirTest.air application.xml .

You should now have an AppName.air file that you can send to your friends, or simply run it on your own computer.

References

Like this? Follow me ↯

Follow @pfreitag

Adobe AIR Tutorial for HTML / JavaScript Developers was first published on February 25, 2008.

If you like reading about adobe, air, html, javascript, or ajax then you might also like:

Comments

Straight and to the point. Thank you much, this was just was I was looking for.

by rob on 02/25/2008 at 5:12:26 PM UTC

You're Welcome Rob.

by Pete Freitag on 02/26/2008 at 10:17:04 AM UTC

@WrongWay What leads you to think AIR won't be released on linux? They are currently accepting beta tests for AIR on linux, email: helptesterairlinux@adobe.com

See http://www.beedigital.net/blog/?p=1863 for more info.

by Pete Freitag on 02/26/2008 at 11:58:28 AM UTC

hi pete,

outstanding example! thanks much. i had a little bit of a snag when trying to replicate it, as the ADT tool was saying the paths to the PNGs was "unsupported format".

however, i got it to run eventually by commenting out the ICON node in application.xml and running the command-line tools.

baby steps. i'll figure it out. :-)

by Jason Salas on 03/16/2008 at 7:43:08 PM UTC

Great tutorial - just what is needed! Simplicity above all, unfortunately adobe sites are not that simple most of the times.

I have followed all the steps, my application launches successfully. I have also issued a temp certificate as per your instructions, but when I try to package I get a message "could not load keystore file (password may be incorrect)". I guess the password is the one that is set in the certificate generation step, right? Still this doesn't work ...

any advice?

thanks!

by George on 03/29/2008 at 2:35:56 AM UTC

hi i want to know how to config and use ajax in eclipse environment

by ramamoorthy on 04/02/2008 at 2:42:00 AM UTC

Hi,

Do you have any example to use database with html, in air.?

by naed on 05/07/2008 at 6:03:07 AM UTC

I have followed all the steps, my application launches successfully. I have also issued a temp certificate as per your instructions, but when I try to package I get a message "could not load keystore file (password may be incorrect)". I guess the password is the one that is set in the certificate generation step, right? Still this doesn't work ...

me too !!

by Marsza on 06/29/2008 at 9:52:35 PM UTC

Hi, me again. When compiling to exec, I noticed Ubuntu didn't like trailing spaces after some values in between the XML tags.

Also...
If you get a time stamp error, just add -tsa none after the name of the certificate

and...
check out a free ebook called AIR for Javascript Developers

by Leon on 01/17/2009 at 3:25:24 AM UTC

Hi thanks for the tutorial its awesome . It helped me a lot in my work , i am still at the beginner level. Can you please point me to a direction where i can learn more about the adt command line options also for the the application xml ?
thanks in advance .
isnain

by isnain on 01/25/2009 at 3:50:16 AM UTC

Hi Isnain,

Check it out at http://help.adobe.com/en_US/AIR/1.5/devappshtml/WS5b3ccc516d4fbf351e63e3d118666ade46-7fd7.html

:-)

by George on 01/26/2009 at 1:44:22 AM UTC

could not load keystore file (password may be incorrect)" is caused by typing "adt ?certificate -cn SelfSigned 1024-RSA sampleCert.pfx samplePassword", where samplePassword is you need to type pkcs12

by Jason on 02/15/2009 at 12:56:38 AM UTC

Thanks. it a nice step by step example.
at the final step while creating .air file i m getting error "Could not generate timestamp: Connection timed out: connect"
.
Plz help me out.

by Gaurav on 03/12/2009 at 2:50:33 AM UTC

The problem I ran into is: at least one file is required when I tried to package my application from running the above packaging code. Any suggestions?

by dennismonsewicz on 01/11/2010 at 2:05:25 PM UTC

Disregard my last comment... I was leaving out the . [dot] after the application.xml

by dennismonsewicz on 01/11/2010 at 2:14:19 PM UTC

Hi,

Thanks for you work. I tried the adl -package but I got this error message... could not load keystore file (password may be incorrect).

by boe var on 02/07/2010 at 10:32:28 AM UTC

Hi,
thanks for the training really appreciate it, can i deploy my coldfusion code that connects to the database with air.

by Mama jee on 02/22/2010 at 1:11:34 PM UTC

Excellent tutorial. I copied icons from another example otherwise you should comment out those lines. Also I had to type password as the password to get it to work.

by Lou Prado on 03/03/2010 at 5:24:09 PM UTC

Excellent tutorial. I copied icons from another example otherwise you should comment out those lines. Also I had to type password as the password to get it to work.

by Lou Prado on 03/03/2010 at 5:35:40 PM UTC

Excellent, gonna try tonight...

by Sajjad Anwar on 06/19/2010 at 12:49:07 PM UTC

Hi,

This is the good article on javascript

by Deep on 06/25/2010 at 5:22:10 AM UTC

@pi-Ratas Dude u forgot the dot (current dir) at the end of the command :

adt -package -storetype pkcs12 -keystore ../cert.pfx ../build/AirTest.air application.xml <b>.</b> <-

by TJ on 08/17/2010 at 3:18:34 AM UTC

I'm confused where do i run that adt thingy?

by protoboy on 11/10/2010 at 5:43:41 AM UTC

Awesome Post. I add this Post to my bookmarks.

by caruvtam on 12/23/2010 at 1:01:48 AM UTC

Make sure the command is not being executed in a folder that has restricted access privileges to avoid the "could not load keystore file". Just try the command somewhere else.

by GeorgeMcK on 01/01/2011 at 4:01:27 PM UTC

What I thought was a password error was actually the fact that I was missing additional files namely my index.html in addition to the xml file...

by Dimitri on 04/20/2011 at 4:57:41 PM UTC

I ran into some compilation errors at first after running adt. The culprit was XML white spaces and paths to the icons, and lastly, looking in the source dir instead of the build for the .air ;)

by Dimitri on 05/05/2011 at 4:56:49 PM UTC

How to add and run the video file *.mp4 in the html and get the output for adobe air

by LOL on 04/26/2012 at 3:54:23 AM UTC

you ok paul i got it from a mate so this is the contact
filing address , there very helpfull ,just say Howard hemtom give you there number

by Howardhemtom on 05/27/2012 at 3:54:25 PM UTC

i got message when i execute the command adl application.xml

application descriptor not found .

even i m in my application folder

by Neelu Singh on 06/05/2012 at 5:21:01 AM UTC

yous ok susie sorry mate i`v took so long here is the web address and details , there very helpfull ,tell them fetons
recommended you

by davyfetons on 12/08/2012 at 5:16:04 PM UTC