Votre première WebExtension

Si vous connaissez déjà les concepts de base des extensions de navigateur, vous pouvez directement consulter afin de voir comment les fichiers d'extension sont assemblés. Ensuite, utilisez la documentation de référence pour commencer la construction de votre extension. Visitez l'atelier sur les extensions de Firefox pour en savoir plus sur le processus de test et de publication des WebExtensions pour Firefox.

Cet article vous montre comment créer une extension Firefox, du début à la fin. L'extension ajoute une bordure de couleur rouge sur toutes les pages chargées depuis le site "mozilla.org" ou n'importe lequel de ses sous-domaines.

Le code source de cet exemple est disponible sur GitHub : https://github.com/mdn/webextensions-examples/tree/master/borderify.

Pour commencer, il vous faut Firefox (dans la version 45 ou avec une version supérieure).

Écriture de l'extension

Créez un nouveau répertoire et déplacez vous à l'intérieur. Par exemple, dans votre ligne de commande/terminal vous pourriez le faire comme ceci :

mkdir borderify
cd borderify

manifest.json

Créez un nouveau fichier nommé manifest.json directement dans le répertoire borderify et tapez-y le contenu suivant :

{

  "manifest_version": 2,
  "name": "Borderify",
  "version": "1.0",

  "description": "Ajoute une bordure rouge pleine sur l'ensemble des pages web mozilla.org.",

  "icons": {
    "48": "icons/border-48.png"
  },

  "content_scripts": [
    {
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ]

}
  • Les trois premières clés : manifest_version, name, et version sont obligatoires et contiennent des métadonnées fondamentales nécessaires au module.
  • description est optionnelle, mais recommandée : elle s'affiche dans le gestionnaire de module.
  • icons est optionnelle, mais recommandée : elle permet d'établir l'icône du module qui s'affichera dans le gestionnaire de module.

La clé la plus intéressante ici est content_scripts, qui demande à Firefox de charger un script dans toutes les pages dont l'URL correspond à un motif de correspondance de domaines spécifique. Dans notre cas, nous demandons à Firefox de charger un script appelé borderify.js dans toutes les pages HTTP ou HTTPS du domaine "mozilla.org" et tous ses sous-domaines.

Dans certaines situations, vous devez établir un identifiant pour votre extension. Si vous avez besoin d'établir un identifiant pour votre extension, incluez la clé browser_specific_settings dans manifest.json et définissez sa propriété gecko.id :

"browser_specific_settings": {
  "gecko": {
    "id": "borderify@example.com"
  }
}

icons/border-48.png

Le module doit posséder une icône qui sera affichée dans le gestionnaire de modules du navigateur. Le fichier manifest.json utilisé ici fournit une icône icons/border-48.png.

Créons le répertoire icons directement sous le répertoire borderify. Fournissez une icône nommée border-48.png. Vous pouvez utiliser celle-ci, qui est tirée du repértoire d'icônes Google Material Design, et est utilisable à condition de respecter les termes de la licence Creative Commons Attribution-ShareAlike.

Si vous décidez de fournir votre propre icône, sa taille devra être de 48x48 pixels. Il est aussi possible de fournir une icône de 96x96 pixels, adaptée à l'affichage en haute résolution et, dans ce cas, elle devra être spécifiée par la propriété 96 de l'objet icon dans le fichier manifest.json :

"icons": {
  "48": "icons/border-48.png",
  "96": "icons/border-96.png"
}

Une alternative est de fournir un fichier SVG qui sera automatiquement mis à la bonne échelle.

borderify.js

Enfin, créez un fichier nommé borderify.js directement dans le répertoire borderify et insérez-y ceci :

document.body.style.border = "5px solid red";

Ce script sera chargé dans chaque page où le domaine correspond au motif fourni par la clé content_scripts du manifeste. Ce script a un accès direct au document contrairement à des scripts chargés par la page elle-même.

Essai

D'abord, vérifiez de nouveau que les bons fichiers sont au bon endroit :

borderify/
    icons/
        border-48.png
    borderify.js
    manifest.json

Installation

Dans Firefox : Ouvrez la page about:debugging, cliquez sur "Firefox" (dans les versions plus récentes de Firefox), cliquez sur « Chargez un module complémentaire temporaire… », puis sélectionnez n'importe quel fichier dans le répertoire de votre extension.

Le module complémentaire est dorénavant installé et persistera jusqu’à ce que vous redémarriez Firefox.

Une autre alternative est d’exécuter l'extension depuis la ligne de commande à l'aide de l'outil web-ext.

Test

Rendez-vous sur une page web du domaine "mozilla.org". Vous devriez y voir une bordure rouge qui entoure la page :

Toutefois, n'essayez pas ce module sur addons.mozilla.org ! Les scripts de contenu sont bloqués sur ce domaine.

Expérimentez un peu en modifiant le contenu du script, en changeant par exemple la couleur de la bordure ou en altérant le contenu de la page. Puis sauvegardez le content script, rechargez les fichiers du module en cliquant sur le bouton « Recharger » dans about:debugging. Les changements sont immédiats :

Empaqueter et publier

Afin que d'autres personnes puissent utiliser votre module, il vous faut l'empaqueter et le soumettre à la signature de Mozilla. Pour en apprendre plus, voir "Publier votre extension".

Et ensuite ?

Maintenant que vous avez eu une introduction au processus de développement d'une WebExtension pour Firefox, voici quelques suggestions pour la suite :