chrome-registration.rst (14002B)
1 Chrome Registration 2 ------------------- 3 4 What is chrome? 5 --------------- 6 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. 11 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. 14 15 Chrome providers 16 ---------------- 17 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. 23 24 There are three basic types of chrome providers: 25 26 Content 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. 32 33 Locale 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. 40 Skin 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 44 images. 45 46 The chrome registry 47 ------------------- 48 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. 52 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 56 manager. 57 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. 61 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 66 console). 67 68 .. code:: text 69 70 locale packagename localename path/to/files 71 skin packagename skinname path/to/files 72 73 .. note:: 74 75 The characters @ # ; : ? / are not allowed in the 76 packagename. 77 78 Manifest instructions 79 --------------------- 80 81 comments 82 ~~~~~~~~ 83 84 .. code:: text 85 86 # this line is a comment - you can put here whatever you want 87 88 A line is a comment if it begins with the character '#'. Any following 89 character in the same line is ignored. 90 91 manifest 92 ~~~~~~~~ 93 94 :: 95 96 manifest subdirectory/foo.manifest [flags] 97 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. 101 102 component 103 ~~~~~~~~~ 104 105 :: 106 107 component {00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags] 108 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 113 program or site. 114 115 contract 116 ~~~~~~~~ 117 118 :: 119 120 contract @foobar/mycontract;1 {00000000-0000-0000-0000-000000000000} [flags] 121 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. 125 126 category 127 ~~~~~~~~ 128 129 :: 130 131 category category entry-name value [flags] 132 133 Registers an entry in the `category manager`. The 134 specific format and meaning of category entries depend on the category. 135 136 content 137 ~~~~~~~ 138 139 A content package is registered with the line: 140 141 :: 142 143 content packagename uri/to/files/ [flags] 144 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 148 '/'. 149 150 locale 151 ~~~~~~ 152 153 A locale package is registered with the line: 154 155 .. code:: text 156 157 locale packagename localename uri/to/files/ [flags] 158 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. 164 165 skin 166 ~~~~ 167 168 A skin package is registered with the line: 169 170 .. code:: text 171 172 skin packagename skinname uri/to/files/ [flags] 173 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 178 user's preferences. 179 180 style 181 ~~~~~ 182 183 Style overlays (custom CSS which will be applied to a chrome page) are 184 registered with the following syntax: 185 186 .. code:: text 187 188 style chrome://URI-to-style chrome://stylesheet-URI [flags] 189 190 override 191 ~~~~~~~~ 192 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" 196 instructions: 197 198 .. code:: text 199 200 override chrome://package/type/original-uri.whatever new-resolved-URI [flags] 201 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). 207 208 .. _chrome_manifest_resource: 209 210 resource 211 ~~~~~~~~ 212 213 Aliases can be created using the ``resource`` instruction: 214 215 .. code:: text 216 217 resource aliasname uri/to/files/ [flags] 218 219 This will create a mapping for ``resource://<aliasname>/`` URIs to the 220 path given. 221 222 .. note:: 223 224 **Note:** There are no security restrictions preventing web content 225 from including content at resource: URIs, so take care what you make 226 visible there. 227 228 Manifest flags 229 -------------- 230 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. 234 235 application 236 ~~~~~~~~~~~ 237 238 Extensions may install into multiple applications. There may be chrome 239 registration lines which only apply to one particular application. The 240 flag 241 242 .. code:: text 243 244 application=app-ID 245 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. 250 251 This example shows how a different overlay can be used for different 252 applications: 253 254 :: 255 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 259 260 appversion 261 ~~~~~~~~~~ 262 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 266 267 .. code:: text 268 269 appversion=version 270 appversion<version 271 appversion<=version 272 appversion>version 273 appversion>=version 274 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`. 280 281 platformversion 282 ~~~~~~~~~~~~~~~ 283 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 288 flag 289 290 .. code:: text 291 292 platformversion=version 293 platformversion<version 294 platformversion<=version 295 platformversion>version 296 platformversion>=version 297 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. 302 303 contentaccessible 304 ~~~~~~~~~~~~~~~~~ 305 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>`__. 314 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. 318 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. 322 For example: 323 324 :: 325 326 content packagename chrome/path/ 327 content packagename chrome/path/ contentaccessible=yes 328 329 os 330 ~~ 331 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. 335 336 .. code:: text 337 338 os=WINNT 339 os=Darwin 340 341 osversion 342 ~~~~~~~~~ 343 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: 347 348 .. code:: text 349 350 osversion>=10.5 351 352 abi 353 ~~~ 354 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: 359 360 :: 361 362 binary-component component/myLib.dll abi=WINNT_x86-MSVC 363 binary-component component/myLib.so abi=Linux_x86-gcc3 364 365 platform (Platform-specific packages) 366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 367 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. 374 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. 378 379 process 380 ~~~~~~~ 381 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 386 main process. 387 388 :: 389 390 component {09543782-22b1-4a0b-ba07-9134365776ee} maincomponent.js process=main 391 component {98309951-ac89-4642-afea-7b2b6216bcef} contentcomponent.js process=content 392 393 remoteenabled 394 ~~~~~~~~~~~~~ 395 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: 400 401 :: 402 403 content packagename chrome/path/ remoteenabled=yes 404 405 remoterequired 406 ~~~~~~~~~~~~~~ 407 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: 412 413 :: 414 415 content packagename chrome/path/ remoterequired=yes 416 417 Example chrome manifest 418 ----------------------- 419 420 .. list-table:: 421 :widths: 20 20 20 20 422 423 424 * - type 425 - engine 426 - language 427 - url 428 * - content 429 - branding 430 - browser/content/branding/ 431 - contentaccessible=yes 432 * - content 433 - browser 434 - browser/content/browser/ 435 - contentaccessible=yes 436 * - override 437 - 438 - chrome://global/content/license.html 439 - chrome://browser/content/license.html 440 * - resource 441 - payments 442 - browser/res/payments/ 443 - 444 * - skin 445 - browser 446 - classic/1.0 browser/skin/classic/browser/ 447 - 448 * - locale 449 - branding 450 - en-US 451 - en-US/locale/branding/ 452 * - locale 453 - browser 454 - en-US 455 - en-US/locale/browser/ 456 * - locale 457 - browser-region 458 - en-US 459 - en-US/locale/browser-region/