JavaScript in AIR

AIR makes several changes to the typical behavior of common JavaScript objects. Many of these changes are made to make it easier to write secure applications in AIR. At the same time, these differences in behavior mean that some common JavaScript coding patterns, and existing web applications using those patterns, might not always execute as expected in AIR. For information on correcting these types of issues, see Avoiding security-related JavaScript errors.

HTML Sandboxes

AIR places content into isolated sandboxes according to the origin of the content. The sandbox rules are consistent with the same-origin policy implemented by most web browsers, as well as the rules for sandboxes implemented by the Adobe Flash Player. In addition, AIR provides a new application sandbox type to contain and protect application content. See Security sandboxes for more information on the types of sandboxes you may encounter when developing AIR applications.

Access to the run-time environment and AIR APIs are only available to HTML and JavaScript running within the application sandbox. At the same time, however, dynamic evaluation and execution of JavaScript, in its various forms, is largely restricted within the application sandbox for security reasons. These restrictions are in place whether or not your application actually loads information directly from a server. (Even file content, pasted strings, and direct user input may be untrustworthy.)

The origin of the content in a page determines the sandbox to which it is consigned. Only content loaded from the application directory (the installation directory referenced by the app: URL scheme) is placed in the application sandbox. Content loaded from the file system is placed in the local-with-file system or the local-trusted sandbox, which allows access and interaction with content on the local file system, but not remote content. Content loaded from the network is placed in a remote sandbox corresponding to its domain of origin.

To allow an application page to interact freely with content in a remote sandbox, the page can be mapped to the same domain as the remote content. For example, if you write an application that displays map data from an Internet service, the page of your application that loads and displays content from the service could be mapped to the service domain. The attributes for mapping pages into a remote sandbox and domain are new attributes added to the frame and iframe HTML elements.

To allow content in a non-application sandbox to safely use AIR features, you can set up a parent sandbox bridge. To allow application content to safely call methods and access properties of content in other sandboxes, you can set up a child sandbox bridge. Safety here means that remote content cannot accidentally get references to objects, properties, or methods that are not explicitly exposed. Only simple data types, functions, and anonymous objects can be passed across the bridge. However, you must still avoid explicitly exposing potentially dangerous functions. If, for example, you exposed an interface that allowed remote content to read and write files anywhere on a user's system, then you might be giving remote content the means to do considerable harm to your users.

JavaScript eval() function

Use of the eval() function is restricted within the application sandbox once a page has finished loading. Some uses are permitted so that JSON-formatted data can be safely parsed, but any evaluation that results in executable statements results in an error. Code restrictions for content in different sandboxes describes the allowed uses of the eval() function.

Function constructors

In the application sandbox, function constructors can be used before a page has finished loading. After all page load event handlers have finished, new functions cannot be created.

Loading external scripts

HTML pages in the application sandbox cannot use the script tag to load JavaScript files from outside of the application directory. For a page in your application to load a script from outside the application directory, the page must be mapped to a non-application sandbox.

The XMLHttpRequest object

AIR provides an XMLHttpRequest (XHR) object that applications can use to make data requests. The following example illustrates a simple data request:

xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "http:/www.example.com/file.data", true);
xmlhttp.onreadystatechange = function() {
    if (xmlhttp.readyState == 4) {
        //do something with data...
    }
}
xmlhttp.send(null);

In contrast to a browser, AIR allows content running in the application sandbox to request data from any domain. The result of an XHR that contains a JSON string can be evaluated into data objects unless the result also contains executable code. If executable statements are present in the XHR result, an error is thrown and the evaluation attempt fails.

To prevent accidental injection of code from remote sources, synchronous XHRs return an empty result if made before a page has finished loading. Asynchronous XHRs will always return after a page has loaded.

By default, AIR blocks cross-domain XMLHttpRequests in non-application sandboxes. A parent window in the application sandbox can choose to allow cross-domain requests in a child frame containing content in a non-application sandbox by setting allowCrossDomainXHR, an attribute added by AIR, to true in the containing frame or iframe element:

<iframe id="mashup"
    src="http://www.example.com/map.html"
    allowCrossDomainXHR="true">
</iframe>

Note: When convenient, the AIR URLStream class can also be used to download data.

If you dispatch an XMLHttpRequest to a remote server from a frame or iframe containing application content that has been mapped to a remote sandbox, make sure that the mapping URL does not mask the server address used in the XHR. For example, consider the following iframe definition, which maps application content into a remote sandbox for the example.com domain:

<iframe id="mashup"
    src="http://www.example.com/map.html"
    documentRoot="app:/sandbox/"
    sandboxRoot="http://www.example.com/"
    allowCrossDomainXHR="true">
</iframe>

Because the sandboxRoot attribute remaps the root URL of the www.example.com address, all requests are loaded from the application directory and not the remote server. Requests are remapped whether they derive from page navigation or from an XMLHttpRequest.

To avoid accidentally blocking data requests to your remote server, map the sandboxRoot to a subdirectory of the remote URL rather than the root. The directory does not have to exist. For example, to allow requests to the www.example.com to load from the remote server rather than the application directory, change the previous iframe to the following:

<iframe id="mashup"
    src="http://www.example.com/map.html"
    documentRoot="app:/sandbox/"
    sandboxRoot="http://www.example.com/air/"
    allowCrossDomainXHR="true">
</iframe>

In this case, only content in the air subdirectory is loaded locally.

For more information on sandbox mapping see HTML frame and iframe elements and HTML security in Adobe AIR.

Cookies

In AIR applications, only content in remote sandboxes (content loaded from http: and https: sources) can use cookies (the document.cookie property). In the application sandbox, other means for storing persistent data are available, including the EncryptedLocalStore, SharedObject, and FileStream classes.

The Clipboard object

The WebKit Clipboard API is driven with the following events: copy, cut, and paste. The event object passed in these events provides access to the clipboard through the clipboardData property. Use the following methods of the clipboardData object to read or write clipboard data:

Method	Description
clearData(mimeType)	Clears the clipboard data. Set the mimeType parameter to the MIME type of the data to clear.
getData(mimeType)	Get the clipboard data. This method can only be called in a handler for the paste event. Set the mimeType parameter to the MIME type of the data to return.
setData(mimeType, data)	Copy data to the clipboard. Set the mimeType parameter to the MIME type of the data.

JavaScript code outside the application sandbox can only access the clipboard through theses events. However, content in the application sandbox can access the system clipboard directly using the AIR Clipboard class. For example, you could use the following statement to get text format data on the clipboard:

var clipping = air.Clipboard.generalClipboard.getData("text/plain",
                            air.ClipboardTransferMode.ORIGINAL_ONLY);

The valid data MIME types are:

MIME type	Value
Text	"text/plain"
HTML	"text/html"
URL	"text/uri-list"
Bitmap	"image/x-vnd.adobe.air.bitmap"
File list	"application/x-vnd.adobe.air.file-list"

Important: Only content in the application sandbox can access file data present on the clipboard. If non-application content attempts to access a file object from the clipboard, a security error is thrown.

For more information on using the clipboard, see Copy and paste and Using the Pasteboard from JavaScript (Apple Developer Center).

Drag and Drop

Drag-and-drop gestures into and out of HTML produce the following DOM events: dragstart, drag, dragend, dragenter, dragover, dragleave, and drop. The event object passed in these events provides access to the dragged data through the dataTransfer property. The dataTransfer property references an object that provides the same methods as the clipboardData object associated with a clipboard event. For example, you could use the following function to get text format data from a drop event:

function onDrop(dragEvent){
    return dragEvent.dataTransfer.getData("text/plain",
            air.ClipboardTransferMode.ORIGINAL_ONLY);
}

The dataTransfer object has the following important members:

Member	Description
clearData(mimeType)	Clears the data. Set the mimeType parameter to the MIME type of the data representation to clear.
getData(mimeType)	Get the dragged data. This method can only be called in a handler for the drop event. Set the mimeType parameter to the MIME type of the data to get.
setData(mimeType, data)	Set the data to be dragged. Set the mimeType parameter to the MIME type of the data.
types	An array of strings containing the MIME types of all data representations currently available in the dataTransfer object.
effectsAllowed	Specifies whether the data being dragged can be copied, moved, linked, or some combination thereof. Set the effectsAllowed property in the handler for the dragstart event.
dropEffect	Specifies which of the allowed drop effects are supported by a drag target. Set the dropEffect property in the handler for the dragEnter event. During the drag, the cursor changes to indicate which effect would occur if the user released the mouse. If no dropEffect is specified, an effectsAllowed property effect is chosen. The copy effect has priority over the move effect, which itself has priority over the link effect. The user can modify the default priority using the keyboard.

For more information on adding support for drag-and-drop to an AIR application see Drag and drop in AIR and Using the Drag-and-Drop from JavaScript (Apple Developer Center).

innerHTML and outerHTML properties

AIR places security restrictions on the use of the innerHTML and outerHTML properties for content running in the application sandbox. Before the page load event, as well as during the execution of any load event handlers, use of the innerHTML and outerHTML properties is unrestricted. However, once the page has loaded, you can only use innerHTML or outerHTML properties to add static content to the document. Any statement in the string assigned to innerHTML or outerHTML that evaluates to executable code is ignored. For example, if you include an event callback attribute in an element definition, the event listener is not added. Likewise, embedded <script> tags are not evaluated. For more information, see the HTML security in Adobe AIR.

Document.write() and Document.writeln() methods

Use of the write() and writeln() methods is not restricted in the application sandbox before the load event of the page. However, once the page has loaded, calling either of these methods does not clear the page or create a new one. In a non-application sandbox, as in most web browsers, calling document.write() or writeln() after a page has finished loading clears the current page and opens a new, blank one.

Document.designMode property

Set the document.designMode property to a value of on to make all elements in the document editable. Built-in editor support includes text editing, copy, paste, and drag-and-drop. Setting designMode to on is equivalent to setting the contentEditable property of the body element to true. You can use the contentEditable property on most HTML elements to define which sections of a document are editable. See HTML contentEditable attribute for additional information.

unload events (for body and frameset objects)

In the top-level frameset or body tag of a window (including the main window of the application), do not use the unload event to respond to the window (or application) being closed. Instead, use exiting event of the NativeApplication object (to detect when an application is closing). Or use the closing event of the NativeWindow object (to detect when a window is closing). For example, the following JavaScript code displays a message ( "Goodbye.") when the user closes the application:

var app = air.NativeApplication.nativeApplication;
app.addEventListener(air.Event.EXITING, closeHandler);
function closeHandler(event)
{
    alert("Goodbye.");
}

However, scripts can successfully respond to the unload event caused by navigation of a frame, iframe, or top-level window content.

Note: These limitations may be removed in a future version of Adobe AIR.

JavaScript Window object

The Window object remains the global object in the JavaScript execution context. In the application sandbox, AIR adds new properties to the JavaScript Window object to provide access to the built-in classes of AIR, as well as important host objects. In addition, some methods and properties behave differently depending on whether they are within the application sandbox or not.

Window.runtime property
The runtime property allows you to instantiate and use the built-in runtime classes from within the application sandbox. These classes include the AIR and Flash Player APIs (but not, for example, the Flex framework). For example, the following statement creates an AIR file object:

var preferencesFile = new window.runtime.flash.filesystem.File();

The AIRAliases.js file, provided in the AIR SDK, contains alias definitions that allow you to shorten such references. For example, when AIRAliases.js is imported into a page, a File object can be created with the following statement:

var preferencesFile = new air.File();

The window.runtime property is only defined for content within the application sandbox and only for the parent document of a page with frames or iframes.

See Using the AIRAliases.js file.

Window.nativeWindow property
The nativeWindow property provides a reference to the underlying native window object. With this property, you can script window functions and properties such as screen position, size, and visibility, and handle window events such as closing, resizing, and moving. For example, the following statement closes the window:

window.nativeWindow.close();

Note: The window control features provided by the NativeWindow object overlap the features provided by the JavaScript Window object. In such cases, you can use whichever method you find most convenient.

The window.nativeWindow property is only defined for content within the application sandbox and only for the parent document of a page with frames or iframes.

Window.htmlLoader property
The htmlLoader property provides a reference to the AIR HTMLLoader object that contains the HTML content. With this property, you can script the appearance and behavior of the HTML environment. For example, you can use the htmlLoader.paintsDefaultBackground property to determine whether the control paints a default, white background:

window.htmlLoader.paintsDefaultBackground = false;

Note: The HTMLLoader object itself has a window property, which references the JavaScript Window object of the HTML content it contains. You can use this property to access the JavaScript environment through a reference to the containing HTMLLoader.

The window.htmlLoader property is only defined for content within the application sandbox and only for the parent document of a page with frames or iframes.

Window.parentSandboxBridge and Window.childSandboxBridge properties
The parentSandboxBridge and childSandboxBridge properties allow you to define an interface between a parent and a child frame. For more information, see Cross-scripting content in different security sandboxes.

Window.setTimeout() and Window.setInterval() functions
AIR places security restrictions on use of the setTimeout() and setInterval() functions within the application sandbox. You cannot define the code to be executed as a string when calling setTimeout() or setInterval(). You must use a function reference. For more information, see setTimeout() and setInterval().

Window.open() function
When called by code running in a non-application sandbox, the open() method only opens a window when called as a result of user interaction (such as a mouse click or keypress). In addition, the window title is prefixed with the application title (to prevent windows opened by remote content from impersonating windows opened by the application). For more information, see the Restrictions on calling the JavaScript window.open() method.

air.NativeApplication object

The NativeApplication object provides information about the application state, dispatches several important application-level events, and provides useful functions for controlling application behavior. A single instance of the NativeApplication object is created automatically and can be accessed through the class-defined NativeApplication.nativeApplication property.

To access the object from JavaScript code you could use:

var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;

Or, if the AIRAliases.js script has been imported, you could use the shorter form:

var app = air.NativeApplication.nativeApplication;

The NativeApplication object can only be accessed from within the application sandbox. For more information about the NativeApplication object, see Working with AIR runtime and operating system information.

The JavaScript URL scheme

Execution of code defined in a JavaScript URL scheme (as in href="javascript:alert('Test')") is blocked within the application sandbox. No error is thrown.