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

Accessing the chrome registry in installation scripts An install script is a required part of a software package like the xFly.. The two main functions of an installation script are the

Chapter 6 Packaging and Installing Applications-P2 6.2.3.4 Overlaying Mozilla files into your application

In the previous section, we described how to use the XUL overlay

technology to put information from your application into the Mozilla

browser When developers use overlays in this way, they usually add a

menuitem or a new UI to the browser that provides access to the

application

But overlays can also add interface elements and other data from Mozilla into the application itself In fact, each component in Mozilla imports a lot of its own user interface from such XUL overlay mainstays as

globalOverlay.xul, tasksOverlay.xul (the file into which the xFly menuitem is overlaid), and navigatorOverlay.xul As you can see when you look at the main browser file, navigator.xul, shown in Example 6-7, most user interface is actually brought in from these reusable overlays A relatively small percentage of all that appears in the browser is defined within that particular navigator.xul file

Example 6-7 Overlays in navigator.xul

<?xul-overlay

href="chrome://navigator/content/navigatorOverlay.xul"?>

<?xul-overlay

href="chrome://navigator/content/navExtraOverlay.xul"?>

<?xul-overlay

href="chrome://navigator/content/linkToolbarOverlay.xul"?>

<?xul-overlay

href="chrome://communicator/content/sidebar/sidebarOverlay.xul"?>

<?xul-overlay

href="chrome://communicator/content/securityOverlay.xul"?>

<?xul-overlay

href="chrome://communicator/content/communicatorOverlay.xul"?>

<?xul-overlay

href="chrome://communicator/content/bookmarks/bookmarksOverlay.xul"?>

Of these overlays, those with the most value for application developers are the communicatorOverlay.xul, which defines many of browser menus; the tasksOverlay.xul, which adds the Tools menu and brings

in all of its application menuitems as well as a lot of important browser functions like toOpenWindowByType and toNavigator (for returning

to the main browser window); and the globalOverlay (which is overlaid

into navigatorOverlay.xul, so it gets loaded there), which defines even more

general and low-level features like pop ups and functions for quitting the application or setting tooltip text

Once files are divided into subdirectories and the manifests for each

subdirectory, your application is technically a package although until you compress it and create an install script, it's a package only for your computer and the environment in which it was created See the section Section 6.4 later in this chapter to see how you can use the file format and installation information to make the xFly something you can put on a web server and have users install with a single click on a web page

6.2.4 The Chrome Registry

The chrome registry was briefly mentioned several times in this book It plays an important (but sometimes invisible) role in the way Mozilla

applications, including the Mozilla browser itself, deal with user

information, new components, skins, and other resources

At the beginning of the book, you had to create RDF files that would

describe your application to Mozilla Special entries also needed to be made

to the installed-chrome.txt file in the chrome application

directory These entries are just two of the most common ways to address the chrome registry, which is what Mozilla uses to persist configurable aspects of the browser and its other applications

6.2.4.1 Where is the chrome registry?

The chrome registry is not a single file and it's not stored in a single place Rather, it is a distributed collection of data and interfaces for data

manipulation The data itself generally lives in RDF files, many of which are

in the chrome application directory The chrome registry APIs

principally nsIChromeRegistry are used by installation scripts when they register new software, by the skin-switching UI, and by the language

selection facility The chrome registry is the means through which packages are registered

In some cases, especially when you create and debug your Mozilla

application, you may want to edit the RDF files that make up the chrome registry directly But more often, you can use external scripts, inline

JavaScript, or the installed-chrome.txt file to get what you need from the registry Procedures for doing so are described in the section

Section 6.2.2 earlier in this chapter, and in the section Section 6.3.2 later in this chapter

6.2.4.2 Accessing the chrome registry in installation scripts

An install script is a required part of a software package like the xFly The two main functions of an installation script are the physical download and installation of files in the package and registration of that software with the chrome registry Install scripts use functions from the XPInstall API to install the files and functions from the chrome registry interface to handle the latter, as seen in this snippet:

registerChrome(PACKAGE | DELAYED_CHROME,

getFolder("Chrome", "help"), "content/");

The registration process is typically something that happens between the install initialization and the actual execution of the install:

initInstall( ) // initialize the overall

installation

// add items to installed using:

// addFolder, addDirectory, getFolder, and others

registerChrome(TYPE, dir, subdir)

performInstall( );

Scripts and the installation process, including the registration of installed packages, are detailed in the next section

6.3 Installing Mozilla Applications

Once your application is packaged, the next step is to create a cross-platform installation, or XPI A XPI is a special file archive that contains your

Mozilla package(s) and its own installation instructions The relationship of the various parts of the installation process the XPI itself, the internal installation script, the trigger script that begins the installation, and the

Mozilla browser can be visualized in Figure 6-4

Figure 6-4 Installation process overview

6.3.1 The XPI File Format

Mozilla cross-platform installations use XPIs as the file format in which to organize, compress, and automate software installations and software

updates A XPI is a PKZIP-compressed archive (like ZIP and JAR files) with a special script at the highest level that manages the installation A quick scan of the contents of a XPI file (which you can open using with any unzip utility) reveals the high-level directory structure shown in Example 6-

application directory itself

In the case of the Mozilla browser, the XPIs manage the transfer and registry

of all components the chrome files in the JARs, the executables, the

default user information, and the libraries As you will see in the installation script, the contents of the archive are installed onto the filesystem in much the same way as they are stored in the archive itself, although it's possible to rearrange things arbitrarily upon installation to create new directories, install files in system folders and other areas, or execute software that

handles other aspects of the installation, such as third-party installers

6.3.1.1 XPI example

When the items to be installed are very simple, XPIs may contain nothing more than a single executable and the install script itself, as shown in Figure 6-5 In this figure, the WinZip utility has been used to display the contents of

a XPI that installs a text editor on a Win32 system

Figure 6-5 Simplest XPI archive

This example uses XPInstall technology to install something that may or may not be a Mozilla application The install.js script in Example 6-8 would look like this In Mozilla application development, however, XPIs often contain JAR files that are installed as new packages in the Mozilla distribution To make a XPI for your package, use any zip software

(applications or extensions that will be part of the main Mozilla distribution

are required to use the free zip utility from InfoTools so that they can be run

as part of the build process) to archive your files

6.3.1.2 JARs versus XPIs

Technically, only the internal installation script distinguishes JARs and XPIs However, Mozilla treats them differently Since JARs do not include this installation script, they cannot install full content or applications by themselves In this case, "content" means XUL, XBL, or JavaScript files that have script access to XPCOM Files of this kind that are in JARs are denied access to XPConnect and are not registered as content in the chrome

registry JARs are used primarily to install locales, or language packs, and skins

Skins that contain scripts and bindings (see the section Section 4.5.3 and the Evil Skins sidebar, both in Chapter 4) are seen more as chrome content and must be installed in XPIs if they are to be fully functional Like executables that are fetched from the Web, XPIs can cause trouble when downloaded by unprepared users since the software in XPIs are given the same privileges on the Mozilla platform that the browser chrome itself has

The characteristics and usage of an XPI are:

• Has an install.js file

• Can install anything via XPInstall API

• PKZip-compressed

• May contain one or more JAR packages

• Mozilla installation

• Used for new packages

The characteristics and usage of a JAR are:

• Contains only the resources themselves

• Installed with an external script

• May be installed inside a XPI

• PKZip-compressed

• Themes

• Languages packs

• Storage archive for installed components

Mozilla uses the presence of this internal installation script and not the file suffix (which can be changed easily enough) to determine what type of archive it is Accordingly, JARs are most often used to install new themes and new language packs, which can be done by using just a brief trigger script on a web page loaded into Mozilla When they contain new chrome new XUL and JavaScript that will access the Mozilla objects via XPConnect JAR files must be put within a XPI that can register them properly

6.3.2 Installation Scripts

Most new packages in Mozilla are installed by means of installation scripts These scripts are written in JavaScript Unlike regular web page JavaScript,

however, which uses window as the top-level object, installation scripts have a special install object context As you will see in the following

examples, the Install object even when it's implicit and not prefixed to the object methods is the top-level object upon which most methods are called

6.3.2.1 Script examples

At their very simplest, installation scripts look something like Example 6-9

Example 6-9 Simple install script

// initialize the installation first

initInstall("My Package Install", "package_name",

These methods are being called on the Install object, which is implicit in

an installation script Example 6-10 is an equivalent (and still very compact) installation script The Install object is prefixed explicitly to the install functions

Example 6-10 Script that explicitly prefixes the Install object

Install.initInstall("My Package Install",

Example 6-11 A more complicated install script

var vi = "10.10.10.10";

var xpiSrc = "adddir1";

initInstall("addFileNoVers1", "adddir_1", vi, 1);

6.3.2.2 Web page installations

XPInstall technology makes software installation from a web page very easy When a link on a web page kicks off the installation of new software,

"trigger" code on the web page starts the process and gets the XPI onto the local system Once this is done, the install.js file in the XPI can take

up the full installation and registration of new files

In Example 6-12, the trigger script placed in an onclick event handler

on the page starts the installation of a new theme on the local machine, where the XPI can be unpacked and its installation script executed in full

Example 6-12 Trigger script on a web page

Install the New Blue theme</a>

Later, we discuss in more detail the Install object, whose methods are typically called in installation scripts

6.3.2.3 Scriptless installations

When you have a simple Mozilla package like a theme, which does not need special security privileges and which is always installed in a particular

location, you can leave out the XPI and its internal installation script

altogether and use a trigger script like Example 6-13 and a regular JAR file

to download and register the new package

Example 6-13 Scriptless install of a JAR

Install the New Blue theme</a>

The only difference here is that the item to be installed is a JAR and not a XPI file Also, no internal installation script is present (since of the two, only XPIs carry their own install.js file) When the InstallTrigger object gets a JAR with a package manifest it can read and a package type that doesn't break the security boundary for applications (i.e., a new theme, a new language pack, or new content that doesn't use XPConnect), it can

download and register that package with the chrome registry and make it available to users The JAR and a trigger script like the one just shown are all you need in this case See the earlier section, Section 6.3.1.2 for more detail on the limitations of scriptless installs

The xFly application accesses XPCOM objects in Mozilla, which

makes it a full-blown XPConnected application Thus, it needs to be installed in a XPI file that has its own internal installation script

6.3.2.4 Platform-dependent installation

Though the XPI format is by definition cross-platform, the files you

distribute within it may need to be installed on a per-platform basis The

platform can be retrieved using the platform property of the Install object or the getFolder function Example 6-14 shows a JavaScript

function for install.js for returning the platform that the script is

var fOSWin = getFolder("Win System");

// do Windows script and files

}

else { // mac

// do Mac script and files

}

6.3.2.5 The install log

When you are testing your XPI or need a way to troubleshoot installation problems, one of the best methods is to consult the installation log file This

file is called install.log and lives in the bin directory

The install.log file is generated the first time you try to install software in

Mozilla and appended to for each subsequent installation The format of the file in which the URL and date of the installation appear as a heading makes it easy to find the installation you are checking on in the install log

Example 6-15 shows the output in install.log after a single successful installation

Example 6-15 install.log

-

-http://books.mozdev.org/examples/xfly.xpi

06/28/2002 19:12:59

-

Install xFly (version 0.0.1)

logComment( "Installation started " );

The output for this call will appear in install.log formatted like this:

** Installation started

When installation is not smooth, Mozilla outputs an error code to track down what is happening For example, if you declare a constant variable twice in your install script, you will receive notification of an script error in the UI, and this error will be logged in install.log:

** Line: 4 redeclaration of const X_JAR_FILE

Install **FAILED** with error -229 07/01/2002 11:47:53