In the past few days I've given a basic introduction to the resources necessary to work with HTML AIR apps as well as a basic walkthrough of how you can use Aptana for your editing. In today's entry I'm going to cover two things. First - what does working within the AIR framework mean for you as a developer, and secondly, what does a real example look like. As a first example, it isn't HelloWorld per se, but it gives you an idea of what "real" code looks like.
So first off - I've already talked about how a simple HTML page is used as the basis for your AIR application. Along with the application descriptor XML file, that's the minimum you need. But certainly you want to do more than Hello World. You want to tie into the power that the AIR framework gives you. What exactly does AIR allow you to do? Quite a lot actually:
- You can read and write files and directories from the user's machine.
- You can access network resources and do fancy socket type operations.
- You can build in support for drag and drop.
- You can support copy and paste.
- You can work with audio, both playing MP3s as well as accessing the user's microphone.
- You can work with an embedded local database.
- Like any other "real" application, you can create an icon for your application as well as register your application as the handler for a particular file type. Want your application to support .ray files? Doable!
- You can (under certain circumstances) run other applications on the user's system.
- You can create native windows - think about JavaScript window.create on steroids.
- You can create applications that have no UI - think services that run in the background.
And frankly - a lot more too. For the most part, think of any "real" application, and - in general (I won't say 100%) - Adobe AIR will allow you to create it. Even better - you can create it once and ship it out to Windows, Macs, and Linux machines. (This too requires an *. You will see cases where you write code specifically for one platform or the other. So for example, AIR allows you to put an icon in the Windows taskbar. Since that doesn't make sense on the Mac, you will write your code to check for that support.)
Ok - that's cool and all - but how does this happen? Quite simple - AIR extends your HTML application to give JavaScript access to new objects in the DOM. Specifically they are: runtime, nativeWindow, and htmlLoader. You can imagine that your writing code for a browser with super powers. So for example, to get access to a local file, you can do something like this:
var theFile = new runtime.flash.filesystem.file("some path");
If that seems like a bit too much typing, there is a handy-dandy aliases file that ships with the SDK. If you make use of Aptana, it will gladly copy that file into your project. Once you have the aliases file, the code above gets even simpler.
var theFile = new air.File("...");
Ok, so with that out of the way, let's look at our first example. I'll paste the entire code and then go over the details. I've also included the AIR file that you can download and install yourself.
<html>
<head>
<title>Demo working with selected file</title>
<script type="text/javascript" src="lib/air/AIRAliases.js"></script>
<script src="lib/jquery/jquery-1.4.2.js"></script> $(document).ready(function() {
air.trace('App started'); file = air.File.documentsDirectory;
file.addEventListener(air.Event.SELECT, handleSelect); //bind to file button
$("#fileButton").click(function() {
file.browseForOpen("Pick something");
}) //bind to launcher button
$("#launcher").live("click",function() {
if(file.name) file.openWithDefaultApplication();
})
}) function handleSelect(ev) {
air.trace('you picked a file');
var s = "";
s += "Name: " + file.name + "<br/>";
s += "Directory? " + file.isDirectory + "<br/>";
s += "Native path: " + file.nativePath + "<br/>";
s += "Parent: " + file.parent.nativePath + "<br/>";
s += "url: " + file.url + "<br/>";
s += "<input type='button' id='launcher' value='Launch in native app'>"; $("#dump").html(s);
}
</script>
</head>
<body> <input type="button" id="fileButton" value="Click Me">
<div id="dump"></div> </body>
</html>
<script>
var file;
We've got a few things going on here, so let's break it down. I like to start at the bottom normally since I typically use buttons, forms, and DIVs as a way to debug. In this case, you can see I've got one button (fileButton) and one div (dump). Scroll on up to the document.ready block. If by some reason you don't know jQuery, just think of that as "Run me when the page is ready" block. The first "special" line is air.trace. This will send a debug message which Aptana will nicely display for you in the IDE. Think of this as console.log.
Next check out this line:
file = air.File.documentsDirectory;
One of the coolest features of the AIR File API is that it has a few useful shortcuts. The documentsDirectory is one of them. It allows you to point to a user's documents directory no matter what OS they are using. Similar aliases exist for the desktop and other common folders. The next line adds a SELECT handler. We're going to tie our button to a 'pick a file' dialog and need a way to say what method should be run when the file is selected.
So how do we support asking the user to pick a file? In a regular HTML form that would be an input/type=file control. In AIR we can simply prompt the user to pick a file. This can be based on any UI or event. So I simply use jQuery to say that the click event for our button should run browseForOpen. Note - if I wanted to I could require you to pick files of a certain type. I've not done that here.
Skip past the last part of the document.ready block and check out the select handler, handleSelect. This will be run after the user has selected a file. The file object will point to the file on their file system and gives us access to a lot of things. In my example I just worked with a few of them, like name, path, url, etc. Size is there too if you want it. I'd recommend checking the docs out on the File API for more information.
The last part of the puzzle is the laucher button I create. It showcases another cool feature, openWithDefaultApplication. As you can guess, this will ask the OS to run the file with whatever application is registered for it. So on my Mac, PDFs open with Preview, and on my PC it opens with Acrobat. Simple.
To give you some idea of what this looks like, here are two quick screen shots:
The number one thing I want you to take from this is the fact that the "special" parts - ie the file references and such - were all pretty simple. I'd say more code was involved with the jQuery event handlers and the display portion.
Any questions? Tomorrow we look at another file example. You can download the AIR file below.