User:Jorge.villalobos/AddonPackaging/Manifest
Contents
The Manifest File
The manifest file for the new packaging system is defined using a subset of HTML. The file name is manifest.html, and must reside in the root of the package file.
The existence of this file determines whether the new packaging system is applied or not. For backward compatibility, package files can contain both the new and old manifest files.
Layout
The basic layout of a manifest file is like so:
<?xml version="1.0"?>
<!DOCTYPE html>
<html>
<body>
<!-- properties -->
</body>
</html>
Some properties are required, some are optional.
Single value properties are defined using the paragraph tag (<p>), and multi-valued properties are defined using the ordered list tags (<ol>, <li>). The id attribute determines the property each value corresponds to, for single-valued properties. The class attribute is used for properties that can be repeated in the same manifest, like target applications.
Property ordering is irrelevant. Any HTML content that doesn't correspond to properties in the spec will be ignored.
Required properties
Your manifest must specify these properties correctly otherwise your addon may not install.
id
The add-on id, which is a:
- A string formatted like so: extensionname@organization.tld. (Recommended)
- A GUID.
Example:
<p id="id">packaging-example@wiki.mozilla.org</p>
name
The name of the add-on; intended for display in the UI. It can be optionally localized as described below, but a default name should always be defined. The name cannot be empty.
Example:
<p id="name">Add-on Packaging Spec Example</p>
version
A version string identifying the version of the addon being supplied. It must conform to the rules of the Toolkit version format.
Example:
<p id="version">1.0</p>
type
An integer value representing the type of add-on.
- 2 Extensions
- 4 Themes
- 8 Locale
- 32 Multiple Item Package
Example:
<p id="type">2</p>
chrome-domains
The chrome domain determines how chrome and resource URLs are resolved for the add-on.
Example:
<p id="chrome-domains">packagingspec</p>
For the above example, the add-on would be registering itself for URLs starting with chrome://packagingspec and resource://packagingspec.
See the expanded version of chrome-domains below, in case more fine-grained chrome manipulation is required.
target-applications
Specifies the applications targeted by this addon.
The add-on will work with the application identified by the application-id property specified, from the minimum version min-version up to and including the maximum version max-version (for a comprehensive list of application IDs and valid min/max versions for them see valid application versions).
These version strings are formatted in the same fashion as the version property and will be compared to the application version; this allows the extension author to specify which versions of the application an add-on has been tested with.
The manifest must specify at least one target application.
Example:
<ol id="target-applications">
<!-- Firefox. -->
<li>
<p class="application-id">{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</p>
<p class="min-version">3.6</p>
<p class="max-version">4.0.*</p>
</li>
<!-- SeaMonkey. -->
<li>
<p class="application-id">{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}</p>
<p class="min-version">2.1</p>
<p class="max-version">2.1.*</p>
</li>
</ol>
Since it's possible to have multiple target applications, the properties are specified using class instead of id.
Example minimal manifest
This is an example manifest that includes all required properties:
<?xml version="1.0"?>
<!DOCTYPE html>
<html>
<body>
<p id="id">packaging-example@wiki.mozilla.org</p>
<p id="name">Add-on Packaging Spec Example</p>
<p id="version">1.0</p>
<p id="chrome-domain">packagingspec</p>
<!-- Extension. -->
<p id="type">2</p>
<ol id="target-applications">
<!-- Firefox. -->
<li>
<p class="application-id">{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</p>
<p class="min-version">3.6</p>
<p class="max-version">4.0.*</p>
</li>
</ol>
</body>
</html>
Optional properties
description
A short description of the add-on - intended for display in the user interface. This description should fit on one short line of text.
Example:
<p id="description">An example for the new add-on packaging specification.</p>
creator
The name of the creator/principal developer - intended for display in the user interface. This is a single value.
Example:
<p id="creator">Jorge Villalobos</p>
developers
The name(s) of co-developers. You may specify multiple developers.
Example:
<ol id="developers"> <li>John Doe</li> <li>Jane Doe</li> </ol>
translators
The name(s) of translators. You may specify multiple translators.
Example:
<ol id="translators"> <li>John Doe</li> <li>Jane Doe</li> </ol>
contributors
The name(s) of additional contributors. You may specify more than one contributor.
Example:
<ol id="contributors"> <li>John Doe</li> <li>Jane Doe</li> </ol>
homepage-url
A link to the addon's home page - intended for display in the user interface.
Example:
<p id="homepage-url">https://wiki.mozilla.org/User:Jorge.villalobos/AddonPackaging</p>
update-url
A link to a custom Update Manifest file that specifies available updates to the addon. The format of this URL follows the same rules and have the same options as the previous manifest format. The file it links to, however, can use the previous format or a new format. See the section on the update file for more information.
Example:
<p id="update-url">http://www.example.com/update.php?id=%ITEM_ID%&version=%ITEM_VERSION%</p>
update-key
To ensure the security of update data that is retrieved over plain http you must use a digital signature to verify the contents of the data. In order to do so you must include the public part of the cryptographic key in an update-key property. This can be generated using the McCoy tool. Any line breaks and whitespace as part of this entry are ignored.
Example:
<p id="update-key"> MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK426erD/H3XtsjvaB5+PJqbhj Zc9EDI5OCJS8R3FIObJ9ZHJK1TXeaE7JWqt9WUmBWTEFvwS+FI9vWu8058N9CHhD NyeP6i4LuUYjTURnn7Yw/IgzyIJ2oKsYa32RuxAyteqAWqPT/J63wBixIeCxmysf awB/zH4KaPiY3vnrzQIDAQAB </p>
options-url
The chrome:// URL of the extension's preferences dialog. This is only useful to extensions. If this property is specified, when the extension is selected in the Add-ons Manager, the Options button is enabled and will open this dialog.
Example:
<p id="options-url">chrome://packagingspec/content/options.xul</p>
about-url
The chrome:// URL of the extension's About dialog. This is only useful to extensions. If this property is specified, when the extension is selected in the Add-ons Manager, the About option is enabled and will open this dialog.
Example:
<p id="about-url">chrome://packagingspec/content/about.xul</p>
localized-url
The chrome:// URL of the extension's localized metadata file. The URL must point to a properties file, and the property name in the locale file must match the id of the manifest property. Numerical suffixes are used for multi-values properties.
Example:
<p id="localized-url">chrome://packagingspec/locale/manifest.properties</p>
Properties file:
name = Ejemplo de empaquetamiento de complementos description = Este es un ejemplo translator.1 = Jorge translator.2 = Somebody else
Only the following properties can be localized: name, description, creator, developers, translators and contributors.
target-platforms
A set of strings specifying the platforms that the add-on supports. It contains either the value of OS_TARGET alone or combined with TARGET_XPCOM_ABI, separated by an underscore (_). If any value matches the application's build parameters, it will be installed; if not, the user will get an appropriate error message.
There's more information in the previous manifest format documentation.
Example:
<ol id="target-platforms"> <li>WINNT_x86-msv</li> <li>Linux</li> <li>Darwin_ppc-gcc3</li> <li>SunOS_sparc-sunc</li> </ol>
requires
Very similar to target-applications, except that the id is not an application id but an add-on id. If the add-on specified by the addon-id is not installed or has an incompatible version, the extension manager will disable the installed add-on and show the message "Requires additional items". Multiple dependencies can be declared.
Example:
<ol id="requires">
<!-- Lightning -->
<li>
<p class="addon-id">{e2fda1a4-762b-4020-b5ad-a41df1933103}</p>
<p class="min-version">0.9</p>
<p class="max-version">1.1.*</p>
</li>
</ol>
locations
Makes it possible to define different locations to files and folders that are normally located in a fixed place.
Example:
<ol id="locations">
<li>
<p class="location-name">defaultPrefs</p>
<p class="location">prefs/myPrefs.js</p>
</li>
<li>
<p class="location-name">icon</p>
<p class="location">images/icon.png</p>
</li>
<li>
<p class="location-name">components</p>
<p class="location">code/myComponents/</p>
</li>
<li>
<p class="location-name">platform</p>
<p class="location">code/platform/</p>
</li>
</ol>
Only the locations specified in the example can be changed. Changing the icon location may cause it not to appear during installation or while the add-on is disabled.
Optional chrome properties
overlays
A list of XUL overlays the add-on applies.
Examples:
<ol id="overlays">
<li>
<p class="source">chrome://packagingspec/content/overlay.xul</p>
<p class="target">chrome://browser/content/browser.xul</p>
</li>
</ol><ol id="overlays">
<li>
<p class="source">chrome://packagingspec/content/overlay.xul</p>
<p class="target">chrome://browser/content/browser.xul</p>
<p class="flags">appversion<=3.7 os=WINNT</p>
</li>
</ol>
See the manifest flags section at MDC for more information on the supported flags. They can be applied to any chrome property.
styles
A list of XUL style overlays the add-on applies.
Examples:
<ol id="styles">
<li>
<p class="source">chrome://packagingspec/skin/toolbar.css</p>
<p class="target">chrome://global/content/customizeToolbar.xul</p>
</li>
</ol>
overrides
A list of XUL window overrides the add-on applies.
Examples:
<ol id="overrides">
<li>
<p class="source">chrome://packagingspec/content/newCustomizeToolbar.xul</p>
<p class="target">chrome://global/content/customizeToolbar.xul</p>
</li>
</ol>
chrome-domains (Expanded)
An expanded version of chrome-domain, that can include multiple domains, as well as specific locations for content, skin, locale and resource packages.
Examples:
<ol id="chrome-domains">
<li>
<p class="domain">packagingspec</p>
<ol class="content">
<li>
<p class="location">chrome/packagingspec/content/</p>
</li>
</ol>
<ol class="skin">
<li>
<p class="location">chrome/packagingspec/skin/</p>
<p class="skin-name">classic/1.0</p>
</li>
</ol>
<ol class="locale">
<li>
<p class="location">chrome/packagingspec/locale/en-US/</p>
<p class="locale-name">en-US</p>
</li>
</ol>
<ol class="resources">
<li>
<p class="location">modules/</p>
<!-- <p class="disabled">true</p> -->
</li>
</ol>
</li>
</ol>
The disabled property for resources is necessary for add-ons that don't want to publish their presence to websites. It can be included without having to specify a location for resource files. If content, skin or locale are included, location is required, and locale-name is also required for locale items. The skin-name property is optional.
Visualizing manifests
Manifest files can include CSS to make their visualization easier. The CSS can be included just like in HTML:
<head> <link rel="stylesheet" type="text/css" href="manifest.css" /> </head>
Here's an example of what can be done with some CSS: Styled Manifest. Perhaps there should be an official stylesheet in a known location, to facilitate developer work.
More can be done by adding HTML nodes to the document, which will be ignored during parsing and can help make the document more human-readable. However, this practice is discouraged because it can add too much unnecessary information to the manifest.
