Adobe Integrated Runtime (AIR) for JavaScript Developers Pocket Guide

BUY THIS BOOK

Print Book $14.99

Safari Books Online

What is this?

Print Book £9.99

What is this?

Looking to Reprint this content?

Tell a friend

Adobe Integrated Runtime (AIR) for JavaScript Developers Pocket Guide By Mike Chambers, Daniel Dura, Kevin Hoyt

Cover | Table of Contents

Chapter 1: Introduction to the Adobe Integrated Runtime (AIR)

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The Adobe Integrated Runtime (AIR) is a cross-platform desktop runtime being developed by Adobe that allows web developers to use web technologies to build and deploy Rich Internet Applications and web applications to the desktop.

Prior to the public beta release, the Adobe Integrated Runtime (AIR) was referred to in public by its code name of Apollo.

In order to better understand what Adobe AIR enables, and which problems it tries to address, it is useful to first take a look at the (relatively short) history of web applications.

Over the past couple of years, there has been an accelerating trend of applications moving from the desktop to the web browser. This has been driven by a number of factors, which include:

Growth of the Internet as a communication medium
Relative ease of deployment of web applications
Ability to target multiple operating systems via the browser
Maturity of higher-level client technologies, such as the browser and the Flash Player runtime

Early web applications were built primarily with HTML and JavaScript, which, for the most part, relied heavily on client/ server interactions and page refreshes. This page refresh model was consistent with the document-based metaphor for which the browser was originally designed, but provided a relatively poor user experience when displaying applications.

With the maturation of the Flash Player runtime, however, and more recently Ajax-type functionality in the browser, it became possible for developers to begin breaking away from page-based application flows. Developers began to be able to offer richer application experiences via the browser. In a whitepaper from March 2002, Macromedia coined the term rich Internet application (RIA), to describe these new types of applications in browsers, which "blend content, application logic and communications…to make the Internet more usable and enjoyable." These applications provided richer, more desktop-like experiences, while still retaining the core cross-platform nature of the Web:

Internet applications are all about reach. The promise of the web is one of content and applications anywhere, regardless of the platform or device. Rich clients must embrace and support all popular desktop operating systems, as well as the broadest range of emerging device platforms such as smart phones, PDAs, set-top boxes, game consoles, and Internet appliances.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

A Short History of Web Applications

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Over the past couple of years, there has been an accelerating trend of applications moving from the desktop to the web browser. This has been driven by a number of factors, which include:

Growth of the Internet as a communication medium
Relative ease of deployment of web applications
Ability to target multiple operating systems via the browser
Maturity of higher-level client technologies, such as the browser and the Flash Player runtime

Internet applications are all about reach. The promise of the web is one of content and applications anywhere, regardless of the platform or device. Rich clients must embrace and support all popular desktop operating systems, as well as the broadest range of emerging device platforms such as smart phones, PDAs, set-top boxes, game consoles, and Internet appliances.

You can find the complete whitepaper and more information on RIAs at: http://download.macromedia.com/pub/flash/whitepapers/richclient.pdf

The paper goes on to list some features that define RIAs:

Provide an efficient, high-performance runtime for executing code, content, and communications.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Problems with Delivering Applications via the Browser

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

As web applications have become more complex, they have begun to push the boundaries of both the capabilities of the browser and the usability of the application. As their popularity grows, these issues become more apparent and important and highlight the fact that there are still a number of significant issues for both developers and end users when deploying and using applications within the browser.

The web browser was originally designed to deliver and display HTML-based documents. Indeed, the basic design of the browser has not significantly shifted from this purpose. This fundamental conflict between document and application-focused functionality creates a number of problems when deploying applications via the browser.

Applications deployed via the browser have their own user interface, which often conflicts with the user interface of the browser. This application within an application model often results in user interfaces that conflict with and contradict each other. This can lead to user confusion in the best cases, and application failure in the worst cases. The classic example of this is the browser's Back button. The Back button makes sense when browsing documents, but it does not always make sense in the context of an application. Although there are a number of solutions that attempt to solve this problem, they are applied to applications inconsistently and users may not know whether a specific application supports the Back button, or whether it will force their application to unload, causing it to lose its state and data.

Due in part to the web security model (which restricts access to the user's machine), applications that run in the browser often do not support the type of user interactions with the operating system that people expect from applications. For example, you cannot drag a file into a browser-based application and have the application act on that file. Nor can the web application interact with other applications on the user's computer.

RIAs have tried to improve on this by making richer, more desktop-like interfaces possible in the browser, but they have not been able to overcome the fundamental limitations and separation of the browser from the desktop.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Introducing the Adobe Integrated Runtime

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

So, what is Adobe AIR, and how can it make web application development and deployment better?

The Adobe Integrated Runtime (AIR) is a cross-operating system runtime being developed by Adobe that allows web developers to leverage their existing web development skills (such as Flash, Flex, HTML, JavaScript, and PDF) to build and deploy rich Internet applications and content to the desktop.

In essence, Adobe AIR provides a platform in between the desktop and the browser, which combines the reach and ease of development of the web model with the functionality and richness of the desktop model.

It is important to step back for a second and point out what Adobe AIR is not. Adobe AIR is not a general desktop runtime meant to compete with lower-level application runtimes. Adobe AIR is coming from the web to the desktop and is targeted at web developers. Its primary use case is enabling web applications and RIAs to be deployed to the desktop. This is a very important but subtle distinction, as enabling web applications and RIAs on the desktop is the primary use case driving the Adobe AIR 1.0 feature set.

At its core, AIR is built on top of web technologies, which allow web developers to develop for and deploy to the desktop using the same technologies and development models that they use today when deploying applications on the Web.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Primary AIR Technologies

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

There are three primary technologies included within Adobe AIR, which fall into two distinct categories: application technologies and document technologies.

Application technologies are technologies that can be used as the basis of an application within Adobe AIR. Adobe AIR contains two primary application technologies, HTML and Flash, both of which can be used on their own to build and deploy AIR applications.

HTML / JavaScript

The first core application technology within Adobe AIR is HTML and JavaScript. This is a full HTML-rendering engine, which includes support for:

HTML
JavaScript
CSS
XHTML
Document Object Model (DOM)

Yes, you read that right. You don't have to use Flash to build Adobe AIR applications. You can build full-featured applications using just HTML and JavaScript. This usually surprises some developers who expect Adobe AIR to focus only on Flash. However, at its core, Adobe AIR is a runtime targeted at web developers using web technologies—and what's more of a web technology than HTML and JavaScript?

The HTML engine used within Adobe AIR is the open source WebKit engine. This is the engine behind a number of browsers, including KHTML on KDE and Safari on Mac OS X.

You can find more information on the WebKit open source project at http://www.webkit.org.

See , "Working with JavaScript and HTML within Adobe AIR", for a more in-depth discussion of WebKit within Adobe AIR.

Flash

The second core application technology that Adobe AIR is built on is the Flash Player. Specifically, Adobe AIR is built on top of Flash Player 9, which includes the ECMAScript based ActionScript 3, as well as the open source Tamarin virtual machine (which will be used to interpret JavaScript in future versions of Firefox).

You can find more information on the open source Tamarin project at on the Mozilla web site at http://www.mozilla.org/projects/tamarin/.

Not only are all of the existing Flash Player APIs available within Adobe AIR, but some of those APIs have also been expanded and/or enhanced. Some of the functionality that the Flash Player provides to Adobe AIR includes:

Just-in-time Interpreted ActionScript engine for speedy application performance

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 2: Getting Started with AIR Development

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter discusses how to get started developing applications for the Adobe Integrated Runtime using HTML and JavaScript. It covers:

Installing Adobe AIR
Configuring the Adobe AIR SDK and command-line tools
Creating your first AIR application
Testing AIR applications
Packaging and deploying AIR applications

Once you have completed this chapter, your environment for developing AIR applications should be correctly configured, and you should have an solid understanding of how to begin to build, test, and deploy AIR applications.

There are a number of required items needed in order to begin developing AIR applications.

The AIR Beta is required to test application icons, as well as deployment of AIR applications. The Beta runtime can be downloaded for free from:

http://www.adobe.com/go/air

The Adobe AIR SDK contains command-line tools, sample files, and other resources to make developing AIR applications easier. In particular, we will be using the command-line tools included in the SDK (ADL and ADT), which will allow us to test and package our AIR applications from virtually any development environment.

You can download the AIR SDK for free from:

http://www.adobe.com/go/air

Building AIR applications with HTML and JavaScript requires that you have a way to create the HTML and JavaScript files. You can use any tool that supports creating and editing text files (such as VIM or Notepad), although it's recommended that you use a tool that has richer support for working with HTML and JavaScript files, such as Adobe Dreamweaver, Panic's Coda, or Aptana.

While it is possible to develop and package AIR applications on virtually any operating system (including Linux), you can test and deploy the application only on operating systems supported by Adobe AIR.

The supported operating systems for the Beta are:

Windows XP SP2
Windows Vista Home Ultimate Edition
Mac OS 10.4.8 and 10.4.9 (Intel and PowerPC)

Adobe AIR will support additional versions of Mac and Windows for the 1.0 release, and Linux shortly after the 1.0 release.

If you have previously installed an earlier version of Adobe AIR (formerly referred to as Apollo), you need to uninstall those versions before installing the Beta version.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

What Do You Need to Develop AIR Applications?

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

There are a number of required items needed in order to begin developing AIR applications.

The AIR Beta is required to test application icons, as well as deployment of AIR applications. The Beta runtime can be downloaded for free from:

http://www.adobe.com/go/air

You can download the AIR SDK for free from:

http://www.adobe.com/go/air

The supported operating systems for the Beta are:

Windows XP SP2
Windows Vista Home Ultimate Edition
Mac OS 10.4.8 and 10.4.9 (Intel and PowerPC)

Adobe AIR will support additional versions of Mac and Windows for the 1.0 release, and Linux shortly after the 1.0 release.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Uninstalling Pre-Beta Versions of Adobe AIR

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

If you have previously installed an earlier version of Adobe AIR (formerly referred to as Apollo), you need to uninstall those versions before installing the Beta version.

In the Windows Start menu, select Settings → Control Panel.
Select the Add or Remove Programs control panel.
Select Adobe Apollo 1.0 Alpha1 to uninstall the Apollo runtime.
Click the Change/Remove button.

Delete the /Library/Frameworks/Adobe Apollo.framework directory.
Delete the /Library/Receipts/Adobe Apollo.pkg file.
Empty the Trash.

Once you have done this, you are ready to install the Beta runtime.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Installing Adobe AIR

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

While it is not necessary to have Adobe AIR installed on your computer in order to develop and test AIR applications, it is useful to have in order to try other AIR applications and to test your final application's deployment and packaging.

Installing the runtime is simple, and requires downloading and running the Adobe Integrated Runtime Installer.

Download AIR Installer from http://www.adobe.com/go/air
Launch the installer. On a Mac, you must first mount the .dmg file, which contains the installer.
Follow the installation instructions.

As Adobe AIR is simply a runtime and not an application that can be launched, the easiest way to confirm that it is installed correctly is to try installing an AIR application.

You can do this by either downloading an AIR application and installing it, or following the instructions later in the chapter to build a simple AIR application.

You can download sample AIR applications from Adobe's web site at: http://www.adobe.com/go/air.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Uninstalling Adobe AIR Beta

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The process for uninstalling Adobe AIR is different depending on the operating system that you are running on.

The Adobe AIR installer places an uninstall application on the user's system when it is installed. To uninstall the Adobe Integrated Runtime, launch the uninstaller named Adobe AIR Uninstaller which can be found in the /Users/<User>/Applications directory (where <User> is your system user account name).

On Windows, you can uninstall Adobe AIR the same way that you uninstall any other application. Just select the Adobe Integrated Runtime in the add/remove programs section of the control panel.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Setting Up the AIR SDK and Command-Line Tools

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The Adobe AIR SDK Beta contains tools, samples, and code that makes it easier to develop, test and deploy applications.

In particular, it contains two command-line tools that we will use:

ADL	This is used to launch and test an AIR application without having to first install it.
ADT	This is used to package an AIR application for distribution.

In order to ease development, you should place the path to these files within your system's path. This will allow you to execute the tools from anywhere on your system.

The command line tools are located in the bin directory within the SDK.

Download the AIR SDK Beta from http://www.adobe.com/go/air.
Open the SDK
1. On Windows, uncompress the ZIP archive.
2. On Mac, mount the .dmg file.
Copy the contents of the SDK to your system (we will refer to this location as <SDK_Path>.
In order to run the command-line tools, you need to copy only the bin and runtime directories from the SDK.
It's important that the bin and runtime directories within the SDK maintain their relative paths to each other.
At this point, you should have at least the following two directories: <SDK_Path>/bin and <SDK_Path>/runtime. The ADL and ADT command-line tools are located in the bin directory.

All that's left is to place the <SDK_Path>/bin directory into your system path, so that you can execute the command line applications from anywhere on your system.

The instructions for this are different depending on whether you are on a Mac- or Windows-based system.

Open the System Properties dialog box and click the Advanced tab. You can find this in the System settings in the Control Panel.
Click the Environment Variables button.
Select the PATH entry and then click the Edit button. Add the path to the bin directory to the end of the current variable value, separating it from previous values with a semicolon:
```
	;<SDK_Path>/bin
```
shows the process.
Click OK to close the panels.

Figure : Placing command-line tools in the system path on Windows

In order to test the installation, open a new Windows Console (Start → Run → Console), and type:

adt

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Creating a Simple AIR Application with HTML and JavaScript

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Now that you have installed and configured Adobe AIR and the Adobe AIR SDK Betas, we are ready to build our first AIR application.

We will build a very simple "hello world" example. Once you have built and tested the application, your development environment will be set up and ready to build more complex and functional AIR applications.

Every AIR application contains a minimum of two files. The first file is the root content file. This is the main HTML or SWF file for the application, and is the file that will be displayed/executed when the application first starts up.

The second file is called the application descriptor file, which is an XML file that provides metadata to Adobe AIR about the application.

Let's create these files for our application:

Create a new folder called AIRHelloWorld.
Inside of this folder, create two new files called AIRHelloWorld.html and AIRHelloWorld.xml.
Open each of these files using your favorite text or HTML editor/IDE.

Understanding application descriptor files

The application descriptor file is an XML file required for each AIR application. It provides general metadata (such as application name and description) to Adobe AIR, as well as information on how the application should be run. This includes specifying the root application file for the application and the window mode that the initial application window should use.

First, let's look at the entire application descriptor file (AIRHelloWorld.xml) for our application, and then we will go into more detail on each item within the file.

You can find a sample application descriptor file in the AIR SDK in the templates folder.

Open AIRHelloWorld.xml and type in the following text:

	<?xml version="1.0" encoding="UTF-8"?>
	<application xmlns="http://ns.adobe.com/air/application/1.0.M4"
	                     appId="com.oreilly.AIRHelloWorld"
	                     version="1.0">

	      <name>AIRHelloWorld</name>
	      <title>AIRHelloWorld Installer</title>
	      <description>Simple Hello World Example
	        using HTML</description>
	      <copyright></copyright>

	      <rootContent systemChrome="standard"
	                  transparent="false" visible="true">
	ApolloHelloWorld.html</rootContent>

	</application>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Testing the Application

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

While there are a number of HTML IDEs (such as Dreamweaver) that are adding support for launching and testing AIR applications directly from within the IDE, we will focus on launching and testing AIR applications using the ADL command-line tool included within the SDK. This will provide a solid basis for an understanding of what is going on. It will also provides the most flexibility in integrating the development process with other IDEs, editors and workflows.

The first step in testing the application is to run it as an AIR application to make sure that:

There are no errors in the application descriptor file
The application launches
The HTML renders correctly
The JavaScript code functions as expected

While we could package up the entire application and then install it, this would be tedious, and make it difficult to quickly iterate on and test new versions. Luckily, the Adobe AIR SDK provides a command-line tool called ADL, which allows you to launch an AIR application without having to first install it.

In order to test our application:

Open a Terminal window (on Mac) or a Console window (on Windows).
Change to the directory that contains the AIRHelloWorld.html and AIRHelloWorld.xml files.
Run ADL with the following command, passing in the name of the application descriptor file:
```
	adl AIRHelloWorld.xml
```

This should launch your application within the standard system chrome of your operating system.

Figure : AIRHelloWorld application running from ADL on Mac OS X

If the application does not launch correctly, or if you get an error, check the following:

Make sure you have configured the SDK correctly, so that the ADL tool can be found.
Make sure that you are running the ADL command from the same directory that contains the AIRHelloWorld.xml file.
Make sure that your application descriptor file contains well-formed XML.
Make sure the information in the application descriptor file is correct. Pay particular attention to the application attributes and the rootContent value.
Make sure that the AIRHelloWorld.html and AIRHelloWorld.xml files are in the same directory.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Packaging and Deploying the AIR Application

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Now that we understand how to build, test and debug an AIR application, we are ready to create an AIR file which will allow us to deploy and distribute our application.

An AIR file is a zip-based application distribution package that is used to distribute AIR applications. It contains all of the files necessary to install and run an AIR application, and is used by the Adobe Integrated Runtime to create and install an AIR application onto the user's system.

The AIR file is created by the ADT command line tool included in the AIR SDK and is used to distribute the application to other users.

AIR files require that Adobe AIR already be installed on the user's system.

ADL will be able to also create OS-specific native installers that will be able to first install Adobe AIR and then install the AIR application for systems where Adobe AIR is not already installed.

This functionality is not yet implemented in the public Beta.

An AIR file requires a minimum of two files, the application descriptor file, and a root application file. However, you can also include other files, icons, directories, and assets that will be bundled with the AIR file, and installed alongside your application. These files will then be available to the application at runtime.

The ADT command-line tool included in the Adobe AIR SDK is used to create AIR files. Its usage format is:

	adl –package AIRFILENAME FILESTOINCLUDE

To create an AIR file for our application:

Open a terminal (Mac OS X) or Console (Windows) window.
Change to the directory which contains AIRHelloWorld.html and AIRHelloWorld.xml.

Run the following command:

	adt -package AIRHelloWorld.air AIRHelloWorld.xml
	AIRHelloWorld.html

This should create a file named AIRHelloWorld.air in the same directory. If the file is not created, or if you receive any errors:

Make sure you have configured the SDK correctly in order to ensure that the ADT tool can be found.
Make sure that you are running the ADT command from the same directory that contains the AIRHelloWorld.xml file.
Make sure that your application descriptor file contains well formed XML.
Make sure the information in the application descriptor file is correct. Pay particular attention to the application attributes, and the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 3: Working with JavaScript and HTML Within AIR

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter provides an in-depth overview of the HTML and JavaScript environments within the Adobe Integrated Runtime. It discusses:

The use of the open source WebKit HTML-rendering engine within Adobe AIR
JavaScript functionality within Adobe AIR
AIR-specific implementations of functionality
Working with AIR, Flash Player and ActionScript APIs from JavaScript

Once you have completed this chapter, you should have a solid understanding of the HTML and JavaScript environments within Adobe AIR. You should also understand how to work with AIR and ActionScript APIs within HTML and JavaScript-based applications.

Adobe AIR leverages the open source WebKit-rendering engine to add support for rendering HTML content to the runtime.

In addition to HTML rendering, WebKit also provides support for associated web technologies, such as:

JavaScript
XMLHttpRequest
CSS
XHTML
W3C DOM Level 2 support

Essentially, Adobe AIR has a full HTML rendering engine, and includes support for of the same technologies that can be used when developing web applications and content targeting the web browser. Developers can build full-featured AIR applications that leverage these technologies.

You can find more information on the WebKit project at: http://www.webkit.org.

Adobe spent a considerable amount of time researching which HTML engine to use within Adobe AIR and used a number of criteria that ultimately led them to settle on WebKit.

Open project

Adobe knew from the very beginning that it did not want to create and maintain its own HTML rendering engine. Not only would this be an immense amount of work, but it would also make it difficult for developers, who would then have to become familiar with all of the quirks of yet another HTML engine.

WebKit provides Adobe AIR with a full-featured HTML engine that is under continuous development by a robust development community that includes individual developers as well as large companies such as Nokia and Apple. This allows Adobe to focus on bug fixes and features, and also means that Adobe can actively contribute back to WebKit, while also taking advantage of the contributions made by other members of the WebKit project.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

WebKit Within the Adobe Integrated Runtime

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Adobe AIR leverages the open source WebKit-rendering engine to add support for rendering HTML content to the runtime.

In addition to HTML rendering, WebKit also provides support for associated web technologies, such as:

JavaScript
XMLHttpRequest
CSS
XHTML
W3C DOM Level 2 support

You can find more information on the WebKit project at: http://www.webkit.org.

Adobe spent a considerable amount of time researching which HTML engine to use within Adobe AIR and used a number of criteria that ultimately led them to settle on WebKit.

Open project

Proven technology that web developers know

As discussed earlier, one of the biggest problems with complex web application development is ensuring that content works consistently across browsers. While something may work perfectly in Firefox on the Mac, it may completely fail in Internet Explorer on Windows. Because of this, testing and debugging browser-based content can be a nightmare for developers.

Adobe wanted to ensure that developers were already familiar with the HTML engine used within Adobe AIR, so they did not have to learn all of the quirks and bugs of a new engine. Since Safari (which is built on top of WebKit) is the default browser for Mac OS X (and is also available on Windows), developers should be familiar with developing for WebKit.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

JavaScript Within AIR

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Adobe AIR has full support for JavaScript within HTML content. JavaScript 1.5, which corresponds to ECMA-262 is supported.

The JavaScript engine is implemented via WebKit, and works the same as it does within WebKit-based browsers. In addition to having access to the HTML DOM, JavaScript can also access AIR and Flash Player APIs directly via the window.runtime property. This will be discussed in more detail later.

For an in-depth introduction and discussion of JavaScript, check out JavaScript: the Definitive Guide: 5th Edition, published by O'Reilly:

http://www.oreilly.com/catalog/jscript5/

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

AIR Implementation of Functionality

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

HTML and JavaScript functionality is consistent with that found in other WebKit-based projects and browsers, such as Apple's Safari browser. When exploring documentation on HTML engine / browser functionality, you can use references to the Safari browser as an indicator of the functionality available within the HTML environment within AIR.

However, because the HTML engine is running in a runtime, and not a browser, there are a few differences that are useful to understand before beginning development with HTML and JavaScript within Adobe AIR.

The Adobe Integrated Runtime has full support for setting and getting cookies from HTML-based content. Cookie support is implemented via the operating system's networking stack. This means that AIR applications can share cookies set by any browser or application that also leverage the operating system stack.

For example. AIR applications can share cookies set through Internet Explorer on Windows, and Safari on Mac, as they both also use the operating system's cookie storage functionality. Firefox implements its own cookie storage and thus cookies set within Firefox cannot be shared with AIR applications.

In addition to cookies, AIR applications have a number of other APIs that can be used for persistent data, including the file API, as well as the embedded database API.

Windows

You can create new windows via JavaScript just as you can within the browser.

	myWindow = window.open("Window.html", "myWindow",
	"height=400,width=400");

However, the runtime property which provides access to AIR and Flash Player APIs is not automatically available within the new window. In order to make it available, you must explicitly place it within the scope of the new window like so:

	window.runtime = window.opener.runtime;

Full support of native windows is not available within the Beta. Only APIs available from JavaScript have been implemented.

Dialogs

HTML dialogs are also supported within AIR applications, although not all have been implemented within the Beta.

Dialog	Supported in Beta
alert	yes
confirm	yes
prompt	no

In addition, the file-browsing dialog created via:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Accessing AIR APIs from JavaScript

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

In addition to the standard JavaScript and HTML DOM APIs, JavaScript code running within the application context in an AIR application can also take advantage of APIs provided by the runtime, as well as Flash Player APIs and even ActionScript 3 libraries. This greatly extends the capabilities of JavaScript over the APIs available in the browser, and includes functionality such as:

Playing sounds
Manipulating images and bitmaps
Reading and writing files to and from the local file system
Creating, controlling and manipulating native windows
Making direct socket connections (both binary and text based)
Accessing the clipboard
Leveraging an embedded database to store data

You can find examples of how to leverage these features in the cookbook section in .

This section discusses how to leverage AIR and Flash Player APIs from JavaScript, as well as how to load and leverage compiled ActionScript libraries from within JavaScript.

Most AIR and Flash Player APIs are contained within packages (similar to how many JavaScript frameworks leverage namespaces and packages). This helps organize the APIs, and also reduces the possibility of naming conflicts. When accessing AIR and Flash Player APIs directly from JavaScript, you must do so via their complete package path and name.

As discussed earlier, all AIR and Flash Player APIs are made available via the window.runtime property. The runtime property is at the root of the runtime environment, and all APIs are relative to this root.

For example, to access an API which is not contained within a package, such as trace() you reference it directly from the runtime property, like so:

	window.runtime.trace("foo");

However, if you want to access an API that is contained within a package, you must prepend the package path to the API. For example, to access the amount of memory currently used by the application, you can call the totalMemory Flash Player property that is in the flash.system.System class. To call this API from JavaScript:

	var mem = window.runtime.flash.system.System.totalMemory;

This also applies when creating new instances of an API class from within JavaScript:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 4: AIR Mini-Cookbook

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter describes solutions to common tasks when developing AIR applications. The solutions in this chapter illustrate many concepts used in AIR application development, and provide working HTML and JavaScript code that can be leveraged within your application.

All examples in this chapter assume you are using the AIRAliases.js file.

Problem

You want to create custom window chrome for your application and need the ability for the user to close and minimize the application.

Solution

Use native window APIs within Adobe AIR to hook up, minimize, and close button functionality.

Discussion

While Adobe AIR allows developers to completely define and customize the application's window chrome, it is important to remember that the application is responsible for every type of windowing event that might normally occur. This means connecting the various visual elements with their respective operating system events.

The NativeWindow instance that represents the main application window is not directly accessible from inside the main HTML DOM. Using AIR APIs, an application can traverse outside of the HTML control, out to the Stage, and get a reference to its NativeWindow instance. Once a reference to the native window has been obtained, the appropriate methods can be called to trigger the operating-system specific event (or vice versa). In the case of being able to minimize the window, the application can use NativeWindow.minimize() and NativeWindow.close() in the case of closing:

	window.htmlControl.stage.window.minimize( );
	window.htmlControl.stage.window.close( );

The NativeWindow.close() event does not necessarily terminate the application. If only one application window is available, the application will terminate. If there are multiple windows, they will close until only one window remains. Closing the last window terminates the application.

application.xml

	<?xml version="1.0" encoding="utf-8" ?>
	<application
	    xmlns="http://ns.adobe.com/air/application/1.0.M4"
	    appId="com.adobe.demo.html.CustomChrome"
	    version="1.0 Beta">

	       <name>Custom Chrome</name>
	       <title>Custom Chrome</title>

	    <rootContent
	        visible="true"
	        transparent="true"
	        systemChrome="none"
	        width="206"
	        height="206">

	        custom.html

	    </rootContent>

	</application>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Application Chrome

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Problem

You want to create custom window chrome for your application and need the ability for the user to close and minimize the application.

Solution

Use native window APIs within Adobe AIR to hook up, minimize, and close button functionality.

Discussion

	window.htmlControl.stage.window.minimize( );
	window.htmlControl.stage.window.close( );

application.xml

	<?xml version="1.0" encoding="utf-8" ?>
	<application
	    xmlns="http://ns.adobe.com/air/application/1.0.M4"
	    appId="com.adobe.demo.html.CustomChrome"
	    version="1.0 Beta">

	       <name>Custom Chrome</name>
	       <title>Custom Chrome</title>

	    <rootContent
	        visible="true"
	        transparent="true"
	        systemChrome="none"
	        width="206"
	        height="206">

	        custom.html

	    </rootContent>

	</application>

index.html

	<html>
	<head>

	<title>Custom Window Controls</title>

	<style>
	body {
	   background-image: url( 'custom-chrome.gif' );
	   font-family: Verdana, Geneva, Arial, Helvetica, sans-serif;
	   font-size: 12px;
	}

	#closer {
	    position: absolute;
	    width: 70px;
	    left: 68px;
	    top: 105px;
	}

	#minimize {
	    position: absolute;
	    width: 70px;
	    left: 68px;
	    top: 75px;
	}

	textarea {
	    position: absolute;
	    left: 8px;
	    right: 8px;
	    bottom: 8px;
	    top: 36px;
	    border-color: #B3B3B3;
	}

	#title {
	    position: absolute;
	    font-weight: bold;
	    color: #FFFFFF;
	}
	</style>

	<script type="text/javascript" src="AIRAliases.js"></
	script>

	<script>
	function doClose( )
	{
	    window.htmlControl.stage.window.close( );
	}

	function doLoad( )
	{
	    document.getElementById( "minimize" ).
	addEventListener( "click", doMinimize );
	document.getElementById( "closer" ).addEventListener(
	"click", doClose );
	}

	function doMinimize( )
	{
	    window.htmlControl.stage.window.minimize( );
	}
	</script>

	</head>
	<body onload="doLoad( )">

	<input id="minimize" type="button" value="Minimize" />
	<input id="closer" type="button" value="Close" />

	</body>
	</html>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Windowing

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Problem

You need to display an additional widow into which additional content can be loaded.

Solution

Basic windows can be generated and maintained in a similar fashion as traditional HTML content using the window.open() method.

Discussion

The JavaScript window.open() method invokes a new window similar to the way it would when used in the browser. Content that gets loaded into the new window can come from a local file, or URL endpoint. Similar to windows created using JavaScript in the browser, there is finite control over the window itself. The window properties that can be controlled are width, height, scrollbars, and resizable.

	var login = window.open( "login.html", "login", "width =
	300, height = 200" );

A native window is a better choice when additional control over the new window is required. Native windows expose virtually the entire functionality of the operating system such as minimize/maximize, always in front, full screen and even removal of system chrome altogether. The drawback to using native windows is that there is substantially more work because all events must be monitored and managed explicitly.

The window.opener property that is commonly used in JavaScript to refer from a new window to the parent (creating) window can also be used.

	<html>
	<head>

	<title>Basic Window</title>
	<script type="text/javascript" src="AIRAliases.js">
	</script>

	<script>
	function doLoad( )
	{
	    document.getElementById( "btnLogin" ).
	addEventListener( "click", doLogin );
	}

	function doLogin( )
	{
	    var login = window.open( "Login.html", null,
	                             "width = 270, height = 150" );
	}
	</script>

	</head>
	<body onload="doLoad( )">

	<input id="btnLogin" type="button" value="Login" />

	</body>
	</html>

	Login.html
	<html>
	<head>

	<title>Login</title>

	</head>
	<body>

	<table>
	    <tr>
	        <td>Email:</td>
	        <td><input name="email" /></td>
	    </tr>
	    <tr>
	        <td>Password:</td>
	        <td><input name="password" /></td>
	    </tr>
	    <tr>
	        <td colspan="2" align="right">
	            <input type="button" value="Sign In" />
	        </td>
	    </tr>
	</table>

	</body>
	</html>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

File API

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Problem

A user has made changes to textual content in the application, which the user wants to save to disk for offline access.Writing Text to a

Solution

Writing text can be accomplished through the File and FileStream classes that are part of AIR.

Discussion

Before any reading or writing takes place to disk, a reference to a file or directory must first exist in the application. A file reference can be established in a number of ways, including programmatic manipulation and user selection. Both of these are accomplished by using the File class. The File class also contains static properties that point to common locations on the operating system. These locations include the desktop directory, user directory and documents directory:

	var file =
	air.File.applicationStorageDirectory.resolve( "myFile.txt" );

The call to File.resolve() creates a reference to a file named myFile.txt located in the application storage directory. Once a reference has been established, it can be used in file IO operations. Note that this doesn't actually create the file at this point.

Physically reading and writing to disk is available using the FileStream class. The FileStream class does not take any arguments in its constructor:

	var stream = ne