Home > Element Reference : InstallTrigger

Contents

### InstallTrigger

Used to trigger an installation of a component. The component should be an XPI file containing the files to installed. The XPI file will be downloaded and the install.js script within the installer will be executed. This object is a global object and its methods can be called directly.

More information about InstallTrigger

#### Properties and Methods:

compareVersion ( String name , String version )
compareVersion ( String name , String version , major , minor , release , build )

Compares the version of a package being installed with the current version installed. You can either pass in a string as the version or a set of up to four integers, representing each part of the version.

If you don't supply all four integers, the missing values default to 0. The string version is a set of numbers separated by periods, as in 4.2.5 which is major version 4, minor version 2 and release 5.

The compareVersion function returns a value which determines what value is different. The following table describes possible return values:

Constant | Value | Description
EQUAL | 0 | The versions are the same.
BLD_DIFF | 1 | The current installation has a higher build version number.
BLD_DIFF_MINUS | -1 | The current installation has a lower build version number.
REL_DIFF | 2 | The current installation has a higher release version number.
REL_DIFF_MINUS | -2 | The current installation has a lower release version number.
MINOR_DIFF | 3 | The current installation has a higher minor version number.
MINOR_DIFF_MINUS | -3 | The current installation has a lower minor version number.
MAJOR_DIFF | 4 | The current installation has a higher major version number.
MAJOR_DIFF_MINUS | -4 | The current installation has a lower major version number.

enabled ( )

Returns true if installs are enabled. This corresponds to the value of the Mozilla preference 'xpinstall.enabled'.

getVersion ( component )

Returns the version of a component currently installed as a string. Returns null if the component is not installed.

install ( arr , notifyFunction )

Starts an installation. The first argument is an array of packages to be installed.

The notifyFunction is a callback function which you may define which is called when an installation is complete or when an error occurs. The callback function takes two arguments, the first will be the URL of the package that was installed and the second is an integer which will be zero if successful and non-zero if an error occured. The special value 999 indicates that the user must restart their system before the installation can complete (usually due to locked files).

You will typically install only one package but you may install as many as you wish. A dialog box will be presented to the user to confirm the installation. The example below will install two packages

    xpi["Calculator"] = "calc.xpi";
    xpi["PictureViewer"] = "pict.xpi";
    InstallTrigger.install(xpi , myCallbackFunction);

Two packages, the Calculator and PictureViewer are installed. The XPI files are URLs relative to the script triggering the installation.

installChrome ( arr , notifyFunction , type )

Installs a new chrome package. This function is similar to the install function, except with an additional parameter which specifies the type of chrome to install. The following values are valid:

- InstallTrigger.SKIN - Install a new skin
- InstallTrigger.LOCALE - Install a new locale
- InstallTrigger.CONTENT - Install a new content package

startSoftwareUpdate ( url , flags )

Starts a software installation. The first argument is the URL of the installation archive file. The second argument is used for flags, which is currently unused. The function is simply a shorthand for the install function when only one component is being installed and no callback function is desired.

Copyright (C) 1999 - 2002 XULPlanet.com