Manifesty Instalacji

Wprowadzenie

Manifest Instalacji to plik, dzięki któremu Menedżer Dodatków określa szczegółowe informacje na temat dodatku, który jest instalowany. Zawiera on dane identyfikujące dodatek oraz informacje takie, jak: kto go stworzył, gdzie można znaleźć więcej informacji na jego temat, z jakimi wersjami aplikacji jest on zgodny, jak powinien przebiegać proces aktualizacji i tym podobne.

Manifest Instalacji jest zapisany w formacie RDF/XML.

Plik musi mieć nazwę install.rdf. Należy go umieścić na najwyższym poziomie pliku XPI.

Budowa

Podstawowy Manifest Instalacji ma budowę:

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <!-- własności -->
  </Description>
</RDF>

Niektóre własności są wymagane, inne nie. Jedne to proste łańcuchy tekstu, drugie to złożone zasoby.

Wymagane własności

Manifest Instalacji musi określać te własności, inaczej Twój dodatek nie zostanie zainstalowany.

id

id rozszerzenia to:

• GUID (wygenerowany przy pomocy guidgen w Windows lub uuidgen na systemach Uniksowych) (Firefox 1.0)
• Łańcuch tekstu w postaci: [email protected]

Ostatni format jest łatwiejszy do stworzenia i korzystania. Firefox 1.5 upewni się, że w twoim manifeście znajduje się id w jednym z podanych formatów, jeśli natrafi na źle sformułowany id, nie zainstaluje dodatku.

Przykłady

<em:id>[email protected]</em:id>

<em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>

version

Numer wersji odpowiedni dla instalowanego dodatku.

Dla Firefoksa/Thundebirda 1.0, format wersji musi spełniać warunki podane w artykule Extension Versioning, Update and Compatibility. Dla Firefoksa/Thundebirda 1.5, zobacz Toolkit version format.

Przykłady

<em:version>2.0</em:version>

<em:version>1.0.2</em:version>

<em:version>0.4.1.2005090112</em:version>

Firefox 1.5 - dodatki, które nie mają poprawnie określonego numeru wersji nie będą instalowane.

Dodatki hostowane na addons.mozilla.org - strona z aktualizacjami Mozilli może przepakować i naprawić lub odrzucić dodatek ze źle określonym numerem wersji.

type

Liczba całkowita określająca typ dodatku.

Przykłady

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

Tę własność dodano w Firefoksie 1.5 i jest ona wymagana tylko dla dodatków innych niż Rozszerzenia i Motywy.

targetApplication

Obiekt określający aplikację bazową dodatku. Oznacza to, że dodatek będzie działać z aplikacją identyfikowaną poprzez określoną własność (<em:id>)(zobacz pełną listę ID aplikacji na stronie Poprawne wersje aplikacji dla programistów dodatków), od minimalnej wersji (<em:minVersion>) do i włącznie z maksymalną wersją (<em:maxVersion>). Numery wersji określamy w ten sam sposób jak przy własności version będzie porównywany z wersją aplikacji; pozwala to autorowi rozszerzenia na określenie wersji Firefoksa, na których było ono testowane.

Uwaga: Firefoks 1.0-1.0.6 posiada wersję aplikacji 1.0. Uaktualnienia bezpieczeństwa oraz stabilności Firefoksa 1.5 posiadają wersje aplikacji 1.5.0.1, 1.5.0.2, itd. Rozszerzenia kompatybilne z Firefoksem lub Thunderbirdem 1.5 powinny określać maxVersion na 1.5.0.*, tak by były automatycznie zgodne z aktualizacjami bezpieczeństwa i stabilności.

Rozszerzenia kompatybilne z Firefoksem 2 powinny mieć określoną własność maxVersion jako 2.0.0.*

Manifest Instalacji musi określać przynajmniej jeden taki obiekt, a może więcej, jeżeli dodatek ma współpracować z wieloma aplikacjami, które posiadają Menedżera Dodatków (np. Firefox i Thunderbird)

Przykłady

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

name

Nazwa dodatku wyświetlana w interfejsie użytkownika (UI).

Przykłady

<em:name>Moje Rozszerzenie</em:name>

Opcjonalne własności

Będziesz mógł określić te własności w zależności od możliwości Twojego dodatku.

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.

Przykłady

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

Więcej dokumentacji można znaleźć na stronie Lokalizacja opisu rozszerzenia.

Ta własność została dodana dla Firefoksa 3.

description

Krótki opis dodatku wyświetlany w interfejsie użytkownika. Opis powinien mieścić się w krótkiej linijce tekstu.

Przykłady

<em:description>Zaawansowana wtyczka.</em:description>

creator

Imię twórcy/głównego developera wyświetlane w interfejsie użytkownika.

Przykłady

<em:creator>Jan Kowalski</em:creator>

lub

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

developer

Imię i nazwisko (imiona i nazwiska) co-developers. Można określić więcej niż jednego programistę.

Przykłady

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

translator

Imię i nazwisko (imiona i nazwiska) osób tłumaczących. Można określić więcej niż jednego tłumacza.

Przykłady

<em:translator>Jan Kowalski</em:translator>
<em:translator>Jan Nowak</em:translator>

contributor

Imiona i nazwiska dodatkowych współpracowników. Można określić więcej niż jednego współpracownika.

Przykłady

<em:contributor>Jan Kowalski</em:contributor> 

<em:contributor>Jan Kowalski</em:contributor>
<em:contributor>Jan Nowak</em:contributor>
<em:contributor>Jan Kowalski</em:contributor>

homepageURL

Odnośnik do strony domowej dodatku wyświetlany w interfejsie użytkownika.

Przykład:

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

updateURL

Odnośnik do własnego Manifestu Aktualizacji, który określa dostępne aktualizacje dla twojego dodatku. Składnia jest opisana poniżej. Jeżeli użytkownik wybrał odpowiednią opcję, to Menadżer Dodatków, co jakiś czas sprawdza plik Manifestu, by określić, czy jest dostępna nowa wersja dodatku.

Twój serwer musi wysłać ten plik w postaci text/rdf, inaczej automatyczna aktualizacja nie zadziała.

Menadżer Dodatków odpowiednio zamieni poniższe wartości w adresie URL, jeżeli chcesz, aby odpowiedź w formacie RDF była generowana dynamicznie, za pomocą PHP lub CGI:

Przykłady

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

<em:updateURL>https://www.foo.com/extension/windows.rdf</em:updateURL>

Dodatki hostowane na addons.mozilla.org: Nie musisz określać własności updateURL. Domyślnie aplikacje Mozilli korzystające z Menedżera Dodatków (jak Firefox i Thunderbird) wysyłają żądanie aktualizacji do addons.mozilla.org. Za każdym razem, kiedy wgrasz nową wersję twojego dodatku albo zmienisz parametry kompatybilności poprzez interfejs autora, twój Manifest Aktualizacji zostanie wygenerowany automatycznie.

Format Manifestu Aktualizacji: Manifest Aktualizacji jest w formacie RDF/XML, który jest opisana tutaj: Manifest Aktualizacji

optionsURL

Adres chrome:// okna dialogowego opcji rozszerzenia. Jest to przydatne jedynie rozszerzeniom. Jeżeli właściwość jest określona, przycisk Opcje na liście rozszerzeń będzie dostępny i będzie wyświetlał podane okno.

Przykłady

<em:optionsURL>chrome://wtyka/content/opcje.xul</em:optionsURL>

aboutURL

Adres chrome:// okna dialogowego Informacje o rozszerzeniu dodatku. Jest to przydatne jedynie rozszerzeniom. Jeżeli własność jest określona, przycisk Informacje o rozszerzeniu... na liście rozszerzeń będzie dostępny i będzie wyświetlał podane okno zamiast domyślnego.

Przykłady

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

iconURL

Adres chrome:// do ikonki o rozmiarze 32x32, która pojawi się na liście dodatków. Jeżeli nie określisz tej własności zostanie użyta domyślna ikonka.

<em:iconURL>chrome://wtyka/skin/ikonka.png</em:iconURL>

hidden

Wartość logiczna, gdy jest prawdziwa, dodatek nie zostanie wyświetlony na liście; zapewnia, że dodatek instalowany jest w chronionej strefie dostępu (np. nie ze strony WWW). Wykorzystuję się to przy budowaniu integracyjnych haków w większych aplikacjach, które mają na liście rozszerzeń wpisy nie mające sensu.

Przykłady

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

Niezalecane właściwości

Te właściwości nie są wspierane w nowszych wersjach Menedżera Dodatków. Są one ignorowane, ale mogą być wymagane przez starsze wersje.

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

OS_TARGET is typically the output of the 'uname -s' command on the target platform, e.g.:

• WINNT for Windows NT, 2000, XP and later
• Linux for all Linux versions
• Darwin for all MacOS X versions
• SunOS for all Solaris versions

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.

Przykłady

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

Notatki

• 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 addon 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.

Przykład

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

Notatki

• 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 addon regardless of the requirements.

Dokumentacja przestarzałych własności

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

file

Firefox 1.0 Ta właściwość wskazywała na plik .jar, który zawierała pakiety chrome wymagające rejestracji w Rejestrze Chrome.

Właściwość <em:file> ma złożona obiektową wartość. Adres lokalny wartości wygląda tak: urn:mozilla:extension:file:PlikJar.jar przy czym PlikJar.jar to nazwa pliku jar, który zawiera pliki pakietów chrome. Może to być także nazwa niespakowanego folderu zawierającego pliki pakietów chrome (np. urn:mozilla:extension:file:folder). In either case, the referenced chrome package file(s) must be placed in the chrome subdirectory of the XPI's top level.

Obiekt ma właściwość package (ze ścieżką wewnątrz pliku lub folderu z pakietami, która prowadzi do pliku contents.rdf, który jest odpowiedzialny za rejestrację pakietu), właściwość locale (jw. tylko, że rejestracji lokalizacji) i właściwość skin (jw. odpowiedzialną za rejestracje motywów).

Obiekt jest zbędny w Firefoksie 1.5 ponieważ chrome.manifest na najwyższym poziomie XPI jest używany do lokalizacji chrome wymagających rejestracji.

Przykłady

<em:file>
 <Description about="urn:mozilla:extension:file:wtyka.jar">
  <em:package>content/wtyka/</em:package>
  <em:locale>locale/pl/wtyka/</em:locale>
  <em:skin>skin/classic/wtyka/<em:skin>
 </Description>
</em:file>

Manifest Instalcji może określać więcej niż jedną właściwość file, po jednej na każdy plik jar lub podfolder zawierający chrome do rejestracji.

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 (zobacz 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.

Więcej informacji

• Zobacz stronę install.rdf w MozillaZine KB po więcej przykładów i informacji na ten temat