mozilla
Your Search Results

    Bản Kê Khai Cài Đặt

    Giới Thiệu

    Một Bản Kê Khai Cài Đặt (Install Manifest) là một tập tin mà một ứng dụng XUL - được bật mở trình Quản lý Tiện ích - sử dụng để xác định các thông tin về tiện ích khi nó được cài đặt. Nó chứa các siêu dữ liệu (metadata) để nhận diện tiện ích, cung cấp thông tin về người đã tạo ra nó, nơi mà các thông thêm về nó có thể được tìm thấy, các phiên bản nào của ứng dụng nào mà nó tương thích, làm sao để nó luôn được cập nhật, và nhiều thứ khác.

    Định dạng của Bản Kê Khai Cài Đặt là RDF/XML.

    Tập tin này phải được đặt tên là install.rdf và luôn có ở cấp cao nhất trong tập tin XPI của tiện ích.

    Bố Cục

    Bố cục cơ bản của một Bản Kê Khai Cài Đặt tương tự như sau:

    <?xml version="1.0"?>
    
    <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:em="http://www.mozilla.org/2004/em-rdf#">
      <Description about="urn:mozilla:install-manifest">
        <!-- các thuộc tính -->
      </Description>
    </RDF>
    

    Một số thuộc tính là bắt buộc, số khác là tùy chọn. Một số cái chỉ có giá trị chuỗi đơn giản, số khác lại là tài nguyên phức tạp.

    Các Thuộc Tính Bắt Buộc

    Bản Kê Khai Cài Đặt phải đặc tả những thuộc tính này một cách chính xác nếu không tiện ích của bạn có lẽ sẽ không được cài.

    id

    Định danh (id) của phần mở rộng, nó là một:

    • GUID (Firefox 1.0)
    • Một chuỗi định dạng giống như: extensionname@organization.tld

    The latter format is significantly easier to generate and manipulate. Firefox 1.5 has checking to ensure that your id falls into one format or the other and will refuse to install addons that have malformed ids.

    Examples

    <em:id>myextension@mysite.com</em:id>
    
    <em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>

    version

    A version string identifying the version of the addon being supplied.

    For Firefox/Thunderbird 1.0, the format must conform to the rules specified in Extension Versioning, Update and Compatibility. For Firefox/Thunderbird 1.5, see Toolkit version format.

    Examples

    <em:version>2.0</em:version>
    
    <em:version>1.0.2</em:version>
    
    <em:version>0.4.1.2005090112</em:version>

    Firefox 1.5 / XULRunner 1.8 - addons that do not use a valid version format will not be installed. The version format is different from, although backwards-compatible with, 1.0's.

    For addons hosted on addons.mozilla.org - Mozilla's update website may repackage your addon and correct or reject malformed version strings.

    type

    An integer value representing the type of addon.

    2 Extensions
    4 Themes
    8 Locale
    32 Multiple Item Package

    Examples

    <em:type>2</em:type>

    This property was added for Firefox 1.5, and is only required for addon types other than Extensions and Themes.

    Firefox 2 and previous supported a value of 16 to represent plug-ins. In Firefox 3 this has been removed.

    targetApplication

    An object specifying an application targeted by this addon. This means that the addon will work with the application identified by the id property (<em:id>) specified (for a comprehensive list of application IDs and valid min/maxVersions for them see Valid application versions for add-on developers), from the minimum version (<em:minVersion>) up to and including the maximum version (<em:maxVersion>). 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 Firefox an extension has been tested with.

    Extensions compatible with Firefox 3.5 should specify a maxVersion of 3.5.*, so that they are automatically compatible with security and stability updates. For Firefox 3.0, a maxVersion of 3.0.* should be used. Extensions compatible only with Firefox or Thunderbird 2 should specify a maxVersion of 2.0.0.*.

    The Install Manifest must specify at least one of these objects, and may specify more if the addon targets multiple applications that support the Add-on Manager (e.g. Firefox and Thunderbird)

    Examples

    <em:targetApplication>
     <Description>
      <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> Firefox
      <em:minVersion>1.5</em:minVersion>
      <em:maxVersion>3.0.*</em:maxVersion>
     </Description>
    </em:targetApplication>
    

    Gecko 1.9 based applications allow you to use the special targetApplication id toolkit@mozilla.org to say that the add-on is compatible with any toolkit app with a toolkit version matching the minVersion and maxVersion.

    name

    The name of the add-on; intended for display in the UI.

    Examples

    <em:name>My Extension</em:name>

    Optional Property Reference

    You may need to supply these properties, depending on the capabilities of your add-on.

    localized

    Allows you to localize the add-on's name, description, contributors and other metadata. The localized description must specify at least one em:locale which indicates which locales to use this information for.

    Examples

    This declares a set of add-on metadata to be displayed when the application is running in the de-DE locale.

    <em:localized>
      <Description>
        <em:locale>de-DE</em:locale>
        <em:name>Tab Sidebar</em:name>
        <em:description>Zeigt in einer Sidebar Vorschaubilder der Inhalte aller offenen Tabs an.</em:description>
      </Description>
    </em:localized>
    

    The following properties which are described elsewhere in this page can be included in the localized property:

    • name
    • description
    • creator
    • homepageURL
    • developer
    • translator
    • contributor

    More documentation can be found at Localizing extension descriptions.

    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.

    Examples

    <em:description>Advanced foo tools.</em:description>
    

    creator

    The name of the creator/principal developer - intended for display in the user interface.

    Examples

    <em:creator>John Doe</em:creator>
    

    or

    <em:creator>CoolExtension Team</em:creator>
    

    developer

    The name(s) of co-developers. You may specify more than one of this value to specify multiple developers.

    Examples

    <em:developer>Jane Doe</em:developer>
    <em:developer>Koos van der Merwe</em:developer>
    

    translator

    The name(s) of translators. You may specify more than one of this value to specify multiple translators.

    Examples

    <em:translator>Janez Novak</em:translator>
    <em:translator>Kari Nordmann</em:translator>
    

    contributor

    The name(s) of additional contributors. You may specify more than one of this value to specify multiple contributors.

    Examples

    <em:contributor>John Doe</em:contributor>
    
    <em:contributor>John Doe</em:contributor>
    <em:contributor>Jane Doe</em:contributor>
    <em:contributor>Elvis Presley</em:contributor>
    

    homepageURL

    A link to the addon's home page - intended for display in the user interface.

    Examples

    <em:homepageURL>http://www.foo.com/</em:homepageURL>
    

    updateURL

    A link to a custom Update Manifest file that specifies available updates to the addon. The format is described below. If enabled, the addon manager periodically checks with this Manifest file to determine if newer versions are available.

    Note: It is strongly recommended that the updateURL be an HTTPS (secure) link. Non-secure update URLs can be hijacked by a malicious update.rdf file, enabling malware to infiltrate the user's computer. Alternatively, you could host your extension on AMO and leave out the updateURL completely. This provides secure updates automatically.

    For security reasons, Gecko 1.9 applications require that if you specify an updateURL, it must be an https URL, or you must include an updateKey.

    Your server must send this file as text/rdf, text/xml or application/xml+rdf or the update checker may not work.

    The addon manager will substitute the following values into this URL in case you wish to generate the response RDF dynamically, such as using PHP or CGI:

    %REQ_VERSION% The version of the request. Currently 1
    %ITEM_ID% The id of the addon being updated
    %ITEM_VERSION% The version of the addon being updated
    %ITEM_MAXAPPVERSION% The maxVersion of the targetApplication object corresponding to the current application for the addon being updated.
    %ITEM_STATUS% Comma separated list of the add-ons operating status in the application. Contains at the least either userEnabled or userDisabled plus any number of incompatible, blockslisted or needsDependencies.
    %APP_ID% The id of the current application
    %APP_VERSION% The version of the application to check for updates for
    %CURRENT_APP_VERSION% The version of the current application
    %APP_OS% The value of OS_TARGET from the Firefox build system, identifying the operating system being used.
    %APP_ABI% The value of the TARGET_XPCOM_ABI value from the Firefox build system, identifying the compiler/architecture combination used to compile the current application.
    %APP_LOCALE% The current application's locale.

    Examples

    <em:updateURL>http://www.foo.com/update.cgi?id=%ITEM_ID%&amp;version=%ITEM_VERSION%</em:updateURL>
    <em:updateURL>http://www.foo.com/extension/windows.rdf</em:updateURL>
    

    For addons hosted on addons.mozilla.org: You may not specify an updateURL property. By default, Mozilla applications using the Addon Manager (such as Firefox and Thunderbird) will send update requests to addons.mozilla.org using the default web service. Every time you upload a new version of your addon or change its compatibility parameters through the author interface, your update manifest will be generated automatically. Addons currently marked as experimental will not be updated due to security concerns.

    Format of the Update Manifest: The Update Manifest is a RDF/XML datasource. For examples of an update manifest, see Extension Versioning, Update and Compatibility and Enabling Extension Updates (external).

    updateKey

    To ensure the security of update rdf 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 updateKey entry in the install.rdf of the add-on. This can be generated using the McCoy tool. Any line breaks and whitespace as part of this entry are ignored.

    Examples

     <em:updateKey>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK426erD/H3XtsjvaB5+PJqbhj
                   Zc9EDI5OCJS8R3FIObJ9ZHJK1TXeaE7JWqt9WUmBWTEFvwS+FI9vWu8058N9CHhD
                   NyeP6i4LuUYjTURnn7Yw/IgzyIJ2oKsYa32RuxAyteqAWqPT/J63wBixIeCxmysf
                   awB/zH4KaPiY3vnrzQIDAQAB</em:updateKey>
    

    optionsURL

    The chrome:// URL of the extension's options dialog box. This is only useful to extensions. If this property is specified, when the extension is selected in the Extensions list, the Options button is enabled and will show this.

    Examples

    <em:optionsURL>chrome://myext/content/options.xul</em:optionsURL>
    

    aboutURL

    Thechrome:// URL of the extension's about dialog box. This is only useful to extensions. If this property is specified, when the extension is selected in the Extensions list, the About... link in the extension's context menu will show this dialog, rather than the default.

    Examples

    <em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>
    

    iconURL

    A chrome:// URL to a 32x32 icon to display in the add-ons list. If this property is not specified, a default icon is used.

    <em:iconURL>chrome://myext/skin/icon.png</em:iconURL>
    Note: For the above example to work you will also have to add a skin package line to your chrome.manifest file. See Chrome Registration#skin. Alternatively you can place your icon in the directory specified in your content package line.

    Gecko 1.9.2 note
    Starting in Gecko 1.9.2 (Firefox 3.6), you can also simply include your icon, named icon.png, in the base directory of the add-on. This allows your add-on's icon to be displayed even when the add-on is disabled, or if the manifest is missing an iconURL entry.

    targetPlatform

    A string specifying a platform that the addon supports. It contains either the value of OS_TARGET alone or combined with TARGET_XPCOM_ABI, separated by an underscore (_).

    You can specify multiple targetPlatform properties per manifest. If any value matches the application's build parameters, it will be installed; if not, the user will get an appropriate error message.

    Examples

    <em:targetPlatform>WINNT_x86-msvc</em:targetPlatform>
    
    <em:targetPlatform>Linux</em:targetPlatform>
    
    <em:targetPlatform>Darwin_ppc-gcc3</em:targetPlatform>
    
    <em:targetPlatform>SunOS_sparc-sunc</em:targetPlatform>
    

    Usually, you would use only the OS part for themes or for extensions that are not fully cross-platform. For extensions including binary (compiled) components, you should never use the OS alone, but include the ABI (s) that you compiled the components with. If you want to include multiple versions of the components, you should also use Platform-specific Subdirectories.

    Notes

    • In the same manifest file, you could even mix values with and without ABI. If a value for the application's OS is encountered that requires any specific ABI, the ABI is considered important for that OS and the application will refuse to install the addon if it does not find a matching OS/ABI combination. This means that if all of the above examples would occur in one manifest, the addon will install on any Linux build of the application, regardless of its ABI, but not on a Windows Cygwin build.
    • There may be builds of Firefox and Thunderbird which do not "know" their ABI (most likely ports to rare platforms, or non-official builds). These builds will refuse to install any addon that requires a specific ABI for their platform.

    This property was added for Firefox/Thunderbird 1.5. Previous versions of these applications will ignore the restrictions and install the addon regardless of the platform.

    requires

    This tag has a similar syntax to the <em:targetApplication> tag. If the add-on specified by the <em:id> tag is not installed or has an incompatible version, the extension manager will disable your extension and show the message "Requires additional items". You can add as many <em:requires> tags as you like. Your extension will be disabled if any of the specified requirements fail.

    Example

    <em:requires>
       <Description>
         <!-- Lightning -->
         <em:id>{e2fda1a4-762b-4020-b5ad-a41df1933103}</em:id>
         <em:minVersion>0.5pre</em:minVersion>
         <em:maxVersion>0.5pre</em:maxVersion>
       </Description>
     </em:requires>
    

    Notes

    • Currently, only <em:id>, <em:minVersion>, <em:maxVersion> are parsed inside the <em:requires> tag.
    • It is not currently possible to add dependencies that are specific to a <em:targetApplication>. See wikimo:Extension Manager:Extension Dependencies for more details.

    This property was added for Firefox/Thunderbird 2. Previous versions of these applications will ignore the restrictions and install the add-on regardless of the requirements.

    Obsolete Property Reference

    These properties were required in older versions of the Addon Manager, but have been replaced with newer and better mechanisms.

    file

    Firefox 1.0 This property pointed to a chrome .jar file that contains chrome packages that require registration with the Chrome Registry.

    The <em:file> property has a complex object value. The uri of the value is urn:mozilla:extension:file:jarFile.jar where jarFile.jar is the name of the jar file that contains the chrome package's files. This could also be the name of a directory that contains the chrome package's files, un-jarred (e.g. urn:mozilla:extension:file:directory). In either case, the referenced chrome package file(s) must be placed in the chrome subdirectory of the XPI's top level.

    This object has a package property (with a path within the jar file or directory that leads to the location where the contents.rdf file responsible for registering that package is located), a locale property (ditto, but to register the locale) and a skin property (ditto, but to register the theme material).

    In extensions for Firefox 1.5, this property is no longer necessary: the chrome.manifest at the top level of the XPI is used to locate chrome to register. If there is no chrome.manifest, this property is still read by the Addon Manager and a chrome.manifest is generated from old-style contents.rdf.

    Examples

    <em:file>
     <Description about="urn:mozilla:extension:file:myext.jar">
      <em:package>content/myext/</em:package>
      <em:locale>locale/en-US/myext/</em:locale>
      <em:skin>skin/classic/myext/<em:skin>
     </Description>
    </em:file>
    

    An Install Manifest may specify multiple file properties, one for each jar file or subdirectory that contains chrome to register.

    hidden

    Firefox 1.0 - 3.5 A boolean value that when true makes the add-on not show up in the add-ons list, provided the add-on is installed in a restricted access area (so it does not work for add-ons installed in the profile). This is for bundling integration hooks to larger applications where having an entry in the Extensions list does not make sense.

    Note: This property is no longer supported under Gecko 1.9.2 (Firefox 3.6) or later, to prevent extensions from being installed in such a way that the user might not be able to tell they're installed.

    Examples

    <em:hidden>true</em:hidden>

    Glossary

    restricted access area

    A restricted access area is an install location that could be restricted on a restricted-access account, regardless of whether or not the location is restricted with the current user privileges (see nsIInstallLocation::restricted). Currently, the ($APPDIR)/extensions folder and the registry install location under HKEY_LOCAL_MACHINE (see Adding Extensions using the Windows Registry for details) are restricted.

    The ($PROFILE)/extensions and HKEY_CURRENT_USER install locations, on the other hand, are not restricted.

    Document Tags and Contributors

    Contributors to this page: ethertank, kimkha
    Last updated by: ethertank,