Tài liệu Creating Applications with Mozilla-Chapter 6. Packaging and Installing Applications-P3 pdf

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

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

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

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

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 splash screen Some features require that you build the source code yourself, even just a particular module instead of the whole tree Refer to Appendix A for 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 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 of your choice

// Program icon

IDI_APPLICATION ICON

"mozdev.ico"

1 Recompile the bootstrap module This recompilation regenerates the

mozilla.exe executable file

C:\mozilla\src>cd 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 The window manager expects to find two XPM files for each icon specified

in the configuration files as ICON Mozilla 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 It also contains a MOZZ resource that references the Mozilla software license All Macintosh software have this set

of resources

If you want to change icons on a window-by-window basis, do it only

in Mozilla on the Windows platform In the chrome root, there exists a directory \icons\default\ Within this directory, you can place any number of icons for windows in your application The filename has

to be the same as the XUL window ID: <window_id>.ico One example of an icon being used in this way is the DOM Inspector

window in Mozilla In the \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 toward the necessary in the case of Mozilla (Figure 6-7 shows Mozilla's splash screen)

Figure 6-7 Mozilla's splash screen

Because Mozilla is a large 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 own unique splash 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