Prism/Scripting

Important: The information on this page is out of date. Please refer to the Prism documentation [1] on the Mozilla Developer Center.

Prism allows for some client-side web application customization. The web application bundle is allowed to hold a JavaScript file named webapp.js (called the webapp script). This file will be loaded into the Prism chrome window very much like a Firefox extension is loaded into the browser chrome window.

Prism exposes a simple HostUI object to the webapp script. The HostUI object exposes some utility functions that may be useful to the webapp script. The interface is shown below:

/**
 * Simple host API exposed to the web application script files.
 */
var HostUI = {
  // log a message to the error console
  void log(aMsg);

  // get a reference to the main content web browser
  browser getBrowser();

  // show a popup alert message
  void showAlert(aImage, aTitle, aMsg);

  // access the Sidebar object
  object sidebar;
};

var Sidebar = {
  // collapse or expand the sidebar
  boolean visible;

  // sets the web content of the sidebar
  void add(aTitle, aURI);
};

HostUI methods

The methods exposed by the HostUI object allow interaction with the Prism runtime environment.

void log(aMsg);

Logs a message to the Prism error console.

browser getBrowser();

Returns a reference to the XUL Browser object which displays the Prism documents

showAlert(aImage, aTitle, aMsg);

showAlert provides a thin wrapper around the nsIAlertsService.showAlertNotification XPCOM method.

aImage

A URL to the image which should be displayed in the notification

aTitle

The string to be used as the title for the alert

aMsg

The text of the message to be displayed in the alert

There are also hooks that are called when Prism has loaded and when it is about to exit. You can declare these functions in the webapp script:

function startup() {
  // called during startup
}

function shutdown() {
  // called during shutdown
}

Currently, the webapp script also has access to full XPCOM functionality, just like a Firefox extension. This level of functionality is commonly called chrome-level privileges. It means that the script has a higher level of privilege than scripts in the web content and has access to the file system, clipboard and other parts of the native OS.

In the future, the webapp script may have lower privileges. We are looking into the security aspects of the higher privilege level.

Accessing HostUI methods

This object can be accessed via 'host' alias from webapp.js:

function startup() {
  host.log("hello");
}