diff options
Diffstat (limited to 'files/fr/mozilla/add-ons/webextensions/your_second_webextension/index.md')
| -rw-r--r-- | files/fr/mozilla/add-ons/webextensions/your_second_webextension/index.md | 340 |
1 files changed, 159 insertions, 181 deletions
diff --git a/files/fr/mozilla/add-ons/webextensions/your_second_webextension/index.md b/files/fr/mozilla/add-ons/webextensions/your_second_webextension/index.md index 597a01e578..801119f818 100644 --- a/files/fr/mozilla/add-ons/webextensions/your_second_webextension/index.md +++ b/files/fr/mozilla/add-ons/webextensions/your_second_webextension/index.md @@ -5,58 +5,53 @@ tags: - WebExtensions translation_of: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension --- -<div>{{AddonSidebar}}</div> +{{AddonSidebar}} -<p>Si vous avez lu l'article <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension">votre première extension</a>, vous avez déjà une idée de la manière d'écrire une extension. Dans cet article, nous allons écrire une extension légèrement plus complexe qui illustre un peu plus les API.</p> +Si vous avez lu l'article [votre première extension](/fr/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension), vous avez déjà une idée de la manière d'écrire une extension. Dans cet article, nous allons écrire une extension légèrement plus complexe qui illustre un peu plus les API. -<p>L'extension ajoute un nouveau bouton à la barre d'outils Firefox. Lorsque l'utilisateur clique sur le bouton, nous affichons une fenêtre contextuelle qui leur permet de choisir un animal. Une fois l'animal choisi, l'extension remplace le contenu de la page actuelle par une image de l'animal choisi.</p> +L'extension ajoute un nouveau bouton à la barre d'outils Firefox. Lorsque l'utilisateur clique sur le bouton, nous affichons une fenêtre contextuelle qui leur permet de choisir un animal. Une fois l'animal choisi, l'extension remplace le contenu de la page actuelle par une image de l'animal choisi. -<p>Pour implémenter ce module, il nous faut :</p> +Pour implémenter ce module, il nous faut : -<ul> - <li><strong>Définir une <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">action du navigateur (<i>browser action</i>)</a>, matérialisée par un bouton dans la barre d'outils de Firefox</strong>. Pour ce bouton, nous avons besoin : - <ul> - <li>d'une icône, nommée "beasts-32.png"</li> - <li>d'une popup qui s'ouvrira lorsqu'on cliquera sur le bouton. La popup sera constituée d'HTML, de CSS et de JavaScript.</li> - </ul> - </li> - <li><strong>Définir l'icône de l'extension,</strong> nommée "beasts-48.png". Elle apparaîtra dans le gestionnaire de module.</li> - <li><strong>Écrire un script de contenu (<i>content script</i>), "beastify.js" qui sera injecté dans les pages web</strong>. C'est le code qui va effectivement transformer les pages.</li> - <li><strong>Packager les images d'animaux, afin de remplacer les images de la page web</strong>. Nous définirons les images comme étant des ressources accessibles par le Web de sorte que la page web puisse y accéder.</li> -</ul> +- **Définir une [action du navigateur (_browser action_)](/fr/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action), matérialisée par un bouton dans la barre d'outils de Firefox**. Pour ce bouton, nous avons besoin : -<p>Voici une visualisation globale possible de la structure du module :</p> + - d'une icône, nommée "beasts-32.png" + - d'une popup qui s'ouvrira lorsqu'on cliquera sur le bouton. La popup sera constituée d'HTML, de CSS et de JavaScript. -<p><img alt="" src="untitled-1.png"></p> +- **Définir l'icône de l'extension,** nommée "beasts-48.png". Elle apparaîtra dans le gestionnaire de module. +- **Écrire un script de contenu (_content script_), "beastify.js" qui sera injecté dans les pages web**. C'est le code qui va effectivement transformer les pages. +- **Packager les images d'animaux, afin de remplacer les images de la page web**. Nous définirons les images comme étant des ressources accessibles par le Web de sorte que la page web puisse y accéder. -<p>Il s'agit d'une extension simple mais qui démontre plusieurs concepts élémentaires de l'API des WebExtensions :</p> +Voici une visualisation globale possible de la structure du module : -<ul> - <li>Ajout d'un bouton à la barre d'outils</li> - <li>Définition d'une popup à l'aide de HTML, CSS et JavaScript</li> - <li>Injection des scripts de contenu dans les pages web</li> - <li>Communication entre les scripts de contenu et le reste de l'extension</li> - <li>Empaquetage de ressources comme les images dans le module afin que celles-ci puissent ensuite être utilisées par les pages web</li> -</ul> + -<p>Le <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">code source complet du module est disponible sur GitHub</a>.</p> +Il s'agit d'une extension simple mais qui démontre plusieurs concepts élémentaires de l'API des WebExtensions : -<p>Afin de tester cette extension, vous aurez besoin de Firefox 45 ou d'une version ultérieure.</p> +- Ajout d'un bouton à la barre d'outils +- Définition d'une popup à l'aide de HTML, CSS et JavaScript +- Injection des scripts de contenu dans les pages web +- Communication entre les scripts de contenu et le reste de l'extension +- Empaquetage de ressources comme les images dans le module afin que celles-ci puissent ensuite être utilisées par les pages web -<h2 id="writing_the_extension">Écrire l'extension</h2> +Le [code source complet du module est disponible sur GitHub](https://github.com/mdn/webextensions-examples/tree/master/beastify). -<p>Créez un nouveau répertoire et positionnez-vous dedans :</p> +Afin de tester cette extension, vous aurez besoin de Firefox 45 ou d'une version ultérieure. -<pre class="brush: bash"> +## Écrire l'extension + +Créez un nouveau répertoire et positionnez-vous dedans : + +```bash mkdir beastify cd beastify -</pre> +``` -<h3 id="manifest.json">manifest.json</h3> +### manifest.json -<p>Créez un nouveau fichier nommé "manifest.json" directement dans le répertoire "beastify" et saisissez-y le contenu suivant :</p> +Créez un nouveau fichier nommé "manifest.json" directement dans le répertoire "beastify" et saisissez-y le contenu suivant : -<pre class="brush: json"> +```json { "manifest_version": 2, @@ -85,105 +80,100 @@ cd beastify "beasts/snake.jpg" ] } -</pre> +``` + +- Les trois premières clés : [`manifest_version`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version), [`name`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name), et [`version`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version), sont obligatoires et contiennent les métadonnées élémentaires nécessaires à l'extension. +- [`description`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/description) and [`homepage_url`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url) sont optionnelles mais recommandées : elles apportent des informations utiles à propos de l'extension. +- [`icons`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons) est optionnelle mais recommandée : elle permet de spécifier l'icône du module qui s'affichera dans le gestionnaire d'extension. +- [`permissions`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) indique les permissions nécessaires à cette extension. Ici, uniquement [la permission `activeTab`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#activetab_permission) est demandée. +- [`browser_action`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action) spécifie le bouton de la barre d'outil. Nous fournissons trois informations : + + - `default_icon` est obligatoire et référence l'icône du bouton + - `default_title` est optionelle et s'affichera dans une bulle d'aide + - `default_popup` est nécessaire si vous souhaitez qu'une popup s'affiche lorsque l'utilisateur clique sur le bouton. C'est notre cas, nous avons donc défini cette clé et l'avons faite pointer sur un fichier HTML inclus dans le module. -<ul> - <li>Les trois premières clés : <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code>, <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name">name</a></code>, et <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version">version</a></code>, sont obligatoires et contiennent les métadonnées élémentaires nécessaires à l'extension.</li> - <li><code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/description">description</a></code> and <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url">homepage_url</a></code> sont optionnelles mais recommandées : elles apportent des informations utiles à propos de l'extension.</li> - <li><code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> est optionnelle mais recommandée : elle permet de spécifier l'icône du module qui s'affichera dans le gestionnaire d'extension.</li> - <li><code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> indique les permissions nécessaires à cette extension. Ici, uniquement <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#activetab_permission">la permission <code>activeTab</code></a> est demandée.</li> - <li><code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> spécifie le bouton de la barre d'outil. Nous fournissons trois informations : - <ul> - <li><code>default_icon</code> est obligatoire et référence l'icône du bouton</li> - <li><code>default_title</code> est optionelle et s'affichera dans une bulle d'aide</li> - <li><code>default_popup</code> est nécessaire si vous souhaitez qu'une popup s'affiche lorsque l'utilisateur clique sur le bouton. C'est notre cas, nous avons donc défini cette clé et l'avons faite pointer sur un fichier HTML inclus dans le module.</li> - </ul> - </li> - <li><code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code> liste les fichiers qui doivent être accessibles aux pages web. Comme cette extension remplace le contenu de la page web par les images incluses dans cette extension, il faut les rendre accessibles à la page.</li> -</ul> +- [`web_accessible_resources`](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) liste les fichiers qui doivent être accessibles aux pages web. Comme cette extension remplace le contenu de la page web par les images incluses dans cette extension, il faut les rendre accessibles à la page. -<p>Il est à noter que tous les chemins sont relatifs au fichier manifest.json.</p> +Il est à noter que tous les chemins sont relatifs au fichier manifest.json. -<h3 id="the_icon">L'icône</h3> +### L'icône -<p>L'extension doit posséder une icône qui sera affichée dans le catalogue des extensions et dans la liste des extensions du navigateur (vous pouvez afficher le gestionnaire en ouvrant l'URL "about:addons"). Le fichier manifest.json a déclaré une icône pour la barre d'outils, "icons/beasts-48.png".</p> +L'extension doit posséder une icône qui sera affichée dans le catalogue des extensions et dans la liste des extensions du navigateur (vous pouvez afficher le gestionnaire en ouvrant l'URL "about:addons"). Le fichier manifest.json a déclaré une icône pour la barre d'outils, "icons/beasts-48.png". -<p>Créez le répertoire "icons" et enregistrez-y une icône nommée "beasts-48.png". Vous pouvez utiliser <a href="https://github.com/mdn/webextensions-examples/raw/master/beastify/icons/beasts-48.png">une image de notre exemple</a>, provenant du jeu d'icônes de <a href="https://www.iconfinder.com/iconsets/free-retina-icon-set">Aha-Soft's Free Retina</a> et utilisable selon les termes de sa <a href="http://www.aha-soft.com/free-icons/free-retina-icon-set/">licence</a>.</p> +Créez le répertoire "icons" et enregistrez-y une icône nommée "beasts-48.png". Vous pouvez utiliser [une image de notre exemple](https://github.com/mdn/webextensions-examples/raw/master/beastify/icons/beasts-48.png), provenant du jeu d'icônes de [Aha-Soft's Free Retina](https://www.iconfinder.com/iconsets/free-retina-icon-set) et utilisable selon les termes de sa [licence](http://www.aha-soft.com/free-icons/free-retina-icon-set/). -<p>Si vous décidez de fournir votre propre icône, sa taille devra être de 48 pixels par 48 pixels. Il vous est aussi possible de fournir une icône de taille 96 pixels par 96 pixels, adaptée aux affichages haute résolution, et, devra dans ce cas, être spécifiée par la propriété <code>96</code> de l'objet <code>icons</code> du manifeste :</p> +Si vous décidez de fournir votre propre icône, sa taille devra être de 48 pixels par 48 pixels. Il vous est aussi possible de fournir une icône de taille 96 pixels par 96 pixels, adaptée aux affichages haute résolution, et, devra dans ce cas, être spécifiée par la propriété `96` de l'objet `icons` du manifeste : -<pre class="brush: json"> +```json "icons": { "48": "icons/beasts-48.png", "96": "icons/beasts-96.png" -}</pre> +} +``` -<h3 id="the_toolbar_button">Le bouton de la barre d'outils</h3> +### Le bouton de la barre d'outils -<p>Une icône est nécessaire pour le bouton de la barre d'outils et le manifeste déclare une icône "icons/beasts-32.png" pour la barre d'outils.</p> +Une icône est nécessaire pour le bouton de la barre d'outils et le manifeste déclare une icône "icons/beasts-32.png" pour la barre d'outils. -<p>Enregistrez une icône nommée "beasts-32.png" dans le répertoire "icons". Vous pouvez utiliser <a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-32.png">une image de notre exemple</a>, provenant du jeu d'icône <a href="http://www.iconbeast.com/free">IconBeast Lite icon</a> et utilisable selon les termes de sa <a href="http://www.iconbeast.com/faq/">licence</a>.</p> +Enregistrez une icône nommée "beasts-32.png" dans le répertoire "icons". Vous pouvez utiliser [une image de notre exemple](https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-32.png), provenant du jeu d'icône [IconBeast Lite icon](http://www.iconbeast.com/free) et utilisable selon les termes de sa [licence](http://www.iconbeast.com/faq/). -<p>Si vous ne fournissez pas de popup, alors un évènement <code>click</code> est propagé au contexte de l'extension lorque l'utilisateur clique sur le bouton. Si une popup est fournie, l'évènement <code>click</code> n'est pas propagé, mais la popup fournie par l'extension s'ouvrira à la place. C'est ce que nous voulons faire ici, créons cette popup.</p> +Si vous ne fournissez pas de popup, alors un évènement `click` est propagé au contexte de l'extension lorque l'utilisateur clique sur le bouton. Si une popup est fournie, l'évènement `click` n'est pas propagé, mais la popup fournie par l'extension s'ouvrira à la place. C'est ce que nous voulons faire ici, créons cette popup. -<h3 id="the_popup">La popup</h3> +### La popup -<p>Le but de la popup est de permettre à l'utilisateur de choisir une des trois bêtes.</p> +Le but de la popup est de permettre à l'utilisateur de choisir une des trois bêtes. -<p>Créez un nouveau répertoire nommé "popup" à la racine de l'extension. Ce sera l'emplacement du code de la popup. La popup sera constituée de trois fichiers :</p> +Créez un nouveau répertoire nommé "popup" à la racine de l'extension. Ce sera l'emplacement du code de la popup. La popup sera constituée de trois fichiers : -<ul> - <li><strong><code>choose_beast.html</code></strong> qui définit le contenu du panneau</li> - <li><strong><code>choose_beast.css</code></strong> qui met en forme le contenu de ce panneau</li> - <li><strong><code>choose_beast.js</code></strong> qui gére le choix de l'utilisateur en exécutant un script de contenu dans l'onglet actif du navigateur</li> -</ul> +- **`choose_beast.html`** qui définit le contenu du panneau +- **`choose_beast.css`** qui met en forme le contenu de ce panneau +- **`choose_beast.js`** qui gére le choix de l'utilisateur en exécutant un script de contenu dans l'onglet actif du navigateur -<pre class="brush: bash"> +```bash mkdir popup cd popup touch choose_beast.html choose_beast.css choose_beast.js -</pre> - +``` -<h4 id="choose_beast.html">choose_beast.html</h4> +#### choose_beast.html -<p>Voici le contenu du fichier HTML :</p> +Voici le contenu du fichier HTML : -<pre class="brush: html"> -<!DOCTYPE html> +```html +<!DOCTYPE html> -<html> - <head> - <meta charset="utf-8"> - <link rel="stylesheet" href="choose_beast.css"/> - </head> +<html> + <head> + <meta charset="utf-8"> + <link rel="stylesheet" href="choose_beast.css"/> + </head> -<body> - <div id="popup-content"> - <div class="button beast">Grenouille</div> - <div class="button beast">Tortue</div> - <div class="button beast">Serpent</div> - <div class="button reset">Réinitialiser</div> - </div> - <div id="error-content" class="hidden"> - <p>Cette page ne peut être transformée.</p> - <p>Veuillez essayer une autre page.</p> - </div> - <script src="choose_beast.js"></script> -</body> +<body> + <div id="popup-content"> + <div class="button beast">Grenouille</div> + <div class="button beast">Tortue</div> + <div class="button beast">Serpent</div> + <div class="button reset">Réinitialiser</div> + </div> + <div id="error-content" class="hidden"> + <p>Cette page ne peut être transformée.</p> + <p>Veuillez essayer une autre page.</p> + </div> + <script src="choose_beast.js"></script> +</body> -</html> -</pre> +</html> +``` -<p>On a un élément <code><a href="/fr/docs/Web/HTML/Element/div"><div></a></code> dont l'identifiant (<code>id</code>) vaut <code>"popup-content"</code> et qui contient un élément pour chaque choix d'animal. On a également un autre <code><div></code> avec l'identifiant <code>"error-content"</code> et une classe <code>"hidden"</code>. Nous utiliserons cet élément au cas où il y ait un problème à l'initialisation de la popup.</p> +On a un élément [`<div>`](/fr/docs/Web/HTML/Element/div) dont l'identifiant (`id`) vaut `"popup-content"` et qui contient un élément pour chaque choix d'animal. On a également un autre `<div>` avec l'identifiant `"error-content"` et une classe `"hidden"`. Nous utiliserons cet élément au cas où il y ait un problème à l'initialisation de la popup. -<p>Il est à noter que le ficher CSS et le fichier JS sont inclus depuis ce fichier, tout comme une page web normale.</p> +Il est à noter que le ficher CSS et le fichier JS sont inclus depuis ce fichier, tout comme une page web normale. -<h4 id="choose_beast.css">choose_beast.css</h4> +#### choose_beast.css -<p>Le CSS fixe la taille de la popup, s'assure que les trois choix remplissent l'espace et les met en forme de façon élémentaire. C'est aussi le CSS qui masque les éléments avec <code>class="hidden"</code>, cela signifie que l'élément <code><div></code> <code>"error-content"</code> sera masqué par défaut :</p> +Le CSS fixe la taille de la popup, s'assure que les trois choix remplissent l'espace et les met en forme de façon élémentaire. C'est aussi le CSS qui masque les éléments avec `class="hidden"`, cela signifie que l'élément `<div>` `"error-content"` sera masqué par défaut : -<pre class="brush: css"> +```css html, body { width: 100px; } @@ -215,28 +205,28 @@ html, body { .reset:hover { background-color: #EAEA9D; } -</pre> +``` -<h4 id="choose_beast.js">choose_beast.js</h4> +#### choose_beast.js -<pre class="brush: js"> +```js /** * On utilise CSS pour masquer tout ce qui se trouve sur la * page sauf les éléments avec la classe "beastify-image". */ -const hidePage = `body > :not(.beastify-image) { +const hidePage = `body > :not(.beastify-image) { display: none; }`; /** - * On écoute les clics sur les boutons et on envoie + * On écoute les clics sur les boutons et on envoie * un message approprié au script de contenu dans la page */ function listenForClicks() { - document.addEventListener("click", (e) => { + document.addEventListener("click", (e) => { /** - * Selon le nom de la bête, on fournit l'URL vers + * Selon le nom de la bête, on fournit l'URL vers * l'image correspondante. */ function beastNameToURL(beastName) { @@ -257,7 +247,7 @@ function listenForClicks() { * dans l'onglet actif. */ function beastify(tabs) { - browser.tabs.insertCSS({code: hidePage}).then(() => { + browser.tabs.insertCSS({code: hidePage}).then(() => { let url = beastNameToURL(e.target.textContent); browser.tabs.sendMessage(tabs[0].id, { command: "beastify", @@ -272,7 +262,7 @@ function listenForClicks() { * l'onglet actif. */ function reset(tabs) { - browser.tabs.removeCSS({code: hidePage}).then(() => { + browser.tabs.removeCSS({code: hidePage}).then(() => { browser.tabs.sendMessage(tabs[0].id, { command: "reset", }); @@ -322,39 +312,33 @@ function reportExecuteScriptError(error) { browser.tabs.executeScript({file: "/content_scripts/beastify.js"}) .then(listenForClicks) .catch(reportExecuteScriptError); -</pre> +``` + +Pour commencer, le script de la popup exécute un script de contenu dans l'onglet actif dès que la popup est chargée grâce à la méthode [`browser.tabs.executeScript()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript). Si l'exécution du script est réussie, le script de contenu sera chargé dans la page jusqu'à ce que l'onglet soit fermé ou que l'utilisateur navigue sur une autre page. + +On peut avoir des erreurs lors de l'appel à `browser.tabs.executeScript()` car il est impossible d'exécuter des scripts de contenu sur certaines pages. On ne peut, par exemple, pas en exécuter pour certaines pages privilégiées comme about:debugging ou sur des pages du domaine [addons.mozilla.org](https://addons.mozilla.org/). Si un tel échec se produit, `reportExecuteScriptError()` masquera l'élément avec `"popup-content"` et affichera celui avec `"error-content"` puis enregistrera une erreur dans [la console](https://extensionworkshop.com/documentation/develop/debugging/). -<p>Pour commencer, le script de la popup exécute un script de contenu dans l'onglet actif dès que la popup est chargée grâce à la méthode <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">browser.tabs.executeScript()</a></code>. Si l'exécution du script est réussie, le script de contenu sera chargé dans la page jusqu'à ce que l'onglet soit fermé ou que l'utilisateur navigue sur une autre page.</p> +Si l'exécution du script de contenu réussit, la méthode `listenForClicks()` est appelée. Celle-ci permet d'écouter les clics sur la popup. -<p>On peut avoir des erreurs lors de l'appel à <code>browser.tabs.executeScript()</code> car il est impossible d'exécuter des scripts de contenu sur certaines pages. On ne peut, par exemple, pas en exécuter pour certaines pages privilégiées comme about:debugging ou sur des pages du domaine <a href="https://addons.mozilla.org/">addons.mozilla.org</a>. Si un tel échec se produit, <code>reportExecuteScriptError()</code> masquera l'élément avec <code>"popup-content"</code> et affichera celui avec <code>"error-content"</code> puis enregistrera une erreur dans <a href="https://extensionworkshop.com/documentation/develop/debugging/">la console</a>.</p> - -<p>Si l'exécution du script de contenu réussit, la méthode <code>listenForClicks()</code> est appelée. Celle-ci permet d'écouter les clics sur la popup.</p> - -<ul> - <li>Si le clic a lieu sur un bouton avec <code>class="beast"</code>, on appelle <code>beastify()</code>.</li> - <li>Si le clic a lieu sur un bouton avec <code>class="reset"</code>, on appelle <code>reset()</code>.</li> -</ul> +- Si le clic a lieu sur un bouton avec `class="beast"`, on appelle `beastify()`. +- Si le clic a lieu sur un bouton avec `class="reset"`, on appelle `reset()`. -<p>La fonction <code>beastify()</code> fait trois choses :</p> +La fonction `beastify()` fait trois choses : -<ul> - <li>Correspondre le bouton qui a reçu le clic avec l'URL d'une image correspondant à la bête choisie</li> - <li>Masquer tout le contenu de la page en injectant du CSS avec <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS">browser.tabs.insertCSS()</a></code></li> - <li>Envoyer un message "beastify" au script de contenu avec <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">browser.tabs.sendMessage()</a></code> pour lui demander de transformer la page en lui passant l'URL de l'image pour la bête sélectionnée.</li> -</ul> +- Correspondre le bouton qui a reçu le clic avec l'URL d'une image correspondant à la bête choisie +- Masquer tout le contenu de la page en injectant du CSS avec [`browser.tabs.insertCSS()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS) +- Envoyer un message "beastify" au script de contenu avec [`browser.tabs.sendMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage) pour lui demander de transformer la page en lui passant l'URL de l'image pour la bête sélectionnée. -<p>La fonction <code>reset()</code> annule la transformation de l'onglet courant en :</p> +La fonction `reset()` annule la transformation de l'onglet courant en : -<ul> - <li>Retirant le CSS ajouté grâce à <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/removeCSS">browser.tabs.removeCSS()</a></code></li> - <li>Envoyant un message "reset" au script de contenu pour lui demander de réinitialiser la page.</li> -</ul> +- Retirant le CSS ajouté grâce à [`browser.tabs.removeCSS()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/tabs/removeCSS) +- Envoyant un message "reset" au script de contenu pour lui demander de réinitialiser la page. -<h3 id="the_content_script">Le script de contenu (<i>content script</i>)</h3> +### Le script de contenu (_content script_) -<p>Créez un nouveau répertoire sous la racine du module nommé "content_scripts" et créez un nouveau fichier nommé "beastify.js", contenant :</p> +Créez un nouveau répertoire sous la racine du module nommé "content_scripts" et créez un nouveau fichier nommé "beastify.js", contenant : -<pre class="brush: js"> +```js (function() { /** * On vérifie et on initialise une variable globale @@ -395,7 +379,7 @@ browser.tabs.executeScript({file: "/content_scripts/beastify.js"}) * On écoute les messages du script d'arrière-plan pour * déclencher "insertBeast()" ou "removeExistingBeasts()". */ - browser.runtime.onMessage.addListener((message) => { + browser.runtime.onMessage.addListener((message) => { if (message.command === "beastify") { insertBeast(message.beastURL); } else if (message.command === "reset") { @@ -403,78 +387,72 @@ browser.tabs.executeScript({file: "/content_scripts/beastify.js"}) } }); })(); -</pre> +``` -<p>La première chose que fait le script de contenu est de vérifier une variable globale <code>window.hasRun</code> : si elle est déjà définie, le script rend la main et sinon, il définit <code>window.hasRun</code> puis continue. On fait ceci pour éviter que la popup exécute un script de contenu à chaque fois que l'utilisateur ouvre la popup (y compris pour le même onglet) afin d'éviter d'avoir plusieurs instances du script dans le même onglet. Si un utilisateur ouvre plusieurs fois la popup, on doit s'assurer que c'est bien la première instance du script qui gère ce qui se passe.</p> +La première chose que fait le script de contenu est de vérifier une variable globale `window.hasRun` : si elle est déjà définie, le script rend la main et sinon, il définit `window.hasRun` puis continue. On fait ceci pour éviter que la popup exécute un script de contenu à chaque fois que l'utilisateur ouvre la popup (y compris pour le même onglet) afin d'éviter d'avoir plusieurs instances du script dans le même onglet. Si un utilisateur ouvre plusieurs fois la popup, on doit s'assurer que c'est bien la première instance du script qui gère ce qui se passe. -<p>Après ça, on voit plus loin que le script de contenu utilise <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code>. Cela permet de faire le lien avec le script de popup qui envoyait deux messages : "beastify" et "reset".</p> +Après ça, on voit plus loin que le script de contenu utilise [`browser.runtime.onMessage`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage). Cela permet de faire le lien avec le script de popup qui envoyait deux messages : "beastify" et "reset". -<ul> - <li>Si le message est "beastify", on s'attend à ce que celui-ci contienne une URL pointant vers une image. On supprime alors toute image de bête ayant été placée par d'éventuels appels précédents puis on construit et on ajoute un élément <code><a href="/fr/docs/Web/HTML/Element/Img"><img></a></code> dont l'attribut <code>src</code> est défini avec l'URL pointant vers l'image de la bête sélectionnée.</li> - <li>Si le message est "reset", on retire toute image de bête ayant été ajoutée.</li> -</ul> +- Si le message est "beastify", on s'attend à ce que celui-ci contienne une URL pointant vers une image. On supprime alors toute image de bête ayant été placée par d'éventuels appels précédents puis on construit et on ajoute un élément [`<img>`](/fr/docs/Web/HTML/Element/Img) dont l'attribut `src` est défini avec l'URL pointant vers l'image de la bête sélectionnée. +- Si le message est "reset", on retire toute image de bête ayant été ajoutée. -<h3 id="the_beasts">Les bêtes</h3> +### Les bêtes -<p>Enfin, nous devons inclure les images d'animaux.</p> +Enfin, nous devons inclure les images d'animaux. -<p>Créez un nouveau répertoire nommé "beasts", et ajoutez-y les trois images, nommées de façon appropriée. Vous pouvez récupérer les images du <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify/beasts">dépôt GitHub</a>, ou bien ci-après :</p> +Créez un nouveau répertoire nommé "beasts", et ajoutez-y les trois images, nommées de façon appropriée. Vous pouvez récupérer les images du [dépôt GitHub](https://github.com/mdn/webextensions-examples/tree/master/beastify/beasts), ou bien ci-après : -<p><img alt="" src="frog.jpg"><img alt="" src="snake.jpg"><img alt="" src="turtle.jpg"></p> + -<h2 id="testing_it_out">Test</h2> +## Test -<p>D'abord, vérifiez de nouveau que les bons fichiers sont au bon endroit :</p> +D'abord, vérifiez de nouveau que les bons fichiers sont au bon endroit : -<pre> -beastify/ + beastify/ - beasts/ - frog.jpg - snake.jpg - turtle.jpg + beasts/ + frog.jpg + snake.jpg + turtle.jpg - content_scripts/ - beastify.js + content_scripts/ + beastify.js - icons/ - beasts-32.png - beasts-48.png + icons/ + beasts-32.png + beasts-48.png - popup/ - choose_beast.css - choose_beast.html - choose_beast.js + popup/ + choose_beast.css + choose_beast.html + choose_beast.js - manifest.json -</pre> + manifest.json -<p>A partir de Firefox version 45, il est possible d'installer les WebExtensions temporairement.</p> +A partir de Firefox version 45, il est possible d'installer les WebExtensions temporairement. -<p>Ouvrez "about:debugging" dans Firefox, cliquez sur "Charger un module complémentaire temporaire", et choisissez le fichier manifest.json. Vous devriez voir apparaitre l'icône du module dans la barre d'outils de Firefox :</p> +Ouvrez "about:debugging" dans Firefox, cliquez sur "Charger un module complémentaire temporaire", et choisissez le fichier manifest.json. Vous devriez voir apparaitre l'icône du module dans la barre d'outils de Firefox : -<p>{{EmbedYouTube("sAM78GU4P34")}}</p> +{{EmbedYouTube("sAM78GU4P34")}} -<p>Ouvrez une page web et cliquez sur l'icône, sélectionnez une bête et observez la page web se modifier :</p> +Ouvrez une page web et cliquez sur l'icône, sélectionnez une bête et observez la page web se modifier : -<p>{{EmbedYouTube("YMQXyAQSiE8")}}</p> +{{EmbedYouTube("YMQXyAQSiE8")}} -<h2 id="developing_from_the_command_line">Développement depuis la ligne de commande</h2> +## Développement depuis la ligne de commande -<p>Il est possible d'automatiser l'installation temporaire de modules, étape par étape en utilisant l'outil <a href="https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/">web-ext</a> tool. Essayez ainsi :</p> +Il est possible d'automatiser l'installation temporaire de modules, étape par étape en utilisant l'outil [web-ext](https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/) tool. Essayez ainsi : -<pre class="brush: bash"> +```bash cd beastify web-ext run -</pre> +``` -<h2 id="whats_next">Et ensuite ?</h2> +## Et ensuite ? -<p>Maitenant que vous avez créé une WebExtension avancée pour Firefox, vous pouvez :</p> +Maitenant que vous avez créé une WebExtension avancée pour Firefox, vous pouvez : -<ul> - <li><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">Explorer l'anatomie d'une extension</a></li> - <li><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Examples">Explorer les exemples d'extension</a></li> - <li><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/What_next_">Découvrir ce dont vous avez besoin pour développer, tester et publier votre extension</a></li> - <li><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/What_next_#continuez_votre_exp%c3%a9rience_d'apprentissage">Approfondir votre apprentissage</a>.</li> -</ul> +- [Explorer l'anatomie d'une extension](/fr/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension) +- [Explorer les exemples d'extension](/fr/docs/Mozilla/Add-ons/WebExtensions/Examples) +- [Découvrir ce dont vous avez besoin pour développer, tester et publier votre extension](/fr/docs/Mozilla/Add-ons/WebExtensions/What_next_) +- [Approfondir votre apprentissage](/fr/docs/Mozilla/Add-ons/WebExtensions/What_next_#continuez_votre_exp%c3%a9rience_d'apprentissage). |