Chrome registration

馬桶裡有個 chrome?

Chrome 是一拖拉庫在文件 window 範圍之外 AP 視窗的 UI 元件。 管它 Toolbars 、 menu bars、progress bars 還是 window title bars 基本上都是 chrome 的一部份。

Chrome providers

基於某種 window type (例如針對 browser window) 提供 chrome 者稱為 chrome provider。所有的 provider 同心協力針對特定的 window 提供整套的 chrome，從工具列上的圖案到文字或內容描述檔，以及 window 本身的外觀。

以下是三種基本的 chrome provider ：

Content

視窗描述主要是來自於 content provider，格式可以是任何一種 Mozilla 看得懂的類型。通常會是個  XUL file，因為它本來就是專門設計來描述 window 和 dialog 的。用來定義 UI 的 JavaScript 檔也會跟在這包，多數的 XBL binding files 也是。

Locale

多語系的應用程式會將語系資訊交給 locale providers。醬子譯者就可以翻譯並插進一個另外的 chrome package 而不去更動其它的程式。Java-style properties 檔和 DTD 檔是兩種主要的多語系檔案類型。

Skin

Skin provider 就負責 chrome 整套外觀的描述檔，通常是 CSS 和圖形。

Chrome 登錄 (chrome registry)

Gecko runtime 會保持一份稱為 chrome registry 的記錄，用來對登錄 chrome package 名稱和實際檔案路徑。

Chrome registry 可以設定並且會保存；且有賴於 xpinstall 和 extension manager，這樣 user 就可以很多套 chrome provider 然後選擇喜歡的語系和外觀。

XULRunner application、主題布景或附加元件要讓 chrome registry 知道有這麼一個 chrome，那就要在自己的根目錄下放一個 純文字格式的 manifest，也就是 `chrome.manifest`。

這個純文字的 manifests 是簡單的逐行格式，會被一行一行地解析。 chrome registry 看懂一行就處理一行，看不懂就跳過；當然，有問題的會 log 在 console 中。

locale packagename localename path/to/files
skin packagename skinname path/to/files

Manifest 指令

comments

如果一行的開頭是 '#' 那這整行就變成註解。

# this line is a comment - you can put whatever you want here

manifest

manifest subdirectory/foo.manifest [flags]

這行會載入另一份 manifest 檔。這在拆分元件、chrome 登錄項或是各平台相依登錄資料時尤其有用。

binary-component

binary-component components/mycomponent.dll [flags]

叫 Mozilla 登錄並應用 binary component，由於 binary components 為 ABI-specific，應與 abi flag 並用。 在 Firefox 4 之前 ，components 資料夾裡的檔案會自動被登錄。

interfaces

interfaces component/mycomponent.xpt [flags]

叫 Mozilla 從經由 XPIDL 產生的 typelib 檔載入 interface 資訊。在 Firefox 4 之前，components 資料夾裡的檔案會自動被登錄。

component

component {00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags]

告訴 Mozilla 一個由 XPCOM 元件以 JavaScript (或是其它可接受的 scripting language) 實作之元件的 CID。ClassID {0000 ...} 一定要和該元件所實現的 ClassID 相同。可利用程式或線上 UUID 產生器產生唯一的 ClassID。

contract

contract @foobar/mycontract;1 {00000000-0000-0000-0000-000000000000} [flags]

將特定實作的 contract ID (一個語意化字串) 對應到 ClassID。通常 contract ID 就和它頂頭所列的 component entry 一組。
 

category

category category entry-name value [flags]

登錄在 category manager ，至於項目的格式和用意就要看它是哪個 category 了。

content

下面這行登錄一個 content package ：

content packagename uri/to/files/ [flags]

這會將 package 登錄在一個像 `chrome://packagename/content/..` 的位置，也就是之後它被存取的位置。這個 URI 可以是絕對位置或是相對於 manifest file 的位置，但要注意結尾的 '/' 不可省略。

locale

下面這行登錄一個 locale package ：

locale packagename localename uri/to/files/ [flags]

這會將 locale package 登錄在解析 `chrome://packagename/locale/..` 所用的位置。 localename 通常直接用語系名稱像是 "zh" 或有時候用 語系-地區 像 "zh-TW"。如果同一 package 有多個語系 chrome registry 會根據使用者偏好中的設定值選擇最接近的語系。

skin

下面這行登錄一個 skin package ：

skin packagename skinname uri/to/files/ [flags]

這會將 skin package 登錄在 chrome://packagename/skin/.. ， skinname is 是用來識別所安裝 skin 的一個非透明化字串。同樣地，若同一 package 登記了多個 skin ， chrome registry 會根據使用者偏好中的設定值選擇最合適的。

overlay

XUL overlay 以下列語法登錄：

overlay chrome://URI-to-be-overlaid chrome://overlay-URI [flags]

style

Style overlay (套用在chrome page上的自訂 CSS) 以下列語法登錄：

style chrome://URI-to-style chrome://stylesheet-URI [flags]

override

chrome 登錄 manifest 允許 override 指令以便讓某些 extension 或其它嵌入物件可以改寫 XULRunner 或 AP 預設的 chrome file 設定。

override chrome://package/type/original-uri.whatever new-resolved-URI [flags]

注意：override 路徑不會遞迴 (所以將 chrome://foo/content/bar/ override 為 file:///home/john/blah/ 之後，其行為通常不會是預期的那樣)。而且 override 之後路徑是相對於被重寫掉的路徑而不是用來重寫的路徑 (從 CSS 的角度來說，這搞不好是個偏門也搞不好使人抓狂) 。

resource

在 extension 和 AP 中使用 Components.utils.import 來載入 JavaScript code modules 時，建立 resource protocol 別名 (aliases) 有時是必須的。請使用 resource 指令來建立別名：

resource aliasname uri/to/files/ [flags]

這會將目的路徑對映到 resource://<aliasname>/.. 。

Manifest 旗號

Manifest 指令行允許多個以空白分隔的旗號附加於行尾。這些旗號將會設定 package 中 chrome 的特殊屬性，或限制這些指令行本身於什麼條件下作用。

application

Extension 可以安裝於多個應用程式，而有些 chrome registration 可能只需作用於特定的應用程式。以下旗號

application=app-ID

代表這個指令只應在 extension 安裝於符合 app-ID 的應用程式時作用。同一行可以指定多個應用程式，此時只要其中一項符合即會作用。

以下示範如何為多個應用程是分別指定 overlay ：

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 [email protected]

appversion

Extension 可以安裝於同一應用程式的多個不同版本，而有些 chrome registration 可能只需作用於特定的版本。以下旗號

appversion=version
appversion<version
appversion<=version
appversion>version
appversion>=version

代表這個指令只應在 extension 安裝於符合特定版本的應用程式時作用。同一行可以指定多個 appversion ，此時只要其中一項符合即會作用。版本字串應遵循 Toolkit version format 。

platformversion

當附加元件尤其是 binary components支援一種以上的應用程式時，若能指定所相容的 Gecko 版本將為其帶來更多的方便性。若某些 chrome registration 只作用於定特定 Gecko 版本，以下旗號

platformversion=version
platformversion<version
platformversion<=version
platformversion>version
platformversion>=version

代表這個指令只應在 extension 安裝於符合特定 Gecko 版本的應用程式時作用。同一行可以指定多個 platformversion，此時只要其中一項符合即會作用。

contentaccessible

Chrome resources 已不能被非信任來源內容中的 <img>、<script> 及其他包含或添加的 elements 所參照。 這個限制不僅適用於非信任來源中所定義的 elements ， 同時也適用於受信任的附加元件中所定義的 elements。若參照需要明確地被允許，請將 contentaccessible 旗號設定為 yes 來達到如舊版 Firefox 中的行為。 See bug 4369

contentaccessible 只能用於 content package ，言下之意，它不會被 locale 或 skin registration 所識別。好在於 content package 所對應到的 locale 和 skin packages 對 content 而言是可見的。

注意：由於舊版的 Firefox 根本看不懂 contentaccessible flag ， 若要讓附加元件同時支援 Firefox 3 及古董版的話就得來個倒退嚕，您倒是看看：

content packagename chrome/path/
content packagename chrome/path/ contentaccessible=yes

os

Extensions (or themes) may offer different features depending on the operating system on which Firefox is running. The value is compared to the value of OS_TARGET for the platform.

os=WINNT
os=Darwin

See OS_TARGET for a more complete list of os names. The os name is case insensitive.

osversion

An extension or theme may need to operate differently depending on which version of an operating system is running. For example, a theme may wish to adopt a different look on Mac OS X 10.5 than 10.4:

osversion>=10.5

abi

If a component is only compatible with a particular ABI, it can specify which ABI/OS by using this directive. The value is taken from the nsIXULRuntime OS and XPCOMABI values (concatenated with an underscore). For example:

binary-component component/myLib.dll abi=WINNT_x86-MSVC 
binary-component component/myLib.so abi=Linux_x86-gcc3 

See XPCOM ABI for more details.

platform (Platform-specific packages)

Some packages are marked with a special flag indicating that they are platform specific. Some parts of content, skin, and locales may be different based on the platform being run. These packages contain three different sets of files, for Windows and OS/2, Macintosh, and Unix-like platforms. For example, the order of the "OK" and "Cancel" buttons in a dialog is different, as well as the names of some items.

The "platform" modifier is only parsed for content registration; it is not recognized for locale or skin registration. However, it applies to content, locale, and skin parts of the package, when specified.

To indicate that a package is platform-specific, add the "platform" modifier to the "content" line after the path, for example:

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

Once that is specified in your manifest you then ensure that under the directory global-platform are subdirectories win (Windows/OS2), mac (OS9/OSX), or unix (Everything Else). Anything residing outside of these subdirectories will be ignored.

xpcnativewrappers

Chrome packages can decide whether to use the XPCNativeWrapper security mechanism to automatically protect their code against malicious content that they might access. See Safely accessing content DOM from chrome for details.

This flag is enabled by default since Firefox 1.5. Disabling it manually was possible by specifying xpcnativewrappers=no until Firefox 4.

The xpcnativewrappers flag applies only to content packages; it is not recognized for locale or skin registration.

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/
# Firefox-only
overlay chrome://browser/content/pageInfo.xul           chrome://pippki/content/PageInfoOverlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384}
# SeaMonkey-only
overlay chrome://navigator/content/pageInfo.xul         chrome://pippki/content/PageInfoOverlay.xul application={92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}
overlay chrome://communicator/content/pref/preftree.xul chrome://pippki/content/PrefOverlay.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
skin          global      classic/1.0 jar:classic.jar!/skin/classic/global/
override chrome://global/content/netError.xhtml jar:embedder.jar!/global/content/netError.xhtml
content       inspector               jar:inspector.jar!/content/inspector/

Instructions supported in bootstrapped add-ons

The following instructions are supported in Bootstrapped extensions:

• manifest
• content
• locale
• skin
• override

Debugging a chrome manifest file

The Chrome List extension (for Firefox 3.6 and older) shows all registered chrome. This is very helpful when trying to write a chrome.manifest file as you can inspect where the files are being mapped from (jar files, local directory, etc.)

Old-style contents.rdf manifests

Before the plaintext manifests were introduced (which happened in Firefox 1.5, Toolkit 1.8), RDF manifests named "contents.rdf" were used to register chrome. This format is deprecated; however, SeaMonkey versions before version 2 do 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.

Official references for Toolkit API

Official References. Do not add to this list without contacting Benjamin Smedberg. Note that this page is included from the pages listed below. So: Don't Add Breadcrumbs!

• Structure of an Installable Bundle: describes the common structure of installable bundles, including extensions, themes, and XULRunner applications
• Extension Packaging: specific information about how to package extensions
• Theme Packaging: specific information about how to package themes
• Multiple-item Extension Packaging: specific information about multiple-item extension XPIs
• XUL Application Packaging: specific information about how to package XULRunner applications
• Chrome Registration