argument to getFolder is the subdirectory which we are going to install into, which doesn't have to exist. You can leave this argument out entirely if you don't need one.

Setting Install Files

Next, you need to specify which files should be installed. This involves the use of two functions, addDirectory and addFile. The addDirectory function tells the installer that a directory from the XPI archive (and all of its contents) should be installed to a particular location. The addFile is similar but for a single file.

Both the addDirectory and addFile functions have various forms. The simplest takes only one argument, the directory from the installer to install to the assigned installation directory.

addDirectory ( dir );

addFile ( dir );

Example:

addDirectory("findfile");

The example above will specify that the findfile directory from the installer archive should be installed. We can call these functions multiple times to install other files.

Next, we'll want to register the find files in the chrome system so that it can be used with a chrome URL. This can be done with the registerChrome function. It takes two arguments, the first is the type of chrome to register (content, skin or locale). The second is the directory containing the contents.rdf file to register. Because the find files dialog contains content, a skin file and a locale file, registerChrome will need to be called three times.

registerChrome(Install.CONTENT | Install.DELAYED_CHROME, getFolder(findDir, "content"));

registerChrome(Install.SKIN | Install.DELAYED_CHROME, getFolder(findDir, "skin"));

registerChrome(Install.LOCALE | Install.DELAYED_CHROME, getFolder(findDir, "locale"));

The DELAYED_CHROME flag is used to indicate that the chrome should be installed the next time Mozilla is run.

Installation Completion

The addDirectory and addFile functions don't copy any files. They only state which files should be installed. Similarly, registerChrome only states that chrome should be registered. To complete the process and begin copying files, call the performInstall function. It takes no arguments.

The final script for installing the find files component is shown below:

Example 13.2.1: Source

initInstall("Find Files","/Xulplanet/Find Files","0.5.0.0");

findDir = getFolder("Chrome","findfile");

setPackageFolder(findDir);

addDirectory("findfile");

registerChrome(Install.CONTENT | Install.DELAYED_CHROME, getFolder(findDir, "content"));

registerChrome(Install.SKIN | Install.DELAYED_CHROME, getFolder(findDir, "skin"));

registerChrome(Install.LOCALE | Install.DELAYED_CHROME, getFolder(findDir, "locale"));

performInstall();

Additional Install Features

This section describes some more specifics of installers.

Installer File Manipulation

The previous section described a basic installer. You may wish to perform some more elaborate processing during the installation. For example, you may want to install a package only when certain conditions are met, such as having a particular library installed.

In addition to the Install object, a File object is also available during an installation script. It provides some functions which can be used to examine and modify files on disk. You can use these to move, copy or delete files before or after the files are installed. For example, you might want to make a backup of some files first.

The following code will make a copy of the file "/bin/grep" and put it in the directory "/main".

var binFolder=getFolder("file:///","bin");

var grep=getFolder(binFolder,"grep");

var mainFolder=getFolder("file:///","main");

File.copy(grep,mainFolder);

The first line will retrieve a reference to the /bin directory. The text 'file:///' is a special string which means the root of the filesystem. From there, we get the file 'grep' which is contained inside the 'bin' directory. If this file does not exist, an error will occur during the installation. Next, we get the 'main' folder, again from the file system root. Finally, we call the File.copy function which copies the source file to the destination.

Functions also exist to move, rename and execute files. Thus, you can move files that might conflict with your package out of the way.

Handling Errors

You will likely want to handle errors gracefully. This will occur if a file or directory cannot be found, there is insufficient disk space or for a number of other reasons.

You can use the getLastError function to determine whether an error occured. If it returns SUCCESS, no error occured. Otherwise, the number will be an error code which indicates the type of error that occured. You can call this function at any point during the installation script to determine whether an error occured during the last operation.

If an error occurs, you will likely want to abort the installation. You may also want to display an error message to the user. For example, you might put the following as the last section of your script:

if (getLastError() == SUCCESS){

performInstall();

}

else {

cancelInstall();

}

Error codes that could be returned by getLastError are listed in the Mozilla source file nsInstall.h. During installation, a log file is created that contains the operations that are performed. It will also show any errors that occured. The log file can be found in the file 'install.log' in the Mozilla installation directory. A block of text will be added to this file for each installation that occurs.

The logComment function can be used to write a string of text to the log file. It takes one argument, the text to write.

The XUL Tutorial was created by Neil Deakin

http://www.xulplanet.com/