Creating Applications with Mozilla-Chapter 6. Packaging and Installing Applications-P2

Chia sẻ: Thanh Cong | Ngày: | Loại File: PDF | Số trang:23

Thêm vào BST

Báo xấu

66
lượt xem 4
download

Download Vui lòng tải xuống để xem tài liệu đầy đủ

Tham khảo tài liệu 'creating applications with mozilla-chapter 6. packaging and installing applications-p2', công nghệ thông tin, kỹ thuật lập trình phục vụ nhu cầu học tập, nghiên cứu và làm việc hiệu quả

Chủ đề:

Bình luận(0) Đăng nhập để gửi bình luận!

Lưu

Nội dung Text: Creating Applications with Mozilla-Chapter 6. Packaging and Installing Applications-P2

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
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- 8. Example 6-8. Top level of the browser.xpi archive install.js bin\ chrome\ components defaults\ icons\ plugins\ res\ Note that the high-level structure in Example 6-8 parallels the installed browser's directory structure very closely. The bin directory at the highest level of the archive corresponds to the Mozilla application directory. On Unix, this directory is actually called bin, where all of the resources are stored. On other platforms, the installation puts these resources in the 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", "1.0", 1); // add files to the installation f = getFolder("Program"); setPackageFolder(f); addFile("package.xpi") // perform the installation performInstall( ); 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", "package_name", "1.0", 1); f = Install.getFolder("Program"); Install.setPackageFolder(f); Install.addFile("package.xpi") Install.performInstall( ); As they become more complicated, install scripts may set up and arrange target directories in more specific ways, do more error checking, and include variables to make the code more readable and reusable, as seen in the longer install script in Example 6-11. Example 6-11. A more complicated install script var vi = "10.10.10.10"; var xpiSrc = "adddir1"; initInstall("addFileNoVers1", "adddir_1", vi, 1); f = getFolder("Program"); setPackageFolder(f); err = addDirectory(xpiSrc); logComment("the error = " + err); if (0 == getLastError( )) performInstall( ); else cancelInstall( );
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 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 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 running on. Example 6-14. Getting the operating system in an install script function getPlatform( ) { var platformStr; var platformNode; if('platform' in Install) { platformStr = new String(Install.platform); if (!platformStr.search(/^Macintosh/)) platformNode = 'mac'; else if (!platformStr.search(/^Win/)) platformNode = 'win'; else platformNode = 'unix'; } else { var fOSMac = getFolder("Mac System");
var fOSWin = getFolder("Win System"); logComment("fOSMac: " + fOSMac); logComment("fOSWin: " + fOSWin); if(fOSMac != null) platformNode = 'mac'; else if(fOSWin != null) platformNode = 'win'; else platformNode = 'unix'; } return platformNode; } It's often necessary to check the platform when you install new language packs. At the time of this writing, issues related to write access to the chrome folder on Unix systems require some forking in the install script. There are also certain JAR files that are installed on a per-platform basis in language packs. Example 6-14 covers the three major platforms (Windows, Mac, and *nix). Here is how you use it: platformNode = getPlatform( ); if (platformNode != 'unix') { // do Unix script and files } else if (platformNode != 'win') {
// 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)
------------ [1/4] Installing: C:\MOZILLA\BIN\chrome\xfly.jar [2/4] Register Content: jar:resource:/chrome/xfly.jar!/content/ [3/4] Register Skin: jar:resource:/chrome/xfly.jar!/skin/ [4/4] Register Locale: jar:resource:/chrome/xfly.jar!/locale/en-US/ Install completed successfully -- 06/28/2002 19:13:03 In your install.js file, you can use the method logComment to create output other than these standard logging messages. This can be very useful for debugging your install scripts or providing extra feedback: 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
A full list of error codes can be found at http://lxr.mozilla.org/seamonkey/source/xpinstall/src/nsInstall.h or in the XPInstall API Reference at http://developer.netscape.com/docs/manuals/xpinstall/err.html. Though XPInstall is enabled by default, there is preference to turn it on and off in the user profile preferences file (prefs.js). To disable XPInstall, set the preference like this: user_pref("xpinstall.enabled", false); And be aware that target installation platforms may have this preference turned off, which prevents you from installing any new software in Mozilla. 6.3.3. XPInstall XPInstall is a technology used for cross-platform installation. Mozilla uses it extensively to install new packages, but as a general-purpose technology, it can be used to install anything on your computer. The XPI file format we described in the section Section 6.3.1 earlier in this chapter is the basic unit of exchange in an XPInstall and the installation script manages the installation. Installation scripts -- whether they appear within the XPI, on a web page as an external "trigger script," or elsewhere in JavaScript -- use the XPInstall API to do all the heavy lifting. The XPInstall API includes installation functions (Example 6-16) organized into such high-level objects as the Install object, the InstallTrigger object, and the File object, which you can use to install new Mozilla packages.
Example 6-16. Common XPInstall functions initInstall( ) // initializes every installation getFolder( ) // creates a new folder on the target system addFile( ) // adds files and directories to the install performInstall( ) // executes the installation cancelInstall( ) // cancels installation if there are errors In addition to the XPInstall API installation functions, installation scripts often call methods on the chrome registry itself. As described earlier in this chapter in the Section 6.2.4 section, the chrome registry handles the registration of new files and packages on the local system, the maintenance of user configurable data (such as what skin or theme you currently selected), and several utility functions used to make installations easier and more successful. 6.3.3.1. The Install object The Install object is the main object in the XPInstall API. It provides most of the methods and properties used in installation scripts. initInstall(displayName, name, version, flags) The initInstall( ) method that initializes the installation process takes the following parameters: displayName is the name you give to the installation itself; name is the name of the package to be installed (which
must match the name given to the package in the manifests); version is the version of the package being installed (also specified in the manifest); and flags is an optional parameter reserved for future use (which is set to "0" by default and about which you don't have to worry). Example: initInstall("Example Installation", "xfly", "0.9", 0); addFile(file) The addFile( ) method adds a single file to the initialized installation. file is a pointer to the file in the XPI that will be installed. Example: addFile("simple.exe"); err = performInstall( ) The performInstall( ) method starts the installation that you set up. Example: performInstall( ); The Install object exposes the methods listed in Table 6-1. Table 6-1. Install object methods Method Description AddDirectory Unpacks an entire subdirectory. AddFile Unpacks a single file. Displays an Alert dialog box with a Alert message and an OK button.