CHAPTER 9 Tutorial: Packaging WebLock

CHAPTER 9 Tutorial:
Packaging WebLock

In this final part of the tutorial, we'll put all of the pieces of the web locking component-the library itself, the type library, the header file, and the user interface resources-into a package that can be installed on other systems. The first section, "Component Installation Overview", describes the general installation process in Mozilla. The following sections describe the steps you can take to organize the WebLock component for distribution and installation.

Note: the emphasis of this tutorial is on the component development itself, so this section on packaging and installing extensions to Gecko is necessarily brief. For more detailed information on packaging and installation of components into Gecko-based applications, see http://www.mozilla.org/projects/xpinstall.

"Component Installation Overview"
"Archiving Resources"
"The WebLock Installation Script"
"The WebLock Trigger Script"

Component Installation Overview

XPInstall is a set of JavaScript APIs for creating installation scripts. Using XPInstall, you can create web-based installations for Gecko-based applications, Mozilla extensions, or individual components. The installation script for the WebLock component can also be used to register the component with the browser into which it is installed (see "Registration Methods in XPCOM" for more information on registration).

The sample installation script shown below uses the Mozilla XPInstall technology to manipulate an installer and talk to Mozilla's chrome registry as high-level JavaScript objects.

What Is the Chrome Registry?
Like the Windows registry, the chrome registry is a database of information about applications, skins, and other extensions that have been installed in a Gecko application. Since Mozilla and other Gecko-based applications are cross-platform, this database is abstracted above the operating system or any particular platform's registry. The chrome registry lives in a series of RDF/XML files in the application directory of Mozilla and other Gecko-based browsers, where new installs, user configurable data, skins, and other information are related to one another and the application itself.

JavaScript APIs from the XPInstall Install object download the JAR in which the installable files appear and call registration methods that tell Mozilla about the new component and the UI it uses to access the WebLock component. Figure 8 is the complete trigger installation script, which can be launched from a web page. The files themselves are stored in the JAR file weblock.jar, which is simple a ZIP file with the XPI extension that sometimes also contains an internal installation file called install.js.

Once you have the component and the other resources for Weblock packaged properly (see the following section, "Archiving Resources"), the installation script for WebLock is a simple one (see "The WebLock Installation Script").

Archiving Resources

Once you have compiled all the resources that make up the WebLock component and the files that make up the user interface that will be added to the browser, you can place these within a subdirectory called weblock.

Place the entire subdirectory into a ZIP archive and name the archive weblock.xpi. The archive, its subdirectory structure, and its contents should look like this:

Figure 1. weblock.xpi Archive Viewed in WinZIP
Note that the top level of the archive holds the install.js installation file, an RDF manifest for the package as a whole, and the component files (weblock.xpt and weblock4.dll). The component files are copied to the components directory of the Gecko application, and the weblock subdirectory gets copied over into the chrome subdirectory, where its UI resources can be added dynamically to the XUL-based Gecko application.

The next section shows how this process of downloading, copying and registering the necessary files from the XPI can be achieved with an XPInstall installation script.

The WebLock Installation Script

The installation script is the JavaScript file that is stored within the XPI. It must appear at the top level of the installation archive (i.e., weblock.xpi) itself. Once triggered (see the next section, "The WebLock Trigger Script"), the installation script:

downloads the WebLock component and places it in the components directory
copies the weblock subdirectory in the Mozilla chrome application subdirectory
registers both the component and the UI

The XPInstall API provides such essential methods¹ as initInstall, registerChrome, addFile, and others.

// initialize the installation var err = initInstall("WebLock", "weblock", 1.0); var componentsDir = getFolder("Components"); var cf = getFolder("Chrome"); // add the DLL and say where it'll go addFile ("weblock.dll", 1.0, "weblock.dll", componentsDir, ""); // add the typelib also addFile ("weblock.xpt", "1.0", "weblock.xpt", componentsDir, ""); // add the weblock subdirectory // of the XPI and specify that it be // installed in the chrome application directory err = addDirectory ("weblock", "1.0", "", chromeDir, "") // ? have to register component here or with regxpcom? // register the new UI with the mozilla chrome registry registerChrome(CONTENT, getFolder(cf,"weblock.xpi"),"weblock"); registerChrome(SKIN, getFolder(cf, "weblock.xpi"),"weblock"); // perform the installation if there are no errors if (err==SUCCESS) performInstall(); else cancelInstall(err);

Figure 2. WebLock Installation Script
The WebLock Trigger Script

The trigger script is the script placed on a web page that actually initiates an XPInstall installation and calls the installation script that appears in the XPI. Figure 3 is a complete webpage in which the trigger script is defined as a JavaScript function, installWebLock, that gets called when the user clicks the hyperlink.

<html> <title>WebLock Installation</title> <script> // trigger function // that downloads the XPI // so the install.js file inside can be // read and executed function installWebLock() { weblock_xpi = {`WebLock Extension': `weblock.xpi'}; InstallTrigger.install(weblock_xpi); </script> <h1>Install WebLock</h1> <p><a href="javascript:void" onclick="installWebLock();">install weblock</a> </html>

Figure 3. Trigger Script for WebLock
Distributing Your Component

Once you have the component packaged properly and the necessary installation and trigger scripts, you are ready to distribute your component so others can install it in their Gecko applications.

In Mozilla and Netscape browsers, XPInstall makes this process especially easy by providing the file format (XPI) and the necessary installation scripts for doing a web-based installation. As Figure 2 demonstrates, XPInstall uses special keywords to refer to common installation directories such as components in a generalized, cross-platform way.

If you are installing WebLock in an Gecko-based application for which XPInstall is not available, then you will have to devise a separate installation scheme. We leave this as an exercise for the reader.
¹ The methods are available on the main Install object, which is implied in the script below in the same way that the window object is implied in JavaScript manipulation of the DOM of a web page. In other words, the fragment var initInstall() from the script is equivalent to var Install.initInstall().

Note: the emphasis of this tutorial is on the component development itself, so this section on packaging and installing extensions to Gecko is necessarily brief. For more detailed information on packaging and installation of components into Gecko-based applications, see http://www.mozilla.org/projects/xpinstall.

What Is the Chrome Registry? Like the Windows registry, the chrome registry is a database of information about applications, skins, and other extensions that have been installed in a Gecko application. Since Mozilla and other Gecko-based applications are cross-platform, this database is abstracted above the operating system or any particular platform's registry. The chrome registry lives in a series of RDF/XML files in the application directory of Mozilla and other Gecko-based browsers, where new installs, user configurable data, skins, and other information are related to one another and the application itself.

// initialize the installation var err = initInstall("WebLock", "weblock", 1.0); var componentsDir = getFolder("Components"); var cf = getFolder("Chrome"); // add the DLL and say where it'll go addFile ("weblock.dll", 1.0, "weblock.dll", componentsDir, ""); // add the typelib also addFile ("weblock.xpt", "1.0", "weblock.xpt", componentsDir, ""); // add the weblock subdirectory // of the XPI and specify that it be // installed in the chrome application directory err = addDirectory ("weblock", "1.0", "", chromeDir, "") // ? have to register component here or with regxpcom? // register the new UI with the mozilla chrome registry registerChrome(CONTENT, getFolder(cf,"weblock.xpi"),"weblock"); registerChrome(SKIN, getFolder(cf, "weblock.xpi"),"weblock"); // perform the installation if there are no errors if (err==SUCCESS) performInstall(); else cancelInstall(err);

<html> <title>WebLock Installation</title> <script> // trigger function // that downloads the XPI // so the install.js file inside can be // read and executed function installWebLock() { weblock_xpi = {`WebLock Extension': `weblock.xpi'}; InstallTrigger.install(weblock_xpi); </script> <h1>Install WebLock</h1> <p><a href="javascript:void" onclick="installWebLock();">install weblock</a> </html>

Copyright (c) 2003 by Doug Turner and Ian Oeschger. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.02 or later. Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.