Chapter 6. Packaging and Installing Applications-P3 When you have very simple installations -- such as when you want to install a new skin -- you may not need to use the services from the Install object. Besides providing the services necessary for "triggering" the downloading of a package from a web site, the InstallTrigger object offers some simple methods for installing when you do not need to rearrange of the disk, register complications, or do other install-type preparation (see Table 6-2 ). Table 6-2. InstallTrigger interface showing the role of the InstallTrigger object in the overall installation process Method Description compareVersion Compares the version of a file or package with the version of an existing file or package. Enabled Indicates whether the Software Installation is enabled for this client machine. getVersionInfo Returns an InstallVersion object representing the version number from the Client Version Registry for the specified software or component. Method Description Install Installs one or more XPI files on the local machine. installChrome Installs new skin or locale packages in Netscape 6 and Mozilla. startSoftwareUpdate Initiates the download and installation of specified software. Note: deprecated in favor of install. This web page installation script defines its own install method in which a callback parameter on the InstallTrigger's own install( ) method checks the success of the installation and displays a relevant alert for the user (as shown in Example 6-17 ). Example 6-17. Install script callback function doneFn (name, result) { if (result != 0 && result != 999) alert("The install didn't seem to work, you could maybe try " + "a manual install instead.\nFailure code was " + result + "."); else alert("Installation complete, please restart your browser."); } function install(packageName, fileName) { var xpi = new Object( ); xpi[packageName] = fileName; InstallTrigger.install(xpi, doneFn); } <a href="javascript:install('xFly','xfly.xpi');">insta ll</a> 6.3.3.3. Installing non-Mozilla software The XPInstall technology downloads and installs any software on any machine using Mozilla or Netscape 6/7. The same Install object methods that download, register, and install new Mozilla packages (e.g., new themes or new Mozilla applications like xFly) can be used to download other executables and software into any location on the local machine. As with Mozilla application installs, you use an installation script within a XPI to initialize the installation, add the files you want to the installation, and then perform the install and put the software in the designated locations. Note that non-Mozilla software installations do not include a registration step, since the chrome registry does not track non-Mozilla software or any more general additions to the operating system. Example 6-18 shows a simple and typical non-Mozilla installation. Example 6-18. Non-Mozilla software installation script var xpiSrc = "file.txt"; initInstall( "Adding A File", "testFile", "1.0.1.7", 1); f = getFolder("Program"); // keyword for the main program // directory on the target platform // (e.g., the "Program Files" dir on win32) setPackageFolder(f); addFile(xpiSrc); if (0 == getLastError( )) performInstall( ); else cancelInstall( ); Refer to the "XPInstall API Reference" on http://developer.netscape.com for more detailed information about the XPInstall API and how it can be used in more complex installations. 6.3.4. Uninstalling Applications You may have noticed an uninstall( ) method on the Install object in the XPInstall API. This method does some of the work you need to do to uninstall packages from Mozilla, but it's a buggy process and doesn't finish the job.[1] Beyond the physical removal of the package resources during the uninstall, several RDF files in the chrome registry need to be updated, and the XPInstall uninstall( ) does not get to some of these files. Fortunately, the JSLib JavaScript developer's library has a well-implemented uninstall function, which you can use by importing the uninstall.js file and calling uninstall on the package you want uninstalled. uninstall.js is one of the JS file collections that comprise the JSLib. Once you install JSLib, using the uninstall method is simple: include("chrome://jslib/install/uninstall.js"); var p = new Uninstall('myPackageName'); p.removePkg( ); You might want to put this uninstall routine in a function so you can reuse it. function unInstall(pkg) { var p = new Uninstall(pkg); p.removePkg( ); } This method removes the resources themselves and deletes all references to the package in the chrome registry. The pkg parameter is the name of the package as defined in the manifest for that package. The xFly package manifest, for example, defines "xfly" as the name of the package, as shown in Example 6-19 . Example 6-19. Package metadata in the xFly manifest <!-- xFly package information --> <RDF:Description about="urn:mozilla:package:xfly" chrome:displayName="xFly" chrome:author="frillies" chrome:name="xfly"> </RDF:Description> Example 6-9 comes from the content package manifest for xFly, which is similar to the full content manifest for the XMLTerm application you saw in Example 6-4 . To uninstall the xFly package, then -- as you should do to the working version you have as you develop before installing the final version -- hook up a menuitem to call the uninstall routine: <menuitem id="uninstall-item" label="Uninstall xFly" oncommand="unInstall("xfly")" /> This menuitem should have access to a JavaScript file and contains the following code: include("chrome://jslib/install/uninstall.js"); function unInstall(pkg) { var p = new Uninstall(pkg); p.removePkg( ); } Notes [1] Currently, some open bugs in Bugzilla are tracking the progress of this method and its improvement. 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 [...]... has two files for icons located in mozilla/src/gtk: mozicon16.xpm and mozicon50.xpm Many utilities, such as the GIMP, PaintShopPro, and Xview, can transform images from other common formats 6.5 .1.3 Macintosh The Macintosh BNDL resource (OS icons for files and applications) and related resource types (4bit, 8bit, large, small icons, masks, and FREF) are contained in nsMacBundle.rsrc, located at mozilla/xpfe/bootstrap... C:\mozilla\src\mozilla\xpfe\bootstrap>nmake -f makefile.win An alternative to Steps 2 and 3 is to give your icon the same name as the Mozilla icon (mozilla.ico) and just drop it into the tree, replacing the existing one shown in Figure 6-6 Figure 6-6 Windows taskbar with Mozilla icon 6.5 .1.2 Unix X Windows uses the common X Pixmap (XPM) format for icons XPM files are C source code files, with each pixmap defined as a static character array... 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 6.5 Extra Tricks for Customizing an Application If the Mozilla application you are working on is more autonomous than a package that sits up on a Mozilla installation, you may want to add extra customization Here are two common features: the program icon and the... require recompilation of the bootstrap module 6.5 .2.2 Unix The splash screen uses the same XPM format as is used for the icons The file is called splash.xpm and is located in mozilla/xpfe/bootstrap Note that the splash display is turned off by default on this platform and can be displayed by using the -splash switch in a command shell /mozilla -splash 6.5 .2.3 Macintosh The file Splash.rsrc (located... or resources need to be changed to make your icon the default for Mozilla 6.5 .1.1 Windows In Windows, create your own icon and then follow these steps: 1 Go to the mozilla/xpfe/bootstrap folder in the source tree 2 Open the splash.rc resource file This can be done in the text editor of your choice or in any program with special handling for Windows resource files 3 Change the icon resource to the file... application and needs to process so much (including profiles, initialization code, and theme/locale selection from the chrome registry) before you actually see the first window appear, users need a visual clue that something is happening when Mozilla starts up If your application also requires a lot of processing at startup or if you would like to customize your application, then creating and using your...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... more details on obtaining and building the source code 6.5 .1 Icons Program icons are important for several reasons Primarily, however, they are a visual representation of your application on the system that it runs on, whether it runs in a file explorer, a taskbar, or an application selector This section tells you where to locate the current icons in the Mozilla application and what files or resources... screen is essential 6.5 .2.1 Windows The splash screen file is a bitmap image that also lives in the same splash.rc file that houses the icon file, perhaps more appropriately named in this case // Splash screen bitmap IDB_SPLASH BITMAP "splash.bmp" Again, you have the option of changing the resource file or calling the image file the same name as the Mozilla splash (splash.bmp) and dropping it into... \icons\default\ directory you will find the file winInspectorMain.ico on Windows This option is good for package authors who add windows to the Mozilla application and do not want to hijack this resource completely Icons can be installed as part of an XPI 6.5 .2 Splash Screen Are splash screens a necessary startup feature for a program or a shameless plug? The answer is probably somewhere in between, leaning . Chapter 6. Packaging and Installing Applications- P3 When you have very simple installations -- such. tree, replacing the existing one shown in Figure 6- 6 . Figure 6- 6. Windows taskbar with Mozilla icon 6. 5.1.2. Unix X Windows uses the common X Pixmap (XPM)