Les modules complémentaires utilisant les techniques décrites dans ce document sont considérés comme une ancienne technologie dans Firefox. N'utilisez pas ces techniques pour developper de nouveaux modules complémentaires. Utilisez plutôt les WebExtensions. Si vous maintenez un module qui utilise les techniques qui sont décrites ici, envisagez d'effectuer la migration vers les WebExtensions.

À partir de Firefox 53, plus aucun ancien module complémentaire ne sera accepté sur addons.mozilla.org (AMO) pour Firefox pour les ordinateurs et Firefox pour Android.

À partir de Firefox 57, seules les extensions développées avec l'API des WebExtensions seront prises en charge sur Firefox pour les ordinateurs et Firefox pour Android.

Même avant Firefox 57, les changements qui arrivent dans la plateforme Firefox vont rendre beaucoup d'anciennes extensions inutilisables. Ces changements incluent Firefox multiprocessus (e10s), le sandboxing, et les processus de contenu multiple. Les extensions héritées qui sont touchées par ces changements devraient migrer vers l'API des WebExtensions si possible. Voir le document "Compatibility Milestones" (étapes de compatibilité) pour plus d'informations.

Une page du wiki contenant les ressources, chemins de migration, heures d'ouverture et autres, est disponible pour les développeurs souhaitant effectuer la transition vers les nouvelles technologies.

Les extensions traditionnelles incluent des superpositions, dans lesquelles l'application peut charger XUL depuis le paquet de l'extension et l'appliquer automatiquement sur sa propre interface utilisateur. Bien que la création d'extensions, qui ajoutent à l'interface utilisateur de l'application, soit relativement simple, cela signifie que la mise à jour, l'installation ou la désactivation d'une extension nécessite un redémarrage de l'application.

Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) introduit des extensions "bootstrapées". Ce sont des extensions spéciales qui, au lieu d'utiliser une superposition pour appliquer leur interface utilisateur à l'application, s'insèrent par programmation dans l'application. Ceci est fait en utilisant un fichier de script spécial inclus dans l'extension qui contient les fonctions que le navigateur appelle pour commander à l'extension d'installer, désinstaller, démarrer et arrêter.

Toute l'application fait appel à ce fichier de script; l'extension est responsable de l'ajout et de la suppression de son interface utilisateur et de la gestion des autres tâches d'installation et d'arrêt nécessaires.

Cet article explique comment fonctionnent les extensions "bootstrap". Consultez ce didacticiel sur la conversion d'une extension superposée en une opération sans redémarrage pour obtenir un guide pratique étape par étape de la migration.

Le processus de démarrage et d'arrêt

Une fonctionnalité clé des extensions "bootstrapées" est qu'elles doivent pouvoir démarrer et arrêter à la demande de l'application. Lorsque la fonction de startup() (démarrage) de l'extension est appelée, elle doit injecter manuellement son interface utilisateur et tout autre comportement dans l'application. De même, lorsque sa fonction shutdown() (arrêt) est appelée, elle doit supprimer tout ce qu'elle a ajouté à l'application, ainsi que toutes les références à l'un de ses objets.

Il existe plusieurs scénarios dans lesquels la fonction startup() peut être appelée, par exemple :

  • lorsque l'extension est installée pour la première fois, en supposant qu'elle soit compatible avec l'application et activée.
  • lorsque l'extension est activée à l'aide de la fenêtre du gestionnaire de modules complémentaires.
  • lorsque l'application est démarrée, si l'extension est activée et compatible avec l'application.

Quelques exemples  de situations où la fonction shutdown() peut être appelée :

  • lorsque l'extension est désinstallée, si elle est actuellement activée.
  • lorsque l'extension est désactivée.
  • lorsque l'utilisateur quitte l'application, si l'extension est activée.

Notes sur la modification de l'interface utilisateur de l'application

chrome.manifest dans les extensions "bootstrapées"

Vous pouvez utiliser un fichier chrome.manifest dans l'extension "bootstrapée" pour :

  • Rendre le contenu de votre module complémentaire disponible via une URL chrome:// (en utilisant les instructions content (contenu), locale (langue) et skin (habillage) dans le manifeste).
  • Remplacer les URI du chrome:// existant avec votre contenu (en utilisant l'instruction override (passer outre)).

Toutes les instructions chrome.manifest ne sont pas supportées dans les extensions bootstrapées, par exemple, vous ne pouvez toujours pas enregistrer d' Overlays XUL à partir d'une extension "bootstrapée". Voir la documentation Enregistrement chrome pour les détails.

Dans Firefox 10 et versions ultérieures, le fichier chrome.manifest situé dans la racine du XPI du module complémentaire (c'est-à-dire un frère du fichier install.rdf) est chargé automatiquement. Dans Firefox 8 et 9, vous devez charger / décharger manuellement le manifeste en utilisant nsIComponentManager.addBootstrappedManifestLocation() et nsIComponentManager.removeBootstrappedManifestLocation(). Cette fonctionnalité n'était pas disponible dans les versions de Firefox avant 8.

Ajout manuel d'une interface utilisateur

Si vous décidez de développer une extension "bootstrapée", qui modifie l'interface utilisateur de l'application, voici quelques suggestions pour vous aider à démarrer.

Vous devez rechercher les éléments d'interface utilisateur de l'application appropriés par leur ID en appelant document.getElementById (), puis les manipuler pour injecter votre interface utilisateur. Par exemple, vous pouvez accéder à la barre de menus de Firefox avec document.getElementById ("main-menubar").

Assurez-vous qu'au moment de l'arrêt, vous supprimez toute interface utilisateur que vous avez ajoutée.

Création d'une extension "bootstrapée"

Pour marquer une extension comme "bootstrappable", vous devez ajouter l'élément suivant à son manifeste d'installation :

<em:bootstrap>true</em:bootstrap>

Alors, vous devez ajouter un fichier bootstrap.js qui contient les fonctions requises ; elles devraient être à côté du fichier install.rdf dans le paquet de l'extension.

Rétrocompatibilité

Parce que les anciennes versions de Firefox ne connaissent pas la propriété bootstrap ou le fichier bootstrap.js, il n'est pas trop difficile de créer un XPI qui fonctionnera à la fois comme une extension "bootstrapable" et comme une extension traditionnelle. Créez votre extension en tant qu'extension "bootstrapable", puis ajoutez les "overlays" (superpositions) traditionnels. Les versions plus récentes de Firefox utiliseront le script bootstrap.js, en ignorant les composants et les superpositions, alors que les versions plus anciennes utiliseront les superpositions.

Points d'entrée Bootstrap

Le script bootstrap.js doit contenir plusieurs fonctions spécifiques, appelées par le navigateur pour gérer l'extension. Le script est exécuté dans un bac à sable privilégié, qui est mis en cache jusqu'à ce que l'extension soit arrêtée.

startup (démarrage)

Appelé lorsque l'extension doit se démarrer elle-même. Il se produit au moment du lancement de l'application, lorsque l'extension est activée après avoir été désactivée ou après son arrêt afin d'installer une mise à jour. Il peut être appelé plusieurs fois pendant la durée de vie de l'application.

C'est à ce moment que votre extension doit injecter son interface utilisateur, démarrer toutes les tâches qu'elle peut avoir besoin d'exécuter et ainsi de suite.

void startup(
  data,
  reason
); 
Paramètres
data (donnée)
Une donnée bootstrap.
reason (motif)
Une des constantes causales, indiquant pourquoi l'extension est en cours de démarrage. Ce peut être l'une d'entre elles : APP_STARTUP, ADDON_ENABLE, ADDON_INSTALL, ADDON_UPGRADE ou ADDON_DOWNGRADE.

shutdown (arrêt)

Appelé lorsque l'extension doit se fermer, par exemple lorsque l'application est en cours de fermeture, ou lorsqu'elle est sur le point d'être mise à niveau ou désactivée. Toute interface utilisateur qui a été injectée doit être supprimée, les tâches doivent être arrêtées et les objets éliminés.

void shutdown(
  data,
  reason
);
Paramètres
data (donnée)
Une donnée bootstrap.
reason (motif)
Une des constantes causales, indiquant pourquoi l'extension est en train de se fermet. Ce peut être l'une d'entre elles : APP_SHUTDOWN, ADDON_DISABLE, ADDON_UNINSTALL, ADDON_UPGRADE ou ADDON_DOWNGRADE.

install (installation)

Votre script "bootstrap" doit inclure une fonction install() que l'application appelle avant le premier appel startup() après l'installation, la mise à niveau ou le déclassement de l'extension.

void install(
  data,
  reason
); 
Paramètres
data (donnée)
Une donnée bootstrap.
reason (motif)
Une des constantes causales, indiquant pourquoi l'extension est en train d'être installée. Ce peut être l'une d'entre elles : ADDON_INSTALL, ADDON_UPGRADE, ou ADDON_DOWNGRADE.

uninstall (désinstallation)

Cette fonction est appelée après le dernier appel à shutdown()  avant qu'une version particulière de l'extension soit désinstallée. Il n'est pas appelé si install()  n'a jamais été appelé .

Note : Si vous ouvrez le gestionnaire de modules complémentaires, puis cliquez sur «Supprimer» sur un module complémentaire, il n'appellera pas la fonction de désinstallation immédiatement. Il s'agit d'une désinstallation en raison de l'option "Annuler" disponible. Si le gestionnaire de modules complémentaires est fermé ou qu'un autre événement se déroule de telle sorte que l'option "Annuler" devient indisponible, la désinstallation en dur a lieu et la fonction de désinstallation est appelée.
Note : La fonction de désinstallation s'exécute sur déclassement et mise à niveau, ainsi vous devriez vous assurer qu'il s'agit d'une désinstallation en faisant ceci :
function uninstall(aData, aReason) {
     if (aReason == ADDON_UNINSTALL) {
          console.log('really uninstalling');
     } else {
          console.log('not a permanent uninstall, likely an upgrade or downgrade');
     }
}
void uninstall(
  data,
  reason
); 
Paramètres
data (donnée)
Une donnée bootstrap.
reason
Une des constantes causales, indiquant pourquoi l'extension est en train d'être désinstallée. Ce peut être l'une d'entre elles : ADDON_UNINSTALL, ADDON_UPGRADE ou ADDON_DOWNGRADE.

Constantes causales

La fonction bootstrap accepte un paramètre reason (motif), qui explique pourquoi l'extension est appelée. Les constantes causales sont :

Constante Valeur Description
APP_STARTUP 1 L'application est démarrée.
APP_SHUTDOWN 2 L'application est fermée.
ADDON_ENABLE 3 Le module complémentaire est activé.
ADDON_DISABLE 4 Le module complémentaire est désactivé. (également envoyé pendant la désinstallation)
ADDON_INSTALL 5 Le module complémentaire est installé.
ADDON_UNINSTALL 6 Le module complémentaire est désinstallé.
ADDON_UPGRADE 7 Le module complémentaire est mis à jour.
ADDON_DOWNGRADE 8 Le module complémentaire est déclassé.

Données bootstrap

Chacun des points d'entrée est transmis à une structure de données simple contenant des informations utiles sur le module complémentaire "bootstrapé". Plus d'informations sur l'extension peuvent être obtenues en appelant AddonManager.getAddonByID(). Les données sont un objet JavaScript simple avec les propriétés suivantes :

Propriété Type Description
id chaîne de caractères L'ID du module complémentaire est "bootstrapé".
version chaîne de caractères La version du module complémentaire est "bootstrapée".
installPath (chemin d'installation) nsIFile L'emplacement d'installation du module complémentaire est "bootstrapé". Il peut s'agir d'un répertoire ou d'un fichier XPI selon que le module complémentaire est installé décompressé ou non.
resourceURI (URI ressource) nsIURI L'URI pointe sur la racine des fichiers complémentaires, il peut s'agir d'un URI jar: ou file: , selon que le module complémentaire est installé ou non.
oldVersion (ancienne version) chaîne de caractères La précédente version installée, si le motif est ADDON_UPGRADE ou ADDON_DOWNGRADE, et si la méthode est install oustartup.
newVersion (nouvelle version) chaîne de caractères La version à installer, si le motif est ADDON_UPGRADE ou ADDON_DOWNGRADE, et si la méthode est shutdown ou uninstall.

Note : Un module complémentaire peut être mis à niveau / déclassé au démarrage de l'application, dans ce cas, le motif de la méthode startup est APP_STARTUP et la propriété oldVersion n'est pas définie. Sachez également que, dans certaines circonstances, une mise à niveau ou un déclassement additif peut se produire sans que la méthode de désinstallation soit appelée.

Débogueur de module complémentaire

A partir de Firefox 31, vous pouvez utiliser le débogueur de module complémentaire pour déboguer les modules complémentaires "bootstrapés".

Localisation (L10n)

La localisation des modules complémentaires "bootstrapés" est très similaire à celle de Firefox 7, car c'est à ce moment-là que la compatibilité de chrome.manifest a démarré.

Fichiers JS et JSM - Utilisation des fichiers de propriétés

Pour localiser vos fichiers .js et .jsm , vous avez à utiliser les fichiers de propriétés.

Le minimum absolument nécessaire est :

  1. Fichier : install.rdf
  2. Fichier : chrome.manifest
  3. Fichier : bootstrap.js
  4. Dossier : locale (langue)
    1. Dossier : VALID_LOCALE_HERE (localisation valide ici)
      1. Fichier : ANYTHING.properties (toutes les propriétés)

Dans le dossier "locale", vous devez disposer de dossiers pour chacune des langues que vous souhaitez fournir; chaque dossier doit être nommé avec un nom "locale" valide (exemple : fr). Dans ce dossier, doit exister un fichier de propriétés. Dans le fichier chrome.manifest, ces paramètres régionaux doivent être définis. Par exemple, si vous disposez d'un sous-dossier fr dans le dossier "locale", votre fichier chrome.manifest devra contenir : locale NAME_OF_YOUR_ADDON fr locale/fr/

Ici un exemple : GitHub :: l10n-properties - au démarrage de ce module, il affichera une invite indiquant USA ou Grande-Bretagne, avec laquelle choisir la langue la plus proche de la vôtre. Vous pouvez tester différents "locale" en allant sur about:config et en changeant les préférences de general.useragent.locale, et en désactivant puis en réactivant le module complémentaire.

Fichiers XUL et HTML - Utilisation d'entités à partir de fichiers DTD

Plusieurs pages HTML sont utilisées, mais elles ne peuvent pas être localisées avec des fichiers DTD. Il y a trois changements que vous devez faire :

  1. Vous devez changer l'extension du fichier HTML en .xhtml
  2. Le doctype doit être défini pointant sur un fichier DTD dans votre dossier "locale", ainsi par exemple : <!DOCTYPE html SYSTEM "chrome://l10n/locale/mozilla.dtd">
  3. Vous devez ajouter l'attribut xmlns à la balise html, par exemple : <html xmlns="http://www.w3.org/1999/xhtml">
  4. Si vous avez plusieurs fichiers DTD lisez ceci : Utilisation de plusieurs DTD

Le minimum nécessaire est :

  1. Fichier : install.rdf
  2. Fichier : chrome.manifest
  3. Fichier : bootstrap.js
  4. Dossier : locale
    1. Dossier : VALID_LOCALE_HERE
      1. Fichier : ANYTHING.dtd

Le fichier chrome.manifest doit inclure une définition pour le contenu, par exemple: content NAME_OF_YOUR_ADDON ./

Le fichier chrome.manifest doit aussi inclure une ligne pointant sur le dossier "locale", comme dans la section de propriété ci-dessus, si vous avez un dossier nommé en-US dans le dossier "locale", le fichier chrome.manifest doit contenir : locale NAME_OF_YOUR_ADDON en-US locale/en-US/

ici un exemple de module complémentaire qui ouvre une page HTML et une page  XUL sur install : GitHub :: l10n-xhtml-xul. Voici un exemple montrant comment utiliser une page HTML localisée en tant que page d'options : GitHub :: l10n-html-options. Vous pouvez aller sur about:config et changer la valeur de la préférence general.useragent.locale en-US par en-GB et recharger la page ouverte pour voir les changements sur les paramètres régionaux.

Plus de lecture

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : loella16, jmh
 Dernière mise à jour par : loella16,