Ajouter une page de paramètres

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Une page de paramètres donne aux utilisateurs la possiblité de voir et de changer les paramètres (parfois aussi appelée "préférences" ou "options") de l'extension.

Avec les WebExtensions, les paramètres sont généralement stockés en utilisant l'API storage. L'ajout d'une page de paramètres se fait en trois étapes :

  • Écrire un fichier HTML qui affiche les paramètres et permet à l'utilisateur de les changer.
  • Écrire un script, inclus depuis le fichier HTML, qui alimente les paramètres depuis le stockage et met à jour les paramètres stockés quand l'utilisateur les change.
  • Renseigner le chemin du fichier HTML come clé de options_ui dans manifest.json. Ainsi, le document HTML sera affiché dans le gestionnaire d'extension, aux cotés des nom et description de l'extension.

Vous pouvez aussi ouvrir cette page automatiquement en utilisant la fonction runtime.openOptionsPage().

Une WebExtension simple

Tout d'abord, nous allons écrire une extension qui ajoute une bordure bleue à chaque page que l'utilisateur visite.

Créez un nouveau dossier nommé "paramètres", dans lequel vous créez un fichier nommé "manifest.json" ayant pour contenu :

{

  "manifest_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["borderify.js"]
    }
  ]

}

Cette extension commande au navigateur de charger un script de contenu nommé "borderify.js" dans chaque page que l'utilisateur visite.

Ensuite, créez un fichier nomé "borderify.js" dans le dossier "paramètres", et remplissez le comme suit :

document.body.style.border = "10px solid blue";

Ça ajoute une bordure bleue à la page.

Maintenant, installez la WebExtension et testez la — ouvrez la page que vous voulez :

Ajouter des paramètres

Maintenant, créez une page de paramètres pour autoriser l'utilisateur à définire la couleur de la bordure.

D'abord, mettez à jour le contenu de "manifest.json" avec celui-ci :

{

  "manifest_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["borderify.js"]
    }
  ],

  "options_ui": {
    "page": "options.html"
  },

  "permissions": ["storage"]

}

Vosu avez ajoutez deux nouvelles clés :

  • options_ui: Cela définit un document HTML comme étant la page de paramètres (aussi appelée page d'options) pour cette extension.
  • permissions: Vous allez utilisez l'API storage pour stockes les paramètres, vous devez donc demander la permission d'utiliser cette API.

Ensuite, puisque vous avez promis de fournir "options.html", créez le à l'intérieur du dossier "paramètres" et remplissez le comme suit :

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
  </head>

  <body>

    <form>
        <label>Border color<input type="text" id="color" ></label>
        <button type="submit">Save</button>
    </form>

    <script src="options.js"></script>

  </body>

</html>

Cela définit un <form> avec un label de texte <input> et un <button> de type "submit". Ça inclus également un script nommé "options.js".

Créez "options.js", lui-aussi dans le dossier "paramètres", et remplissez le comme suit :

function saveOptions(e) {
  e.preventDefault();
  browser.storage.local.set({
    color: document.querySelector("#color").value
  });
}

function restoreOptions() {

  function setCurrentChoice(result) {
    document.querySelector("#color").value = result.color || "blue";
  }

  function onError(error) {
    console.log(`Error: ${error}`);
  }

  var getting = browser.storage.local.get("color");
  getting.then(setCurrentChoice, onError);
}

document.addEventListener("DOMContentLoaded", restoreOptions);
document.querySelector("form").addEventListener("submit", saveOptions);

Cela fait deux choses :

  • Quand le document a été chargé, le script attribue à "color" une valeur depuis le stockage grâce à storage.local.get(). Si la valeur n'est pas renseignée, il utilise "blue" par défaut.
  • Quand l'utilisateur valide le formulaire en cliquant sur "Save", le script stocke la valeur de textbox en utilisant storage.local.set().

Finalement, mettez à jour "borderify.js" pour lire la couleur de la bordure depuis le stockage :

A cause d'un bug dans browser.storage.local.get() dans Firefox pour les versions précédant la 52, le code qui suit ne fonctionnera pas. Pour le faire fonctionner pour les versions de Firefox avant la 52, les deux occurrences d'item.color dans onGot() doivent être changer pour item[0].color.

 function onError(error) {
  console.log(`Error: ${error}`);
}

function onGot(item) {
  var color = "blue";
  if (item.color) {
    color = item.color;
  }
  document.body.style.border = "10px solid " + color;
}

var getting = browser.storage.local.get("color");
getting.then(onGot, onError);

A ce moment, l'extension complète devrait ressembler à ceci :

settings/
    borderify.js
    manifest.json
    options.html
    options.js

Maintenant :

  • Rechargez la WebExtension
  • Chargez un page web
  • Ouvrez la page de paramètres et changez la couleur de la bordure
  • Rechargez la page pour voir la différence

Dans Firefox vous pouvez accéder à la pages des paramètres en visitant about:addons et en cliquant le bouton "Preferences" situé à coté de l'extension.

Pour aller plus loin

Étiquettes et contributeurs liés au document

Étiquettes : 
 Contributeurs à cette page : RoyalPanda
 Dernière mise à jour par : RoyalPanda,