Adobe AIR for JavaScript Developers Pocket Guide

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

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

During its development cycle, Adobe AIR was referred to in public by its code name of “Apollo”.

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 with Ajax-type functionality in the browser, it became possible for developers to begin to break away from page-based application flows. Developers began to offer richer application experiences via the browser. In a whitepaper from March 2002, Macromedia coined the term rich Internet application 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!

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

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 with Ajax-type functionality in the browser, it became possible for developers to begin to break away from page-based application flows. Developers began to offer richer application experiences via the browser. In a whitepaper from March 2002, Macromedia coined the term rich Internet application 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.

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:

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

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 shifted significantly 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 a number of solutions 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 types 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.

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

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?

Adobe AIR is a cross-operating-system runtime 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 RIAs 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 to enable 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, Adobe 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!

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

Three primary technologies are included within Adobe AIR, and they 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 Adobe AIR applications.

HTML/JavaScript

The first core application technology within Adobe AIR is HTML and JavaScript. This includes 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 is 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 for a more in-depth discussion of WebKit within Adobe AIR.

Adobe Flash

The second core application technology that Adobe AIR is built on is Adobe Flash Player. Specifically, Adobe AIR is built on top of Adobe Flash Player 9, which includes the ECMAScript-based ActionScript 3 scripting language, 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 on the Mozilla website, 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:

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

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

This chapter discusses how to start developing applications for Adobe AIR 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
Signing, packaging, and deploying AIR applications

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

You need a number of items to begin developing AIR applications.

The Adobe AIR runtime is required to test application icons and deploy AIR applications. You can download the runtime for free from http://www.adobe.com/go/getair.

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

You can download the AIR SDK for free from http://www.adobe.com/go/getairsdk.

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 Studio.

You can find more information on Adobe Dreamweaver at http://www.adobe.com/go/dreamweaver, Panic’s Coda at http://www.panic.com/coda/, and Aptana Studio at http://www.aptana.com.

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

The supported operating systems are:

Microsoft Windows 2000 SP4
Microsoft Windows XP SP2

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

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

You need a number of items to begin developing AIR applications.

The Adobe AIR runtime is required to test application icons and deploy AIR applications. You can download the runtime for free from http://www.adobe.com/go/getair.

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

You can download the AIR SDK for free from http://www.adobe.com/go/getairsdk.

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 Studio.

You can find more information on Adobe Dreamweaver at http://www.adobe.com/go/dreamweaver, Panic’s Coda at http://www.panic.com/coda/, and Aptana Studio at http://www.aptana.com.

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

The supported operating systems are:

Microsoft Windows 2000 SP4
Microsoft Windows XP SP2
Windows Vista Home Premium, Business, Ultimate, or Enterprise
Mac OS 10.4.910 and later (Intel and PowerPC)

H.264 video playback on a Mac requires an Intel processor.

Adobe is also currently working on adding support for Linux.

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

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

If you have installed prerelease (alpha and/or beta) versions of Adobe AIR, you may need to uninstall them before installing the 1.0 runtime. However, whether this is strictly required can be a little tricky to determine.

lists the prerelease versions of Adobe AIR and whether they should be uninstalled before installing Adobe AIR 1.0.

Table : Prerelease versions of Adobe AIR
Version	Uninstall?
Alpha	Uninstall
Beta 1	Will be uninstalled automatically by the Adobe AIR 1.0 installer
Beta 2	No need to uninstall
Beta 3	No need to uninstall

As shows, the beta 2 and beta 3 runtimes can run side by side with Adobe AIR 1.0. This allows you to run applications built for beta 2 and beta 3 until those betas expire.

If you do not know whether you have installed the alpha version, it is a good idea to go ahead and uninstall all prerelease versions of Adobe AIR.

To uninstall all prerelease versions of Adobe AIR on Windows, follow these steps:

In the Windows Start menu, select Settings→Control Panel.
Select the Add or Remove Programs control panel.
Select the prerelease version of Adobe AIR to uninstall (depending on the version, it may be referred to by its code name of “Apollo”).
Click the Change/Remove button.

Follow these steps to uninstall all prerelease versions of Adobe AIR on the Mac. Depending on the prerelease version(s) of Adobe AIR that you have installed, all steps may not apply.

Run the Adobe AIR Uninstaller in the /Users/<User>/Applications directory (where <User> is your system user account name).
Run the Adobe AIR Uninstaller in the /Applications directory.
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 1.0 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!

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

Although it is not necessary to have Adobe AIR installed on your computer to develop and test Adobe AIR applications, it is useful to have it 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 AIR Installer.

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

It is also possible to install Adobe AIR directly from the runtime via express install. We will cover this in .

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_samples.

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

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

The process for uninstalling Adobe AIR is different depending on your operating system.

On Windows, you can uninstall Adobe AIR the same way that you uninstall any other application. Just select Adobe AIR in the Add/Remove Programs section of the Control Panel.

The Adobe AIR installer places an uninstall application on the user’s system when it is installed. To uninstall Adobe AIR, launch the uninstaller named Adobe AIR Uninstaller which you can find in the /Applications/Utilities 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!

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

The Adobe AIR SDK beta contains tools, samples, and code that make it easier to develop, test, and deploy applications. In particular, it contains two command-line tools that we will use:

ADL: You use this tool to launch and test an Adobe AIR application without having to install it first.
ADT: You use this tool to package and sign an AIR application for distribution.

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 Adobe AIR SDK from http://www.adobe.com/go/getairsdk.
Open the SDK:
a) On Windows, uncompress the ZIP archive.
b) On Mac, mount the .dmg file.
Copy the contents of the SDK to your system (we will refer to this location as <SDK_Path>).
To run the command-line tools, you need to copy only the bin, lib, and runtime directories from the SDK.
It’s important that the bin, lib, and runtime directories within the SDK maintain their relative paths to each other.
At this point, you should have at least the following three directories: <SDK_Path>/bin, <SDK_Path>/lib, and <SDK_Path>/runtime. The ADL and ADT command-line tools are located in the bin directory.

All that is left to do 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.

If you are on a Windows system, follow these steps:

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:

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

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

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

We will build a very simple “Hello World” example. Once we have built and tested the application, our development environment will be set up and ready to build more complex and functional AIR applications.

Every Adobe 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, and it 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 this folder, create two new files called AIRHelloWorld.html and AIRHelloWorld.xml.
Open each file 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 the 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 regarding 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">

    <id>com.oreilly.AIRHelloWorld</id>
    <filename>AIRHelloWorld</filename>
    <name>AIR Hello World</name>
    <description>A simple AIR hello world application</
    description> <version>1.0</version>

    <initialWindow>
         <content>AIRHelloWorld.html</content>
         <title>AIR Hello World</title>
         <systemChrome>standard</systemChrome>
         <transparent>false</transparent>
         <visible>true</visible>
         <minimizable>true</minimizable>
         <maximizable>true</maximizable>
         <resizable>true</resizable>
    </initialWindow>
</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!

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

Although a number of HTML IDEs (such as Adobe Dreamweaver) have 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 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

Although we could package up the entire application and then install it, this would be tedious, and it would 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 install it first.

To test the application:

Open a Terminal window (on the 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 (see ).

Figure : AIRHelloWorld application running from ADL on Mac OS X

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

Make sure you have configured the SDK correctly so that the ADL tool can be found.
Make sure you are running the ADL command from the same directory that contains the AIRHelloWorld.xml file.
Make sure 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!

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 that 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 Adobe AIR uses it 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.

Installing an AIR file requires that Adobe AIR already be installed on the user’s system.

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.

In addition, you will also need a certificate to digitally sign your application.

Adobe AIR requires that all AIR applications be digitally signed. There are two ways to do this.

Signing with a self-signed certificate

Developers can use ADT to digitally sign an AIR file with a self-signed certificate. You self-sign an AIR file by generating a self-signed certificate, and then signing the AIR file with it. Self-signing AIR files provides little security, and no way to verify that the author is who she says she is. When the application is installed, Adobe AIR will warn users that the publisher of the application cannot be verified.

You cannot switch among certificate types when updating applications.

AIR files signed with self-signed certificates are meant primarily for development purposes. If you plan to widely distribute your application to the public, you should sign your application with a certificate issued by a respected and well-known Certification authority (CA).

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

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

This chapter provides an overview of the HTML and JavaScript environments within Adobe AIR. It discusses:

The use of the open source WebKit HTML-rendering engine within Adobe AIR
JavaScript functionality within Adobe AIR
Security Model
Working with Adobe AIR, Flash Player and ActionScript APIs from JavaScript
Troubleshooting AIR Applications written with HTML and 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 (but not limited to):

JavaScript
XMLHttpRequest
CSS
XHTML
W3C DOM Level 2 support

Essentially, Adobe AIR has a full HTML rendering engine, and includes support for all 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 community.

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

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 (but not limited to):

JavaScript
XMLHttpRequest
CSS
XHTML
W3C DOM Level 2 support

Essentially, Adobe AIR has a full HTML rendering engine, and includes support for all 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 community.

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.

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

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!

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 3 browser as an indicator of the functionality available within the HTML environment within AIR.

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

Working with Universal Resource Identifiers (URIs) within HTML content in AIR applications is largely the same as working with URIs within the browser. This section gives a quick overview of working with URIs within HTML content in AIR applications, and introduces some new URIs made available by the runtime.

Supported URI schemes

Adobe AIR provides support for the most common URI schemes available within the browser

Table : Supported URI schemes
Scheme	Description	Example
http://	URI that points to a resource accessed via the standard HTTP protocol.	http://www.adobe.com
https://	URI that points to a resource accessed via a protocol encrypted with SSL/TLS.	https://secure.example.com
file://	URI that points to a resource on the local or a networked file system.	file:///c:/Test/test.txt
mailto:	URI that opens the default email application.	mailto:john.doe@example.com

Unsupported URI schemes

The feed:// and data:// URI schemes are not supported by Adobe AIR 1.0, and there is only partial support for the ftp:// scheme.

Finally, the javascript: URI scheme is not supported within applications running within the Adobe AIR application sandbox. Please check the Security model section later is this chapter for more details.

AIR URI Schemes

Adobe AIR also provides a number of additional URIs that makes it easy to reference files and content within specific areas of the users system.

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

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

This section discusses a number of differences in the security model implementations when running content within Adobe AIR, versus running it in the browser.

Adobe AIR enables Ajax and Flash/Flex developers to use their existing skills to build and deploy desktop applications. Although these applications are built using web technologies, the key thing to keep in mind is that the end result is targeted for running on desktop, and thus the security model for AIR is much closer to that of a desktop application than of a web application.

A desktop application has high privileges compared to a web application as it is installed by the user on a specific machine, implying a degree of trust that is greater than that of arbitrary web content. Unfortunately there are design and implementation patterns common to web applications that can be dangerous when combined with the local system access or other AIR APIs available.

The runtime provides a comprehensive security architecture that defines permissions according to each file in an AIR application. Permissions are granted to files according to their origin, and are assigned into logical security groupings called sandboxes.

Application sandbox

The application sandbox provides access to all Adobe AIR APIs, including those that provide access to the user’s system.

When an application is installed, all files included within an AIR installer file are copied onto the user’s computer into an application directory. Developers can reference this directory in code through the app:/ URI scheme. All files within the application directory tree are assigned to the application sandbox when the application is run.

When running within the application sandbox, some potentially dangerous patterns that are allowed in the browser, are restricted. The things that are disabled revolve around the importing of remote JavaScript content and the dynamic execution/evaluation of JavaScript strings.

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

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

Because of the differences of the security models between content running within the browser, and content running within Adobe AIR, most JavaScript frameworks must explicitly add support for Adobe AIR in order for them to running correctly within an Adobe AIR application.

At the time that the book was authored, all major JavaScript frameworks have added (or are adding) support for Adobe AIR.

Dojo Toolkit 1.1.0 Beta
Ext JS 2.0.2 with Adobe AIR Adapter
jQuery 1.2.3
YUI 2.5.1
MooTools 1.11
FCKeditor 2.6.0 Beta
MochiKit 1.3.1
Spry Prerelease 1.6.1

For a complete and up to date list of frameworks that support Adobe AIR please check the AIR product page http://www.adobe.com/products/air/ or the AIR Developer Center for Ajax: http://www.adobe.com/devnet/air/ajax/.

In addition to the standard JavaScript and HTML DOM APIs, JavaScript code running within the application sandbox 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
Reading and writing to and from an encrypted local store
Access to a relational local database
Creating, controlling and manipulating native windows
Creating and working with native menus
Making direct socket connections (both binary and text based)
Network detection
Accessing the clipboard
Dragging data between AIR applications and OS or another application
File extension registration and running at startup
Support for dock and tray icons

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

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.

The following diagram shows the relationship between the two environments.

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

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

The process of developing an AIR application is much the same as that of developing an HTML-based web application.

The same thing is true when it comes to debugging an AIR application. One difference is that the JavaScript error messages go to the console (when running the application with AIR Debug Launcher) and not in a separate window as you might be used to in the browser world.

This section covers some of the new messages you might come across that are introduced by the runtime and also gives you a quick overview of an AIR SDK tool that can be used to make your life easier when working with HTML/JavaScript.

Security violation for Javascript code

If you call code that is restricted from use in the application sandbox due to security restrictions, the runtime dispatches a JavaScript error: "

Adobe AIR runtime security violation
        for JavaScript code in the application security
        sandbox

.”

Referencing a JavaScript object no longer available

When an object dispatches an event to a handler that has already been unloaded, you see the following error message: "

The application attempted to reference a JavaScript
        object in an HTML page that is no longer loaded

.”

To avoid this error, remove JavaScript event listeners in an HTML page before it goes away. In the case of page navigation (within an HTMLLoader object), remove the event listener during the unload event of the window object.

// In this example the event listener for an uncaughtScript
Exception event is removed when unload event fires
window.onunload = cleanup;
window.htmlLoader.addEventListener('uncaughtScriptException',
uncaughtScriptException);
function cleanup()
{
    window.htmlLoader.removeEventListener('uncaught
ScriptException',
 uncaughtScriptExceptionHandler);
}

Missing event listeners for error events

Exceptions, rather than events, are the primary mechanism for error handling in the runtime classes. However, because exceptions don’t work for asynchronous operations, the runtime dispatches an error event object.

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

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

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

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

Problem

You have finished your application, have signed and packaged it, and want to distribute it via a web page.

Solution

Adobe AIR applications can be easily distributed from a web page using the badge installer included with the SDK.

Discussion

Adobe AIR application files are largely self-contained entities, and are ready for distribution once they are signed and packaged. The resultant file will have an .air extension. That application file can be distributed via email, CD-ROM, or other traditional forms; however, installing an .air file requires that Adobe AIR is already present on the target machine. Alternatively, a web-page-based “badge installer” can streamline installation by detecting the runtime and installing it if necessary before installing your application.

Though you can customize it in a number of different ways, a sample badge installer is included with the Adobe AIR SDK. The badge takes the form of a small 217×180 area, which is ideal for a blog sidebar or other constrained spaces. The default badge installer runs as a Flash 9.0.115 (Flash Update 3) component in the browser. The Flash source file (FLA) is also included with the SDK for additional customization.

You can find the files for the sample badge installer in the samples/badge directory of the SDK.

Deploying with the badge installer requires four files: badge.swf, default_badge.html, AC_RunActiveContent.js, and your AIR application.

Even though the badge installer does appear as Flash content on a web page, you do not need to have any Flash knowledge or software such as Adobe Flash CS3. The badge installer was prebuilt with a number of configurable options that you can set from within the containing HTML page. On line 59 of 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!

Content preview·

Table of Contents

HTML/JavaScript

Adobe Flash

Understanding application descriptor files

Signing with a self-signed certificate

Open project

Open project

Proven technology that web developers know

Supported URI schemes

Unsupported URI schemes

AIR URI Schemes

Application sandbox

Security violation for Javascript code

Referencing a JavaScript object no longer available

Missing event listeners for error events

Problem

Solution

Discussion