Chrome registration

Что такое chrome?

Chrome — это набор всех элементов UI в окне приложения, за исключением самого контента web-страницы. Панели инструментов, строки меню, индикаторы загрузки и панели заголовков окон — все это примеры элементов, которые обычно являются частью chrome.

Mozilla находит и считывает корневой chrome.manifest файл в поисках расширений и тем оформления.

Chrome-провайдеры

Источник chrome для определенного типа окон (например, для окна браузера) называется chrome-провайдером (англ. provider — поставщик). Провайдеры, или поставщики, работают совместно, чтобы обеспечить полный набор элементов chrome для каждого конкретного окна, начиная от иконок на панелях инструментов, заканчивая файлами описания текста, контента и внешнего вида окна как такового.

Существует три основных вида ресурсов chrome:

Content

Главный исходный файл для описания окна исходит от провайдера content, он может быть любого типа, который сможеть обработать Mozilla. Скорее всего это будет XUL-файл, поскольку XUL спроектирован для описания содержимого окон и диалогов. JavaScript файлы, описывающие UI, также приведены в пакетах провайдера content, равно как и большинство XBL файлов сборки.

Locale

Локализуемые приложения содержат все переводы и связанную с локализацией информацию в провайдере locale. Такой подход позволяет переводчикам переводить только сами chrome-пакеты, не затрагивая основной исходный код. Два основных типа файлов локализации: DTD файлы и Java-подобные файлы свойств.

Skin

Провайдер skin отвечает за предоставление полного набора файлов, описывающих внешний вид chrome. Обычно это CSS файлы и изображения.

Реестр chrome

Среда Gecko предоставляет сервис, известный как реестр chrome. Этот сервис обеспечивает преобразование имен из chrome-пакетов в физическое расположение этих пакетов на диске.

Реестр chrome настраиваем и имеет строгую структуру, поэтому пользователь может устанавливать сторонние провайдеры chrome, и, таким образом, изменять внешний вид и локализацию. Это делается при помощи XPInstall и менеджера расширений.

Для того, чтобы сообщить реестру о новом доступном chrome, используется текстовый манифест: файл chrome.manifest в корне расширения, темы, или приложения XULRunner.

Текстовый манифест использует простую строчную разметку: каждая строка парсится отдельно. Если строка определяется реестром как валидная, то он выполняет действие или команду, описываемые этой строкой. Иначе строка игнорируется, а в консоль выводится сообщение об ошибке.

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

Инструкции в манифесте

Комментарии

Комментарием считается любая строчка, начинающаяся с символа решётки ('#'). Всё написанное в комментарии игнорируется.

# эта строчка - комментарий. здесь можно писать что угодно

manifest

manifest subdirectory/foo.manifest [flags]

Эта инструкция загрузит вспомогательный манифест. Это может быть полезно для разделения компонента и инструкции регистрации chrome, или разделения регистрационных данных, зависящих от платформы.

binary-component

binary-component components/mycomponent.dll [flags]

Даёт Mozilla указание к регистрации и использованию бинарного компонента. Эта инструкция должны комбинироваться с флагом abi (двоичного интерфейса приложений), так как бинарные компоненты зависят от ABI. Вплоть до Firefox 4 файлы в директориях компонентов регистрировались автоматически.

interfaces

interfaces component/mycomponent.xpt [flags]

Даёт указание загрузить информацию об интерфейсе из typelib-файла, созданного XPIDL.

Instructs Mozilla to load interface information from a typelib file produced by XPIDL. Вплоть до Firefox 4 файлы в директориях компонентов регистрировались автоматически.

component

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

Даёт Mozilla CID компонента, реализованного компонентом XPCOM на JavaScript или любом другом поддерживаемом языке. ClassID {0000...} должен совпадать с ClassID компонента. Для генерации уникального ClassID, можно возпользоваться любым UUID генератором.

contract

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

Сопостовляет читабельный ID договора с ClassID для точной реализации. Обычно ID договора работает в паре с объявлением компонента, указанным непосредственно перед записью contract.

category

category category entry-name value [flags]

Регистрирует запись в менеджер категорий. Особенности формата и значения записей категорий зависят от категории.

content

Пакет content регистрируется строчкой

content packagename uri/to/files/ [flags]

Это нужно для объявления пути, используемого при разрешении URI типа chrome://packagename/content/.... Этот URI может быть как абсолютным, так и относительным по отношению к манифеста. Внимание: он должен заканчиваться слэшем ('/').

locale

Регистрация пакета локализации происходит при помощи строки

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

Такая инструкция зарегистрирует пакет локализации при разрешении URI типа chrome://packagename/locale/... . Обычно localename это текстовой идентификатор страны "ru" или языка-страны "ru-RU". Если для пакета зарегистрировано несколько локализаций, реестр выберет наиболее подходящий для пользователя, учитывая пользовательские настройки языка.

skin

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

Такая инструкция зарегистрирует пакет оформления при разрешении URI типа chrome://packagename/skin/... . skinname это строка, идентифицирующая установленный скин. Если для пакета зарегистрировано несколько оформлений, реестр выберет наиболее подходящий для пользователя, учитывая пользовательские настройки.

overlay

Оверлеи XUL регистрируются следующим образом:

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

style

Оверлеи стилей (особый CSS-файл, применяющийся к странице chrome) регистрируются следующим образом:

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:

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

resource

Aliases can be created using the resource instruction:

resource aliasname uri/to/files/ [flags]

This will create a mapping for resource://<aliasname>/ URIs to the path given.

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

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

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

appversion=version
appversion<version
appversion<=version
appversion>version
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

platformversion=version
platformversion<version
platformversion<=version
platformversion>version
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 <img>, <script>, or other elements contained in, or added to, content that was loaded from an untrusted source. This restriction applies to both elements defined by the untrusted source and to elements added by trusted extensions. If such references need to be explicitly allowed, set the contentaccessible flag to yes to obtain the behavior found in older versions of Firefox. See bug 436989.

The contentaccessible flag applies only to content packages: it is not recognized for locale or skin registration. However, the matching locale and skin packages will also be exposed to content.

n.b.: Because older versions of Firefox do not understand the contentaccessible flag, any extension designed to work with both Firefox 3 and older versions of Firefox will need to provide a fallback. For example:

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