Chrome registration

  • Revision slug: Chrome_Registration
  • Revision title: Chrome registration
  • Revision id: 13604
  • Created:
  • Creator: Jens.B
  • Is current revision? No
  • Comment fixed caption/section hierarchy

Revision Content

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. 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.

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.

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, a text manifest is used: this manifest is "chrome.manifest" in the root of an extension, or theme, and chrome/*.manifest in a XULRunner application.

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

content packagename path/to/files <flags>
locale packagename localename path/to/files
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

Flags

Content packages can have flags added at the end of the registration. These flags mark special attributes of chrome.

Platform-specific packages

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.

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

content global-platform jar:toolkit.jar!/toolkit/content/global-platform/ platform
xpcnativewrappers

Chrome packages can decide whether to use the xpcnativewrappers security mechanism to protect their code against malicious content access. See Safely accessing content DOM from chrome for details. As of Firefox 1.1a1, this flag is *off* by default, and must be explicitly enabled by specifying xpcnativewrappers=yes. In the future, this flag will be enabled by default and extensions which need insecure access to the content objects will be required to specify xpcnativerwrappers=no.

Example Chrome Manifest

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/ xpcnativewrappers=yes
locale        pippki      en-US       jar:en-US.jar!/locale/en-US/pippki/
content       global-platform         jar:toolkit.jar!/content/global-platform/ platform
skin          global      classic/1.0 jar:classic.jar!/skin/classic/global/

Old-style contents.rdf manifests

Before the plaintext manifests were introduced (Firefox 1.1, Toolkit 1.8), RDF manifests named "contents.rdf" were used to register chrome. This format is deprecated; however, the mozilla suite (seamonkey) does not support the plaintext manifest format yet, so contents.rdf manifests are required for extensions that wish to maintain backwards compatibility with Firefox 1.0 or the suite.

Revision Source

<h3 name="What_is_Chrome.3F"> What is Chrome? </h3>
<p>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.
</p>
<h3 name="Chrome_Providers">Chrome Providers</h3>
<p>A supplier of chrome for a given window type (e.g., for the browser window) is called a chrome provider. 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.
</p><p>There are three basic types of chrome providers:
</p>
<h4 name="Content"> Content </h4>
<p>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. 
</p>
<h4 name="Locale"> Locale </h4>
<p>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. 
</p>
<h4 name="Skin"> Skin </h4>
<p>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. 
</p>
<h3 name="The_Chrome_Registry"> The Chrome Registry </h3>
<p>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.
</p><p>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.
</p><p>In order to inform the chrome registry of the available chrome, a text manifest is used: this manifest is "chrome.manifest" in the root of an extension, or theme, and chrome/*.manifest in a XULRunner application.
</p><p>The plaintext chrome manifests are a simple line-based format:
</p>
<pre class="eval">content packagename path/to/files &lt;flags&gt;
locale packagename localename path/to/files
skin packagename skinname path/to/files
</pre>
<p>XUL overlay
</p>
<pre class="eval">overlay chrome://file-to-overlay chrome://overlay-file
</pre>
<p>Style overlay
</p>
<pre class="eval">style chrome://file-to-style chrome://stylesheet-file
</pre>
<h4 name="Flags"> Flags </h4>
<p>Content packages can have flags added at the end of the registration. These flags mark special attributes of chrome.
</p>
<h5 name="Platform-specific_packages"> Platform-specific packages </h5>
<p>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.
</p><p>To indicate that a content package is platform-specific, add the "platform" modifier after the path; e.g.
</p>
<pre class="eval">content global-platform jar:toolkit.jar!/toolkit/content/global-platform/ platform
</pre>
<h5 name="xpcnativewrappers"> xpcnativewrappers </h5>
<p>Chrome packages can decide whether to use the xpcnativewrappers security mechanism to protect their code against malicious content access. See <a href="en/Safely_accessing_content_DOM_from_chrome">Safely accessing content DOM from chrome</a> for details. As of Firefox 1.1a1, this flag is *off* by default, and must be explicitly enabled by specifying xpcnativewrappers=yes. In the future, this flag will be enabled by default and extensions which need insecure access to the content objects will be required to specify xpcnativerwrappers=no.
</p>
<h4 name="Example_Chrome_Manifest"> Example Chrome Manifest </h4>
<pre class="eval">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/ xpcnativewrappers=yes
locale        pippki      en-US       jar:en-US.jar!/locale/en-US/pippki/
content       global-platform         jar:toolkit.jar!/content/global-platform/ platform
skin          global      classic/1.0 jar:classic.jar!/skin/classic/global/
</pre>
<h4 name="Old-style_contents.rdf_manifests"> Old-style contents.rdf manifests </h4>
<p>Before the plaintext manifests were introduced (Firefox 1.1, Toolkit 1.8), RDF manifests named "contents.rdf" were used to register chrome. This format is deprecated; however, the mozilla suite (seamonkey) does not support the plaintext manifest format yet, so contents.rdf manifests are required for extensions that wish to maintain backwards compatibility with Firefox 1.0 or the suite.
</p>
Revert to this revision