Parts of this page show the use of the XPInstall API. The majority of this API is now deprecated and as of Gecko 1.9 no longer available. Extension, Theme, and plug-in developers must switch away from install.js based packages to the new packaging scheme with an install.rdf manifest. In particular plugin developers should see how to package a plugin as an extension.

« PreviousNext »

This section will describe packaging a XUL application into an installer.

XPInstall Packages

Mozilla provides a mechanism which can be used to package XUL windows, scripts, skins and other files into single file installers. You can place this installer file somewhere for users to download. A simple script can be used to have the package downloaded and installed. This mechanism is called XPInstall (Cross platform Install).

XPInstall installers are packaged into JAR files. Inside the JAR file, you can add all the various files that you want to have installed. In addition, installers should contain an install script (a file named install.js) which can be used to script the installation process. This script has access to various install functions which can be used to install files and components.

The JAR file installers typically have the extension .xpi (pronounced zippy) to distinguish them from other archives. The installers will be usually used to install Mozilla components such as new skins, plugins and packages.

There are several steps involved in launching an installer and installing components. These are described step by step below.

  1. Create a Web page from which the user can download the software to be installed. This page will contain an install trigger which is a small piece of script which launches the install.
  2. The user is presented with a dialog which indicates the package being installed. It is possible for the install trigger to launch multiple installers. In this case, they will be presented in a list. The user may choose to continue or cancel.
  3. If the user chooses to continue, the installer XPI file is downloaded. A progress bar is displayed to the user during this process.
  4. The file install.js is extracted from the install archive and executed. This script will call install functions which will indicate which files from the archive should be installed.
  5. Once the script is complete, the new package has been installed. If multiple packages are being installed, their scripts will run in sequence.

Install Triggers

As indicated above, the install process is started by an install trigger. This involves the use of the special global object InstallTrigger. It contains a number of methods which can be used to start an installation. You can use this object in local or remote content, meaning that it is suitable for a download from a Web site.

Let's create an example install trigger. This involves the use of the function InstallTrigger.install(). This function takes two arguments, the first is a list of packages to install, and the second is a callback function which will be called when the installation is complete. Here is an example:

function doneFn ( name , result ){
  alert("The package " + name + " was installed with a result of " + result);
}

var xpi = new Object();
xpi["Calendar"] = "calendar.xpi";
InstallTrigger.install(xpi,doneFn);

First, we define a callback function doneFn() which will be called when the install is complete. You can name the function whatever you like of course. This function has two arguments. The first is the name of the package that was just installed. This is important if you are installing multiple components. The second argument is a result code. If the result is 0, the installation completed successfully. If the result is non-zero, an error occured and the value is an error code. The function doneFn() here just displays an alert box to the user.

Next, we create an array xpi which will hold the name (Calendar) and URL (calendar.xpi) of the installer. You can add an additional similar such line for each package you wish to have installed. Finally, we call the install function.

When this section of script is executed, the file calendar.xpi will be installed.

Our find files example

Let's try this with the find files dialog.

function doneFn ( name , result ){
  if (result) alert("An error occured: " + result);
}

var xpi = new Object();
xpi["Find Files"] = "findfile.xpi";
InstallTrigger.install(xpi,doneFn);

The XPI Archive

Note: If you want to create a new XULRunner application, extension, or theme, see Bundles.

The installer XPI file is required to contain one file called install.js which is a JavaScript file which is executed during the installation. The remaining files are the files to be installed. These files will typically be placed inside a directory in the archive but they do not have to be. For chrome files, they might be structured like the chrome directory.

Often, the only files placed in an XPI archive will be the install script (install.js) and a JAR file. This JAR file contains all of the files used by your application. The components provided with Mozilla are stored in this manner.

Because the XPI file is just a special ZIP file, you can create it and add files to it using a zip utility.

Our find files example

For the find files dialog, we'll create a structure in the archive much like the following:

install.js
findfile
  content
    contents.rdf
    findfile.xul
    findfile.js
  skin
    contents.rdf
    findfile.css
  locale
    contents.rdf
    findfile.dtd

A directory has been added for each part of the package, the content, the skin and the locale. The contents.rdf files have also been added because they will be needed to register the chrome files.

Next, we'll look further at the install script.

« PreviousNext »