Guide to Customizing and Distributing Mozilla 1.4.1

Previous      Contents      Next

Chapter 12   Advanced Mozilla Customizations

After you've run the CCK tool, produced an installer, and made any manual customizations you may require for the CD autorun screen, you can perform additional manual customizations before distributing the installer to your users. This chapter provides an overview of the preferences architecture and the general procedure for manual customization. It also provides detailed, step-by-step instructions for some of the most common manual customizations.

This chapter contains these sections:

Understanding How Manual Customization Works
Understanding the Preferences Architecture
Before You Start
Editing a Configuration File with a Text Editor
Instructions for Common Manual Customizations

Understanding How Manual Customization Works

---

Mozilla is shipped with many preferences and user-interface items preset as "factory defaults." After Mozilla is installed, these settings are stored in special Javascript files called configuration files.

You can edit configuration files to customize the default settings for your users. For example, you can manually customize:

• The Welcome page that appears at startup


• Proxy settings


• Any items that appear in the Help menu in Mozilla (both text and URLs)


• Password requirements, such as whether an email password is remembered or needed for each session

To create a customized Mozilla installer by using a combination of the CCK tool and manual customizations, you follow this general procedure:

1. Complete all customizations that can be performed with the CCK tool and use the tool to build the installer. The installation files will be located in the directory



CCKTool\Configs\configuration_name\Output\
 

where configuration_name is the configuration name you specified (or selected) for your customized configuration in the first screen of the CCK tool.
 

2. Verify your customizations and run the CCK tool again, if necessary, to adjust them.


3. Identify the preferences you want to change and the Javascript files that specify them. Table 1 below specifies the main Javascript files involved. Detailed information on specific preference entries within those files will be available online at a later time; see Mozilla 1.4.1 Client Customization Kit Release Notes for the most current information. XXX we need to host docs like this at www.mozilla.org


4. Identify the xpi files in the installation files produced by the CCK Tool that contain the JavaScript files you want to change. (Table 1 below specifies the which xpi files contain which JavaScript files.)


5. For each xpi file involved:


• Use a utility such as WinZip to extract the entire xpi file into some convenient temporary directory.
• Locate the JavaScript files that you want to modify in the extracted files.
• Use a text editor to modify the JavaScript files.
• Use a utility such as WinZip to zip up all the files you extracted from the xpi, including the ones you modified.
• Replace the old xpi file with your new xpi file.
   
6. After you have modified the necessary JavaScript files and replaced the old xpi files with the revised xpi files, run the installer and test the resulting Mozilla installation to ensure that your customizations have taken effect.

For step-by-step instructions describing this procedure more precisely for specific manual customizations, see single change to a JavaScript file, see Instructions for Common Manual Customizations.

Understanding the Preferences Architecture

---

Factory defaults are set in .js files, which are in turn located in zipped .xpi files in the directory

CCKTool\Configs\my_config\Output\Core

The primary .js file is all-ns.js, which is located in the file browser.xpi.

Note: If you make changes to preferences stored (after installation) in the prefs.js file, where the user-configurable customizations are stored, you run the risk of overwriting the bookmarks, address books, and other settings that your users may have set in their existing profiles.

Table 12-1    JavaScript files to edit

Filename	XPI file that contains preferences file	Contents
all-ns.js	browser.xpi	general preferences and those not covered specifically by other .js files
config.js	browser.xpi	chrome-related preferences
editor.js	browser.xpi	preferences related to composer
mailnews.js	browser.xpi	mail and news preferences
prefs.js	The contents of prefs.js are created from the contents of the files all-ns.js and all.js in browser.xpi.	user-configurable customizations
security-prefs.js	browser.xpi	security preferences
Windows: winpref.js Unix/Linux: unix.js Macintosh: macprefs.js	browser.xpi	fonts for each platform

Setting a preference in one of the .js files will create a default value that can be changed by the user by choosing Preferences from the Edit menu. Not all preferences are initialized at startup via these .js files. In addition, some settings are stored in RDF files that live in the operating system's directory after the user installs Mozilla. For example, for Windows NT, the path would be:

C:\Winnt\Profiles\user_name\Application Data\Mozilla\Profiles\profile_name\

Important Legal Restrictions

The license that ships with the CCK tool imposes restrictions on certain kinds of customizations. In particular, under the terms of the license agreement, you may NOT perform any of the following customizations:

• Remove the Search and Directory folder from its location in the Bookmarks menu when you open a new profile with Mozilla 1.4.1.


• Remove or modify the contents of the Search and Directory folder in the Bookmarks menu.


• Change the My Sidebar tab that is open by default when you open a new profile with Mozilla 1.4.1 (currently the News tab).


• Remove the Search or Today's Tips sidebar tabs from the My Sidebar tabs shown by default when you open a new profile with Mozilla 1.4.1.


• Remove any of the My Sidebar tabs from the list of tabs available to an end user in the default drop-down list of sidebar tabs available when you open a new profile with Mozilla 1.4.1. (It's OK to add additional tabs).


• Change the default Search service to which the Location Bar Search button and other search services are linked.


• Change the page that opens by default when Mail starts up.

Before You Start

---

The CCK tool allows you to customize specific aspects of the look and feel of Mozilla. In addition, by editing all.js and other configuration files, you can customize almost any aspect of Mozilla. You'll need to familiarize yourself with the Mozilla user interface and associated preferences to assess how to customize Mozilla for your needs. You'll also need to identify:

• The configuration file (typically a JavaScript file) involved


• The name of the preference within that configuration file.


• The .xpi file where the configuration file is located in the installation files produced by the CCK tool.

More details about names of specific preferences and the configuration files where they are stored will be provided online. See the Mozilla 1.4.1 Client Customization Kit Release Notes for the most current information. XXX - need mozilla.org equiv

Some Mozilla features or attributes are under user control, but only indirectly. Such features include whether certain toolbars are displayed, and also settings that Mozilla remembers automatically, such as window size and position. Such settings are not "preferences" in the typical sense, because they cannot be set from a user-selected window or dialog box. Instead, these features are referred to as Mozilla "states."

In addition to the preferences that you can set, you can alter Mozilla configuration settings that are not under direct or indirect user control, such as the items that appear in the Help menu.

Editing a Configuration File with a Text Editor

---

By editing all-ns.js and other configuration files directly, you can modify Mozilla in a variety of ways. You should use a simple text editor (one that doesn't do any formatting) to modify a configuration file. For example, you can use NotePad for Windows, SimpleText for Mac OS, or vi for X-Motif. If you use a word processor to edit the configuration file, make sure you save the edited configuration file as plain (ASCII) text. If formatted characters are used, the configuration file may not be created correctly.

As described above under Understanding How Manual Customization Works, once you have extracted the .js file that you want to modify from the xpi file, you can edit it with a text editor. To do so, you must determine the value type that the preference takes (numeric, string, or boolean) and make the required change to produce the default setting that you want.

Important: Don't use Mozilla Composer to edit configuration files. Composer adds characters to the file that can interfere with its use as a configuration file.

Instructions for Common Manual Customizations

---

Customizing the Welcome Page

The Welcome page appears when the user starts up a new profile for the first time. You may want to customize it so you can provide up-to-date information for new users when they first launch Mozilla.

Follow these steps to manually customize the URL specified for the Welcome page:

1. Locate this file:



CCKTool\Configs\my_config\Core\browser.xpi
 

2. Unzip the entire file browser.xpi into a convenient empty directory.


3. In the directory containing the extracted files, locate the file bin/defaults/pref/all-ns.js.


4. Open all-ns.js with a text editor.


5. Locate this line:



pref("browser.startup.homepage", "chrome://navigator-region/locale/region.properties");
 

6. Change the URL to the URL for your own welcome page and save the file.


7. Zip up the entire bin directory again into a new file called browser.xpi.


8. Replace the original browser.xpi file in CCKTool\Configs\my_config\Core\ with the new browser.xpi.


9. Test your customization.

Previous      Contents      Next     

---

Copyright © 2003 Netscape Communications Corp. All rights reserved.

Last Updated July 30, 2003