Debugging with the AIR HTML Introspector

The Adobe® AIR® SDK includes an AIRIntrospector.js JavaScript file that you can include in your application to help debug HTML-based applications.

About the AIR Introspector

The Adobe AIR HTML/JavaScript Application Introspector (called the AIR HTML Introspector) provides useful features to assist HTML-based application development and debugging:

It includes an introspector tool that allows you to point to a user interface element in the application and see its markup and DOM properties.
It includes a console for sending objects references for introspection, and you can adjust property values and execute JavaScript code. You can also serialize objects to the console, which limits you from editing the data. You can also copy and save text from the console.
It includes a tree view for DOM properties and functions.
It lets you edit the attributes and text nodes for DOM elements.
It lists links, CSS styles, images, and JavaScript files loaded in your application.
It lets you view to the initial HTML source and the current markup source for the user interface.
It lets you access files in the application directory. (This feature is only available for the AIR HTML Introspector console opened for application sandbox. Not available for the consoles open for non-application sandbox content.)
It includes a viewer for XMLHttpRequest objects and their properties, including responseText and responseXML properties (when available).
You can search for matching text in the source code and files.

Loading the AIR Introspector code

The AIR Introspector code is included in a JavaScript file, AIRIntrospector.js, that is included in the frameworks directory of the AIR SDK. To use the AIR Introspector in your application, copy the AIRIntrospector.js to your application project directory and load the file via a script tag in the main HTML file in your application:

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

Also include the file in every HTML file that corresponds to different native windows in your application.

Important: Include the AIRIntrospector.js file only when developing and debugging the application. Remove it in the packaged AIR application that you distribute.

The AIRIntrospector.js file defines a class, Console, which you can access from JavaScript code by calling air.Introspector.Console.

Note: Code using the AIR Introspector must be in the application security sandbox (in a file in the application directory).

Inspecting an object in the Console tab

The Console class defines five methods: log(), warn(), info(), error(), and dump().

The log(), warn(), info(), and error() methods all let you send an object to the Console tab. The most basic of these methods is the log() method. The following code sends a simple object, represented by the test variable, to the Console tab:

var test = "hello";
air.Introspector.Console.log(test);

However, it is more useful to send a complex object to the Console tab. For example, the following HTML page includes a button (btn1) that calls a function that sends the button object itself to the Console tab:

<html>
    <head>
        <title>Source Viewer Sample</title>
        <script type="text/javascript" src="scripts/AIRIntrospector.js"></script>
        <script type="text/javascript">
            function logBtn()
            {
                var button1 = document.getElementById("btn1");
                air.Introspector.Console.log(button1);
            }
        </script>
    </head>
    <body>
        <p>Click to view the button object in the Console.</p>
        <input type="button" id="btn1"
            onclick="logBtn()"
            value="Log" />
    </body>
</html>

When you click the button, the Console tab displays the btn1 object, and you can expand the tree view of the object to inspect its properties:

You can edit a property of the object by clicking the listing to the right of the property name and modifying the text listing.

The info(), error(), and warn() methods are like the log() method. However, when you call these methods, the Console displays an icon at the beginning of the line:

Method	Icon
`info()`
`error()`
`warn()`

The log(), warn(), info(), and error() methods send a reference only to an actual object, so the properties available are the ones at the moment of viewing. If you want to serialize the actual object, use the dump() method. The method has two parameters:

Parameter	Description
`dumpObject`	The object to be serialized.
`levels`	The maximum number of levels to be examined in the object tree (in addition to the root level). The default value is 1 (meaning that one level beyond the root level of the tree is shown). This parameter is optional.

Calling the dump() method serializes an object before sending it to the Console tab, so that you cannot edit the objects properties. For example, consider the following code:

var testObject = new Object();
testObject.foo = "foo";
testObject.bar = 234;
air.Introspector.Console.dump(testObject);

When you execute this code, the Console displays the testObject object and its properties, but you cannot edit the property values in the Console.

Configuring the AIR Introspector

You can configure the console by setting properties of the global AIRIntrospectorConfig variable. For example, the following JavaScript code configures the AIR Introspector to wrap columns at 100 characters:

var AIRIntrospectorConfig = new Object();
AIRIntrospectorConfig.wrapColumns = 100;

Be sure to set the properties of the AIRIntrospectorConfig variable before loading the AIRIntrospector.js file (via a script tag).

There are eight properties of the AIRIntrospectorConfig variable:

Property	Default value	Description
`closeIntrospectorOnExit`	`true`	Sets the Inspector window to close when all other windows of the application are closed.
`debuggerKey`	123 (the F12 key)	The key code for the keyboard shortcut to show and hide the AIR Introspector window.
`debugRuntimeObjects`	`true`	Sets the Introspector to expand runtime objects in addition to objects defined in JavaScript.
`flashTabLabels`	`true`	Sets the Console and XMLHttpRequest tabs to flash, indicating when a change occurs in them (for example, when text is logged in these tabs).
`introspectorKey`	122 (the F11 key)	The key code for the keyboard shortcut to open the Inspect panel.
`showTimestamp`	`true`	Sets the Console tab to display timestamps at the beginning of each line.
`showSender`	`true`	Sets the Console tab to display information on the object sending the message at the beginning of each line.
`wrapColumns`	2000	The number of columns at which source files are wrapped.

AIR Introspector interface

To open the AIR introspector window when debugging the application, press the F12 key or call one of the methods of the Console class (see Inspecting an object in the Console tab). You can configure the hot key to be a key other than the F12 key; see Configuring the AIR Introspector.

The AIR Introspector window has six tabs—Console, HTML, DOM, Assets, Source, and XHR—as shown in the following illustration:

The Console tab

The Console tab displays values of properties passed as parameters to one of the methods of the air.Introspector.Console class. For details, see Inspecting an object in the Console tab.

To clear the console, right-click the text and select Clear Console.
To save text in the Console tab to a file, right-click the Console tab and select Save Console To File.
To save text in the Console tab to the clipboard, right-click the Console tab and select Save Console To Clipboard. To copy only selected text to the clipboard, right-click the text and select Copy.
To save text in the Console class to a file, right-click the Console tab and select Save Console To File.
To search for matching text displayed in the tab, click CTRL+F on Windows or Command+F on Mac OS. (Tree nodes that are not visible are not searched.)

The HTML tab

The HTML tab lets you view the entire HTML DOM in a tree structure. Click an element to view its properties on the right side of the tab. Click the + and - icons to expand and collapse a node in the tree.

You can edit any attribute or text element in the HTML tab and the edited value is reflected in the application.

Click the Inspect button (to the left of the list of tabs in the AIR Introspector window). You can click any element on the HTML page of the main window and the associated DOM object is displayed in the HTML tab. When the main window has focus, you can also press the keyboard shortcut to toggle the Inspect button on and off. The keyboard shortcut is F11 by default. You can configure the keyboard shortcut to be a key other than the F11 key; see Configuring the AIR Introspector.

Click the Refresh Active Window button (at the top of the AIR Introspector window) to refresh the data displayed in the HTML tab.