Creating Applications with Mozilla
PrevChapter 6. Packaging and Installing ApplicationsNext

6.4. Finishing Things Up

We dealt with the xFly example earlier in this chapter and then discussed general information about file formats, installation scripts, and xpinstall. You now have everything you need to make the xFly package an installable application. Borrowing liberally from the examples in the earlier sections Section 6.3.1 and Section 6.3.2, you can bundle a JAR file or the entire subdirectory structure you already created for xFly in the chrome directory: 

chrome
    xfly      content
      skin
      locale

Bundle the JAR file into a ZIP file, add an installation script to that ZIP file (and a web trigger script to the application's web page), and make your application available to Mozilla users everywhere.

6.4.1. Creating the xFly XPI

An XPI file is nothing more than a ZIP file with its own installation script. Using a ZIP utility, you can archive the xfly directory and preserve the subdirectory structure so it's installed in the user's chrome directory as it is in your own. Make sure that the ZIP file, whatever it's called, contains the top-level xfly subdirectory as part of this structure. If it is a JAR file you are distributing for your package, make the JAR file (xfly.jar) the top level, with the content, skin, and locale directories contained within: 

xfly.jar
  content
  skin
  locale

The URLs you used to refer to various parts of your xFly application (e.g., chrome://xfly/content/xfly.js as part of the command that imports the external script file into the main XUL file) will be registered during the installation process with that xfly directory or JAR file directly underneath the Mozilla chrome directory.

6.4.2. Adding the Installation Script

Once you understand the Section 6.3.2 section (earlier in this chapter), creating an installation script for the xFly application is straightforward, as Example 6-20 shows. In this case, we bundled all the xFly subdirectories in a single JAR file, xfly.jar.

Example 6-20. xFly installation script 

const X_MSG             = "Install xFly";
const X_NAME            = "xFly";
const X_VER             = "0.0.1";
const X_JAR_FILE        = "xfly.jar";
const X_CONTENT         = "content/";
const X_SKIN            = "skin/";
const X_LOCALE          = "locale/en-US/";
const X_CHROME          = "chrome";
var err = initInstall(X_MSG, X_NAME, X_VER); 
logComment("initInstall: " + err);
logComment( "Installation started ..." );
addFile("We're on our way ...", X_JAR_FILE, getFolder(X_CHROME), "");
registerChrome(CONTENT|DELAYED_CHROME, getFolder(X_CHROME, X_JAR_FILE), X_CONTENT);
registerChrome(SKIN|DELAYED_CHROME, getFolder(X_CHROME, X_JAR_FILE), X_SKIN);
registerChrome(LOCALE|DELAYED_CHROME, getFolder(X_CHROME, X_JAR_FILE), X_LOCALE);
err = getLastError( );
if ( err == SUCCESS )  {      // if there have been no errors:
  performInstall( );           // install "xfly.jar"
  alert("Please restart Mozilla");
}
else  {                       // otherwise
  cancelInstall( );            // cancel the installation.
}

Save the installation code in Example 6-20 as install.js and add it to the ZIP file you created out of the xfly subdirectory. Name this zip file xfly.xpi. The installation script should be archived at the top level of the XPI file and appear next to the xfly subdirectory or JAR file. Another feature of this script is the declaration of constant variables at the top, for various values used in the script. This feature is good for re-use and organizing your script.

6.4.3. Web Page Installer

The XPI file you created in the last two sections, with its internal install.js file, is all you need to make your Mozilla application portable and installable. The final step creates a link on a regular web page that tells Mozilla where this file is, as shown in Example 6-21.

Example 6-21. Web page trigger 

<a href="#"
   onclick="InstallTrigger.install(
   {`xfly' :
   'xfly.xpi'});">
   Install my cool xFly Application</a>

When the user browses the application web page and clicks the "Install my cool xFly Application" link shown above, Mozilla finds and downloads xfly.xpi in the same directory. It then opens the archive, reads the install script, creates the xfly subdirectory on the local machine or moves the JAR file onto the local machine, and registers it with the chrome registry. When the user restarts the browser, the xFly application is integrated into Mozilla and ready for use. The user can access it with any overlays that put it into the browser's interface (e.g., as an item in the Tools menu) or invoke it directly by using the special chrome option for pointing to a registered chrome: 

mozilla -chrome chrome://xfly/content

Tip

You don't need to have an install page to install a XPI in Mozilla. If, instead of a web page, you provide a URL that points directly to a XPI, Mozilla displays a dialog that asks the user whether they want to initiate the installation of that XPI. As with any new software installation, however, a page that describes the package and what it does can help allay fears and promote use.

PrevHomeNext
Installing Mozilla ApplicationsUpExtra Tricks for Customizing an Application