7 `Chrome` is the set of user interface elements of the
8 application window that are outside the window's content area. Toolbars,
9 menu bars, progress bars, and window title bars are all examples of
10 elements that are typically part of the chrome.
12 ``chrome.manifest`` files are used to register XPCOM components and sources for the chrome protocol.
13 Every application supplies a root ``chrome.manifest`` file that Mozilla reads on startup.
18 A supplier of chrome for a given window type (e.g., for the browser
19 window) is called a chrome provider. The providers work together to
20 supply a complete set of chrome for a particular window, from the images
21 on the toolbar buttons to the files that describe the text, content, and
22 appearance of the window itself.
24 There are three basic types of chrome providers:
27 The main source file for a window description comes from the content
28 provider, and it can be any file type viewable from within Mozilla.
29 It will typically be a XUL file, since XUL is designed for describing
30 the contents of windows and dialogs. The JavaScript files that define
31 the user interface are also contained within the content packages.
34 Localizable applications keep all their localized information in
35 locale providers and Fluent FTL files, which are handled separately.
36 This allows translators to plug in a different
37 chrome package to translate an application without altering the rest
38 of the source code. In a chrome provider, localizable files are mostly
39 Java-style properties files.
41 A skin provider is responsible for providing a complete set of files
42 that describe the visual appearance of the chrome. Typically a skin
43 provider will provide CSS files and
49 The Gecko runtime maintains a service known as the chrome registry that
50 provides mappings from chrome package names to the physical location of
51 chrome packages on disk.
53 This chrome registry is configurable and persistent, and thus a user can
54 install different chrome providers, and select a preferred skin and
55 locale. This is accomplished through xpinstall and the extension
58 In order to inform the chrome registry of the available chrome, a text
59 manifest is used: this manifest is "chrome.manifest" in the root of an
60 extension, or theme, or XULRunner application.
62 The plaintext chrome manifests are in a simple line-based format. Each
63 line is parsed individually; if the line is parsable the chrome registry
64 takes the action identified by that line, otherwise the chrome registry
65 ignores that line (and prints a warning message in the runtime error
70 locale packagename localename path/to/files
71 skin packagename skinname path/to/files
75 The characters @ # ; : ? / are not allowed in the
86 # this line is a comment - you can put here whatever you want
88 A line is a comment if it begins with the character '#'. Any following
89 character in the same line is ignored.
96 manifest subdirectory/foo.manifest [flags]
98 This will load a secondary manifest file. This can be useful for
99 separating component and chrome registration instructions, or separate
100 platform-specific registration data.
107 component {00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags]
109 Informs Mozilla about a component CID implemented by an XPCOM component
110 implemented in JavaScript (or another scripting language, if
111 applicable). The ClassID {0000...} must match the ClassID implemented by
112 the component. To generate a unique ClassID, use a UUID generator
120 contract @foobar/mycontract;1 {00000000-0000-0000-0000-000000000000} [flags]
122 Maps a contract ID (a readable string) to the ClassID for a specific
123 implementation. Typically a contract ID will be paired with a component
124 entry immediately preceding.
131 category category entry-name value [flags]
133 Registers an entry in the `category manager`. The
134 specific format and meaning of category entries depend on the category.
139 A content package is registered with the line:
143 content packagename uri/to/files/ [flags]
145 This will register a location to use when resolving the URI
146 ``chrome://packagename/content/...``. The URI may be absolute or
147 relative to the location of the manifest file. Note: it must end with a
153 A locale package is registered with the line:
157 locale packagename localename uri/to/files/ [flags]
159 This will register a locale package when resolving the URI
160 chrome://*packagename*/locale/... . The *localename* is usually a plain
161 language identifier "en" or a language-country identifier "en-US". If
162 more than one locale is registered for a package, the chrome registry
163 will select the best-fit locale using the user's preferences.
168 A skin package is registered with the line:
172 skin packagename skinname uri/to/files/ [flags]
174 This will register a skin package when resolving the URI
175 chrome://packagename/skin/... . The *skinname* is an opaque string
176 identifying an installed skin. If more than one skin is registered for a
177 package, the chrome registry will select the best-fit skin using the
183 Style overlays (custom CSS which will be applied to a chrome page) are
184 registered with the following syntax:
188 style chrome://URI-to-style chrome://stylesheet-URI [flags]
193 In some cases an extension or embedder may wish to override a chrome
194 file provided by the application or XULRunner. In order to allow for
195 this, the chrome registration manifest allows for "override"
200 override chrome://package/type/original-uri.whatever new-resolved-URI [flags]
202 Note: overrides are not recursive (so overriding
203 chrome://foo/content/bar/ with file:///home/john/blah/ will not usually
204 do what you want or expect it to do). Also, the path inside overridden
205 files is relative to the overridden path, not the original one (this can
206 be annoying and/or useful in CSS files, for example).
208 .. _chrome_manifest_resource:
213 Aliases can be created using the ``resource`` instruction:
217 resource aliasname uri/to/files/ [flags]
219 This will create a mapping for ``resource://<aliasname>/`` URIs to the
224 **Note:** There are no security restrictions preventing web content
225 from including content at resource: URIs, so take care what you make
231 Manifest lines can have multiple, space-delimited flags added at the end
232 of the registration line. These flags mark special attributes of chrome
233 in that package, or limit the conditions under which the line is used.
238 Extensions may install into multiple applications. There may be chrome
239 registration lines which only apply to one particular application. The
246 indicates that the instruction should only be applied if the extension
247 is installed into the application identified by *app-ID*. Multiple
248 application flags may be included on a single line, in which case the
249 line is applied if any of the flags match.
251 This example shows how a different overlay can be used for different
256 overlay chrome://browser/content/browser.xul chrome://myaddon/content/ffOverlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384}
257 overlay chrome://messenger/content/mailWindowOverlay.xul chrome://myaddon/content/tbOverlay.xul application={3550f703-e582-4d05-9a08-453d09bdfdc6}
258 overlay chrome://songbird/content/xul/layoutBaseOverlay.xul chrome://myaddon/content/sbOverlay.xul application=songbird@songbirdnest.com
263 Extensions may install into multiple versions of an application. There
264 may be chrome registration lines which only apply to a particular
265 application version. The flag
275 indicates that the instruction should only be applied if the extension
276 is installed into the application version identified. Multiple
277 ``appversion`` flags may be included on a single line, in which case the
278 line is applied if any of the flags match. The version string must
279 conform to the `Toolkit version format`.
284 When supporting more then one application, it is often more convenient
285 for an extension to specify which Gecko version it is compatible with.
286 This is particularly true for binary components. If there are chrome
287 registration lines which only apply to a particular Gecko version, the
292 platformversion=version
293 platformversion<version
294 platformversion<=version
295 platformversion>version
296 platformversion>=version
298 indicates that the instruction should only be applied if the extension
299 is installed into an application using the Gecko version identified.
300 Multiple ``platformversion`` flags may be included on a single line, in
301 which case the line is applied if any of the flags match.
306 Chrome resources can no longer be referenced from within <img>,
307 <script>, or other elements contained in, or added to, content that was
308 loaded from an untrusted source. This restriction applies to both
309 elements defined by the untrusted source and to elements added by
310 trusted extensions. If such references need to be explicitly allowed,
311 set the ``contentaccessible`` flag to ``yes`` to obtain the behavior
312 found in older versions of Firefox. See
313 `bug 436989 <https://bugzilla.mozilla.org/show_bug.cgi?id=436989>`__.
315 The ``contentaccessible`` flag applies only to content packages: it is
316 not recognized for locale or skin registration. However, the matching
317 locale and skin packages will also be exposed to content.
319 **n.b.:** Because older versions of Firefox do not understand the
320 ``contentaccessible`` flag, any extension designed to work with both
321 Firefox 3 and older versions of Firefox will need to provide a fallback.
326 content packagename chrome/path/
327 content packagename chrome/path/ contentaccessible=yes
332 Extensions (or themes) may offer different features depending on the
333 operating system on which Firefox is running. The value is compared to
334 the value of `OS_TARGET` for the platform.
344 An extension or theme may need to operate differently depending on which
345 version of an operating system is running. For example, a theme may wish
346 to adopt a different look on Mac OS X 10.5 than 10.4:
355 If a component is only compatible with a particular ABI, it can specify
356 which ABI/OS by using this directive. The value is taken from the
357 `nsIXULRuntime` OS and
358 XPCOMABI values (concatenated with an underscore). For example:
362 binary-component component/myLib.dll abi=WINNT_x86-MSVC
363 binary-component component/myLib.so abi=Linux_x86-gcc3
365 platform (Platform-specific packages)
366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
368 Some packages are marked with a special flag indicating that they are
369 platform specific. Some parts of content, skin, and locales may be
370 different based on the platform being run. These packages contain three
371 different sets of files, for Windows and OS/2, Macintosh, and Unix-like
372 platforms. For example, the order of the "OK" and "Cancel" buttons in a
373 dialog is different, as well as the names of some items.
375 The "platform" modifier is only parsed for content registration; it is
376 not recognized for locale or skin registration. However, it applies to
377 content, locale, and skin parts of the package, when specified.
382 In electrolysis registrations can be set to only apply in either the
383 main process or any content processes. The "process" flag selects
384 between these two. This can allow you to register different components
385 for the same contract ID or ensure a component can only be loaded in the
390 component {09543782-22b1-4a0b-ba07-9134365776ee} maincomponent.js process=main
391 component {98309951-ac89-4642-afea-7b2b6216bcef} contentcomponent.js process=content
396 In `multiprocess Firefox`, the
397 default is that a given chrome: URI will always be loaded into the
398 chrome process. If you set the "remoteenabled" flag, then the page will
399 be loaded in the same process as the ``browser`` that loaded it:
403 content packagename chrome/path/ remoteenabled=yes
408 In `multiprocess Firefox`, the
409 default is that a given chrome: URI will always be loaded into the
410 chrome process. If you set the "remoterequired" flag, then the page will
411 always be loaded into a child process:
415 content packagename chrome/path/ remoterequired=yes
417 Example chrome manifest
418 -----------------------
430 - browser/content/branding/
431 - contentaccessible=yes
434 - browser/content/browser/
435 - contentaccessible=yes
438 - chrome://global/content/license.html
439 - chrome://browser/content/license.html
442 - browser/res/payments/
446 - classic/1.0 browser/skin/classic/browser/
451 - en-US/locale/branding/
455 - en-US/locale/browser/
459 - en-US/locale/browser-region/