Chrome Registration ------------------- What is chrome? --------------- `Chrome` is the set of user interface elements of the application window that are outside the 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.manifest`` files are used to register XPCOM components and sources for the chrome protocol. Every application supplies a root ``chrome.manifest`` file that Mozilla reads on startup. 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, content, 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. Locale Localizable applications keep all their localized information in locale providers and Fluent FTL files, which are handled separately. This allows translators to plug in a different chrome package to translate an application without altering the rest of the source code. In a chrome provider, localizable files are mostly 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 manager. 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, or XULRunner application. The plaintext chrome manifests are in a simple line-based format. Each line is parsed individually; if the line is parsable the chrome registry takes the action identified by that line, otherwise the chrome registry ignores that line (and prints a warning message in the runtime error console). .. code:: text locale packagename localename path/to/files skin packagename skinname path/to/files .. note:: The characters @ # ; : ? / are not allowed in the packagename. Manifest instructions --------------------- comments ~~~~~~~~ .. code:: text # this line is a comment - you can put here whatever you want A line is a comment if it begins with the character '#'. Any following character in the same line is ignored. manifest ~~~~~~~~ :: manifest subdirectory/foo.manifest [flags] This will load a secondary manifest file. This can be useful for separating component and chrome registration instructions, or separate platform-specific registration data. component ~~~~~~~~~ :: component {00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags] Informs Mozilla about a component CID implemented by an XPCOM component implemented in JavaScript (or another scripting language, if applicable). The ClassID {0000...} must match the ClassID implemented by the component. To generate a unique ClassID, use a UUID generator program or site. contract ~~~~~~~~ :: contract @foobar/mycontract;1 {00000000-0000-0000-0000-000000000000} [flags] Maps a contract ID (a readable string) to the ClassID for a specific implementation. Typically a contract ID will be paired with a component entry immediately preceding. category ~~~~~~~~ :: category category entry-name value [flags] Registers an entry in the `category manager`. The specific format and meaning of category entries depend on the category. content ~~~~~~~ A content package is registered with the line: :: content packagename uri/to/files/ [flags] This will register a location to use when resolving the URI ``chrome://packagename/content/...``. The URI may be absolute or relative to the location of the manifest file. Note: it must end with a '/'. locale ~~~~~~ A locale package is registered with the line: .. code:: text locale packagename localename uri/to/files/ [flags] This will register a locale package when resolving the URI chrome://*packagename*/locale/... . The *localename* is usually a plain language identifier "en" or a language-country identifier "en-US". If more than one locale is registered for a package, the chrome registry will select the best-fit locale using the user's preferences. skin ~~~~ A skin package is registered with the line: .. code:: text skin packagename skinname uri/to/files/ [flags] This will register a skin package when resolving the URI chrome://packagename/skin/... . The *skinname* is an opaque string identifying an installed skin. If more than one skin is registered for a package, the chrome registry will select the best-fit skin using the user's preferences. style ~~~~~ Style overlays (custom CSS which will be applied to a chrome page) are registered with the following syntax: .. code:: text style chrome://URI-to-style chrome://stylesheet-URI [flags] override ~~~~~~~~ In some cases an extension or embedder may wish to override a chrome file provided by the application or XULRunner. In order to allow for this, the chrome registration manifest allows for "override" instructions: .. code:: text override chrome://package/type/original-uri.whatever new-resolved-URI [flags] Note: overrides are not recursive (so overriding chrome://foo/content/bar/ with file:///home/john/blah/ will not usually do what you want or expect it to do). Also, the path inside overridden files is relative to the overridden path, not the original one (this can be annoying and/or useful in CSS files, for example). .. _chrome_manifest_resource: resource ~~~~~~~~ Aliases can be created using the ``resource`` instruction: .. code:: text resource aliasname uri/to/files/ [flags] This will create a mapping for ``resource:///`` URIs to the path given. .. note:: **Note:** There are no security restrictions preventing web content from including content at resource: URIs, so take care what you make visible there. Manifest flags -------------- Manifest lines can have multiple, space-delimited flags added at the end of the registration line. These flags mark special attributes of chrome in that package, or limit the conditions under which the line is used. application ~~~~~~~~~~~ Extensions may install into multiple applications. There may be chrome registration lines which only apply to one particular application. The flag .. code:: text application=app-ID indicates that the instruction should only be applied if the extension is installed into the application identified by *app-ID*. Multiple application flags may be included on a single line, in which case the line is applied if any of the flags match. This example shows how a different overlay can be used for different applications: :: overlay chrome://browser/content/browser.xul chrome://myaddon/content/ffOverlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384} overlay chrome://messenger/content/mailWindowOverlay.xul chrome://myaddon/content/tbOverlay.xul application={3550f703-e582-4d05-9a08-453d09bdfdc6} overlay chrome://songbird/content/xul/layoutBaseOverlay.xul chrome://myaddon/content/sbOverlay.xul application=songbird@songbirdnest.com appversion ~~~~~~~~~~ Extensions may install into multiple versions of an application. There may be chrome registration lines which only apply to a particular application version. The flag .. code:: text appversion=version appversionversion appversion>=version indicates that the instruction should only be applied if the extension is installed into the application version identified. Multiple ``appversion`` flags may be included on a single line, in which case the line is applied if any of the flags match. The version string must conform to the `Toolkit version format`. platformversion ~~~~~~~~~~~~~~~ When supporting more then one application, it is often more convenient for an extension to specify which Gecko version it is compatible with. This is particularly true for binary components. If there are chrome registration lines which only apply to a particular Gecko version, the flag .. code:: text platformversion=version platformversionversion platformversion>=version indicates that the instruction should only be applied if the extension is installed into an application using the Gecko version identified. Multiple ``platformversion`` flags may be included on a single line, in which case the line is applied if any of the flags match. contentaccessible ~~~~~~~~~~~~~~~~~ Chrome resources can no longer be referenced from within ,