From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- .../add-ons/bootstrapped_extensions/index.html | 348 +++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 files/fr/mozilla/add-ons/bootstrapped_extensions/index.html (limited to 'files/fr/mozilla/add-ons/bootstrapped_extensions') diff --git a/files/fr/mozilla/add-ons/bootstrapped_extensions/index.html b/files/fr/mozilla/add-ons/bootstrapped_extensions/index.html new file mode 100644 index 0000000000..4cc231fe1d --- /dev/null +++ b/files/fr/mozilla/add-ons/bootstrapped_extensions/index.html @@ -0,0 +1,348 @@ +--- +title: Modules complémentaires bootstrapés +slug: Mozilla/Add-ons/Bootstrapped_extensions +tags: + - Extensions + - Guide + - Modules complémentaires +translation_of: Archive/Add-ons/Bootstrapped_extensions +--- +

{{LegacyAddonsNotice}}{{AddonSidebar}}

+ +

{{ gecko_minversion_header("2.0") }}

+ +

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 {{geckoRelease ("2.0")}} 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 :

+ + + +

Quelques exemples  de situations où la fonction shutdown() peut être appelé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 :

+ + + +

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 {{ifmethod ("nsIComponentManager", "addBootstrappedManifestLocation")}} et {{ifmethod ("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 {{domxref ("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 :

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstanteValeurDescription
APP_STARTUP1L'application est démarrée.
APP_SHUTDOWN2L'application est fermée.
ADDON_ENABLE3Le module complémentaire est activé.
ADDON_DISABLE4Le module complémentaire est désactivé. (également envoyé pendant la désinstallation)
ADDON_INSTALL5Le module complémentaire est installé.
ADDON_UNINSTALL6Le module complémentaire est désinstallé.
ADDON_UPGRADE7Le module complémentaire est mis à jour.
ADDON_DOWNGRADE8Le 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éTypeDescription
idchaîne de caractèresL'ID du module complémentaire est "bootstrapé".
versionchaîne de caractèresLa version du module complémentaire est "bootstrapée".
installPath (chemin d'installation)nsIFileL'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)nsIURIL'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. {{ gecko_minversion_inline("7.0") }}
oldVersion (ancienne version)chaîne de caractèresLa précédente version installée, si le motif est ADDON_UPGRADE ou ADDON_DOWNGRADE, et si la méthode est install oustartup. {{ gecko_minversion_inline("22.0") }}
newVersion (nouvelle version)chaîne de caractèresLa version à installer, si le motif est ADDON_UPGRADE ou ADDON_DOWNGRADE, et si la méthode est shutdown ou uninstall. {{ gecko_minversion_inline("22.0") }}
+ +
+

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. +
  2. Fichier : chrome.manifest
    3. +
  3. Fichier : bootstrap.js
    4. +
  4. Dossier : locale (langue) +
      +
    1. Dossier : VALID_LOCALE_HERE (localisation valide ici) +
        +
      1. Fichier : ANYTHING.properties (toutes les propriétés)
        2. +
      +
      2. +
    +
    5. +
+ +

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. +
  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. +
  3. Vous devez ajouter l'attribut xmlns à la balise html, par exemple : <html xmlns="http://www.w3.org/1999/xhtml">
    4. +
  4. Si vous avez plusieurs fichiers DTD lisez ceci : Utilisation de plusieurs DTD
    5. +
+ +

Le minimum nécessaire est :

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

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

+ + -- cgit v1.2.3-54-g00ecf