You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.



Configurable Chrome

Maintained by Benjamin Smedberg <benjamin@smedbergs.us>

What is Chrome?

Chrome is the user interface parts of the application window that are outside of a window's content area. Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome.

Chrome Providers

A supplier of chrome for a given window type (e.g., for the browser window) is called a chrome provider. There are three basic types of chrome providers:

content
The main source file for a window description comes from the content provider, and it can be any file type viewable from within Mozilla. It will typically be a XUL file, since XUL is designed for describing the contents of windows and dialogs. The javascript files that define the user interface are also contained within the content packages, as well as most XBL binding files.
locale
Localizable applications keep all their localized information in locale providers. This allows translators to plug in a different chrome package to translate an application without altering the rest of the source code. The two main types of localizable files are DTD files and java-style properties files.
skin
A skin provider is responsible for providing a complete set of files that describe the visual appearance of the chrome. Typically a skin provider will provide CSS files and images.

In addition, some packages are marked with a special flag indicating that they are platform specific. Some parts of content, skin, locales may be different based on the platform being run. These packages contain three different sets of files, for windows/os2, macintosh, and unix-like platforms. For example, the order of the "OK" and "cancel" buttons on a dialog is different, as well as the name of some items.

The providers work together to supply a complete set of chrome for a particular window, from the images on the toolbar buttons to the files that describe the text, contents and appearance of the window itself.

The Chrome Registry

The gecko runtime maintains a service known as the chrome registry that provides mappings from chrome package names to the physical location of chrome packages on disk.

This chrome registry is configurable and persistent, and thus a user can install different chrome providers, and select a preferred skin and locale. This is accomplished through xpinstall and the extension manger.

In order to inform the chrome registry of the available chrome, two different types of manifests are available. The "new-style" plaintext manifests (introduced by Bug 278534), and an older RDF format known as "contents.rdf". The contents.rdf format is old, and the new plaintext format is preferred for new code.

The mozilla suite (seamonkey) does not support the plaintext manifest format.

Chrome Manifests (plaintext, new-style)

The plaintext chrome manifests are a simple line-based format:

content package
content packagename path/to/files
locale package
locale packagename localename path/to/files
skin package
skin packagename skinname path/to/files
XUL overlay
overlay chrome://file-to-overlay chrome://overlay-file
Style overlay
style chrome://file-to-style chrome://stylesheet-file

To indicate that a content package is platform-specific, add the "platform" modifier after the path; e.g.

content global-platform toolkit/content/global-platform/ platform
content	necko	jar:comm.jar!/content/necko/
locale	necko	en-US	jar:en-US.jar!/locale/en-US/necko/
content	xbl-marquee	jar:comm.jar!/content/xbl-marquee/
content	pipnss	jar:pipnss.jar!/content/pipnss/
locale	pipnss	en-US	jar:en-US.jar!/locale/en-US/pipnss/
overlay	chrome://browser/content/pageInfo.xul	chrome://pippki/content/PageInfoOverlay.xul
overlay	chrome://communicator/content/pref/preftree.xul	chrome://pippki/content/PrefOverlay.xul
overlay	chrome://navigator/content/pageInfo.xul	chrome://pippki/content/PageInfoOverlay.xul
content	pippki	jar:pippki.jar!/content/pippki/
locale	pippki	en-US	jar:en-US.jar!/locale/en-US/pippki/
content global-platform jar:toolkit.jar!/content/global-platform/ platform

contents.rdf manifests

The old contents.rdf manifests are still supported for backwards compatibility. See the JAR packaging documentation for details and examples.