Construire une extension

  • Raccourci de la révision : Construire_une_extension
  • Titre de la révision : Construire une extension
  • ID de la révision : 122114
  • Créé :
  • Créateur : Chbok
  • Version actuelle ? Non
  • Commentaire demande de relecture

Contenu de la révision

{{wiki.template('Traduction_à_relire')}} (Chbok 2 jul 2006 à 06:03 (PDT) : Vérifier les liens et captures écran à faire)

Introduction

Ce tutoriel va vous présenter les étapes requises pour construire une extension très basique, qui ajoute un bouton contenant le texte « Salut tout le monde ! » à la Barre d'état du navigateur Firefox.

Note : Ce tutoriel traite de la construction d'extensions pour Firefox 1.5. D'autres tutoriaux existent pour construire des extensions destinées à des versions plus anciennes de Firefox.

Configuration de l'environnement de développement

Les extensions sont packagées et distribuées dans des fichiers ZIP, ou Bundles, avec l'extension <tt>xpi</tt> (prononcé « zippy »). Le contenu d'un fichier XPI s'arrange de la manière suivante :

extension.xpi :
              /install.rdf
              /components/*
              /components/cmdline.js
              /defaults/
              /defaults/preferences/*.js
              /plugins/*
              /chrome.manifest
              /chrome/icons/default/*
              /chrome/
              /chrome/content/

Par conséquent, il est plus facile de disposer vos fichiers sources selon une méthode similaire, à moins que vous ne désiriez écrire quelque Makefile ou script shell pour packager et zipper tous vos fichiers. Mais même si c'est dans vos cordes, les tests sont plus simples en arrangeant vos fichiers de cette manière à cause d'une particularité du système d'ajout de Firefox 1.5.

Bien, commençons. Créez un dossier pour votre extension quelque part sur votre disque dur, par exemple <tt>C:\extensions\monExtension\</tt> ou <tt>~/extensions/monExtension/</tt>. Dans celui-ci, créez un autre dossier nommé <tt>chrome</tt>, et dans ce dernier créez un dossier nommé <tt>content</tt>. (Dans les systèmes Unix, il est habituellement possible de créer ces trois répertoires à la fois en lançant juste <tt>mkdir -p chrome/content</tt> depuis le répertoire racine de l'extension.)

À la racine du dossier de votre extension, au même niveau que le dossier <tt>chrome</tt>, créez deux nouveaux fichiers texte vides, l'un appelé <tt>chrome.manifest</tt> et l'autre appelé <tt>install.rdf</tt>.

Vous trouverez plus d'astuces sur la mise en place d'un environnement de développement dans la Mozillazine Knowledge Base.

Créer le manifeste d'installation

Ouvrez le fichier nommé <tt>install.rdf</tt> que vous avez créé au premier niveau de la hiérarchie de dossiers de votre extension, et placez ceci à l'intérieur :

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>sample@foo.net</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
   
    <!-- L'application cible de votre extension, 
         avec les versions minimums et maximums supportées. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.0+</em:minVersion>
        <em:maxVersion>1.5.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Méta-données visibles -->
    <em:name>Exemple</em:name>
    <em:description>Une extension test</em:description>
    <em:creator>Votre nom ici</em:creator>
    <em:homepageURL>http://www.foo.com/</em:homepageURL>
  </Description>      
</RDF>

sample@foo.net - L'ID de votre extension. C'est une valeur que vous inventez pour identifier votre extension dans un format d'adresse email (attention, il ne doit pas s'agir de votre email). Il faut qu'il soit unique. Vous pouvez également utiliser un GUID.

Spécifiez <tt><em:type>2</em:type></tt> -- le 2 indique que c'est une extension qui est décrite (voir Manifestes d'installation#type pour les autres codes de type).

{ec8030f7-c20a-464f-9b0e-13a3a9e97384} - L'ID de l'application Firefox.

1.0+ - la version minimum de Firefox avec laquelle votre extension fonctionnera. C'est la version minimum avec laquelle vous vous engagez à tester et corriger les bogues.

1.5.0.* - La version maximum de Firefox avec laquelle votre extension fonctionnera. Elle ne doit pas être supérieure à la dernière version courante !

Voir les manifestes d'installation pour une liste complète des propriétés requises et optionnelles.

Enregistrez le fichier.

Extension du navigateur avec XUL

L'interface utilisateur de Firefox est écrite en XUL et JavaScript. Le XUL est une grammaire XML qui fournit des éléments d'interface comme des boutons, des menus, des barres d'outils, des arbres, etc. Les actions utilisateur sont liées à des fonctionnalités utilisant JavaScript.

Pour modifier le navigateur, on remanie des parties de l'interface utilisateur (UI) du navigateur en ajoutant ou modifiant des éléments. Des contrôles sont ajoutés en insérant de nouveaux éléments DOM XUL dans la fenêtre du navigateur, et peuvent être modifiés en utilisant des scripts et en attachant des gestionnaires d'événements.

Le navigateur est implémenté dans un fichier XUL nommé <tt>browser.xul</tt> (<tt>content/browser/browser.xul</tt> se trouve dans <tt>$FIREFOX_INSTALL_DIR/chrome/browser.jar</tt>). Dans browser.xul, nous pouvons trouver la Barre d'état, qui ressemble à quelque chose de ce genre :

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<tt><statusbar id="status-bar"></tt> est un « point de fusion » pour un overlay XUL.

Les overlays XUL

Les overlays XUL sont un moyen d'attacher d'autres éléments d'interface utilisateur à un document XUL au moment de l'exécution. Un overlay XUL est un fichier .xul qui spécifie des fragments de XUL à insérer dans des points de fusion spécifiques au sein d'un document « maître ». Ces fragments peuvent spécifier des élements d'interface à insérer, supprimer ou modifier.

Exemple de document overlay XUL

<?xml version="1.0"?>
<overlay id="sample" 
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Salut tout le monde"/>
 </statusbar>
</overlay>

L'élément <tt><statusbar></tt> nommé par l'identifiant <tt>status-bar</tt> spécifie le « point de fusion » auquel nous voulons nous fixer au sein de la fenêtre du navigateur.

L'enfant <tt><statusbarpanel></tt> est un nouvel élément d'interface que nous désirons insérer au sein du point de fusion.

Prenez l'exemple de code ci-dessus et enregistrez le dans un fichier nommé <tt>exemple.xul</tt> dans le dossier <tt>chrome/content</tt> que vous avez créé.

Voir plus bas pour plus d'informations au sujet de la fusion d'éléments d'interface et de la modification de l'interface utilisateur en utilisant des overlays.

Les URI chrome

Les fichiers XUL font parti des « packages chrome » - ensemble de composants d'interface utilisateur qui sont chargés via des URI <tt>chrome://</tt>. Plutôt que de charger le navigateur à partir du disque en utilisant les URI <tt>file://</tt> (puisque la localisation de Firefox sur le système peut changer selon les plateformes et les systèmes), les développeurs Mozilla ont trouvé une solution pour créer des URI que l'application installée connaît pour le contenu XUL.

Le navigateur est : <tt>chrome://browser/content/browser.xul</tt> Essayez de rentrer cette URL dans la Barre d'adresse de Firefox !

Les URI chrome comprennent plusieurs composants :

  • Premièrement, le schéma URI (<tt>chrome</tt>) qui explique à la bibliothèque réseau de Firefox qu'il s'agit d'une URI chrome et que le contenu qui sera chargé doit être manipulé d'une certaine manière.
  • Deuxièmement, un nom de package (dans l'exemple ci-dessus, <tt>browser</tt> qui identifie le paquet de composants d'interface utilisateur). Il doit être aussi spécifique à votre extension que possible, afin d'éviter les collisions entre extensions.
  • Troisièmement, le type de données requis. Il y a trois types : <tt>content</tt> (XUL, JavaScript, bindings XML XBL, etc., qui forme la structure et le comportement d'une UI d'application), <tt>locale</tt> (DTD, fichiers .properties, etc. qui contiennent les chaînes de caractères pour la localisation de l'UI), et <tt>skin</tt> (CSS et images qui forment le thème de l'UI).
  • Enfin, un nom de fichier à charger.

Donc, <tt>chrome://foo/skin/bar.png</tt> charge le fichier <tt>bar.png</tt> de la section thème <tt>skin</tt> de <tt>foo</tt>.

Quand du contenu est chargé à l'aide d'une URI chrome, Firefox utilise le registre chrome pour traduire ces URI en adresses de fichiers sources réels sur le disque (ou dans les packages JAR).

Créer un fichier chrome.manifest

Pour plus d'informations sur les fichiers chrome.manifest et les propriétés qu'ils permettent, voir la référence sur les enregistrements chrome.

Ouvrez le fichier nommé <tt>chrome.manifest</tt> que vous avez créé au même niveau que le répertoire <tt>chrome</tt>, à la racine de la hiérarchie du dossier source de votre extension.

Ajoutez ce code :

content     exemple    chrome/content/

(N'oubliez pas la barre oblique finale, "<tt>/</tt>"! Sans elle, l'extension ne sera pas chargée.)

Ceci spécifie :

  1. le type de données au sein d'un package chrome
  2. le nom du package chrome
  3. l'emplacement des fichiers du package chrome

Donc, cette ligne indique que pour le package chrome exemple, nous pouvons trouver ses fichiers content à l'emplacement <tt>chrome/chromeFiles/content</tt> qui est un chemin relatif à l'emplacement du <tt>chrome.manifest</tt>.

Notez que les fichiers content, locale et skin doivent être maintenus dans des dossiers nommés content, locale et skin au sein de votre sous-répertoire <tt>chrome</tt>.

Enregistrez le fichier. Quand vous lancerez Firefox avec votre extension (ceci sera expliqué plus loin dans le tutoriel), il enregistrera le package chrome.

Enregistrer un overlay

Il est nécessaire que Firefox fusionne votre overlay avec la fenêtre du navigateur à chaque fois qu'il affiche celle-ci. Ajoutez donc cette ligne à votre fichier <tt>chrome.manifest</tt> :

overlay chrome://browser/content/browser.xul chrome://exemple/content/exemple.xul

Cette ligne indique à Firefox de fusionner <tt>exemple.xul</tt> dans <tt>browser.xul</tt> lorsque <tt>browser.xul</tt> est chargé.

Test

Tout d'abord, il faut indiquer au navigateur comment trouver votre extension. Dans les jours sombres de Firefox 1.0, cela signifiait un empaquetage de l'extension en un XPI et une installation via l'interface utilisateur, ce qui était franchement fastidieux. À présent, c'est devenu plus simple.

  1. Ouvrez le dossier des profils http://kb.mozillazine.org/Profile_folder (en)
  2. Ouvrez le dossier extensions (ou créez le s'il n'existe pas)
  3. Créez un nouveau fichier texte portant le même nom que l'id de votre extension (par exemple <tt>sample@foo.net</tt>), et mettez y le chemin vers le dossier de votre extension (par exemple <tt>C:\extensions\monExtension\</tt> ou <tt>~/extensions/monExtension</tt>)

Votre extension est maintenant prête à être testée !

(Re)démarrez Firefox. Firefox détectera le lien textuel vers votre extension, et l'installera. À l'apparition du navigateur, vous devriez voir le texte « Salut tout le monde! » dans la Barre d'état (en bas à droite.)

Vous pouvez maintenant revenir dans le fichier .xul pour faire d'autres modifications, qui apparaitront après un redémarage.

Image:Helloworld_tools_menu.png Image:Helloworld_extensions_wnd.png

Empaquetage

Maintenant que votre extension fonctionne, vous pouvez l'empaqueter.

Compressez au format zip le contenu du dossier de votre extension (pas le dossier de l'extension lui-même), et renommez le fichier zip pour avoir une extension en .xpi. Sous Windows XP, cela peut se faire facilement en sélectionnant tous les fichiers et sous-dossiers du dossier de votre extension, en faisant un clic droit et en choisissant « Envoyer vers -> Dossier Compressé ». Un fichier .zip sera crée pour vous. Renommez le, et c'est terminé.

À présent, chargez le .xpi sur votre serveur, en vérifiant qu'il est distribué en tant qu'<tt>application/x-xpinstall</tt>. Vous pouvez créer un lien pour permettre aux personnes intéressées de le télécharger et de l'installer.

Utilisation de addons.mozilla.org

Mozilla Update est un site de distribution où il est possible d'héberger vos extensions gratuitement. Votre extension sera conservée sur le site mirroir de Mozilla pour en garantir la disponibilité de téléchargement, même si elle devenait très populaire. Le site propose également aux utilisateurs une installation facile, et distribuera automatiquement les mises à jour. En plus de cela, il permet aux utilisateurs de commenter et de vous envoyer un retour d'expérience sur votre extension. Il est fortement recommandé d'utiliser Mozilla Update pour distribuer vos extensions.

Visitez http://addons.mozilla.org/developers/ pour créer un compte et commencer à distribuer vos extensions.

Note : Votre extension sera validée plus rapidement et téléchargée plus souvent si vous donnez une bonne description et quelques captures d'écran de l'extension en action.

Enregistrement d'extensions dans le registre de Windows

Sous Windows, des informations à propos des extensions peuvent être ajoutées à la base de registres, et ces extensions seront identifiées automatiquement repérées au prochain démarrage de l'application. Cela permet aux programmes d'installation d'applications externes d'ajouter facilement des points d'accès à leurs commandes sous la forme d'une extension. Consultez Ajout d'extensions avec la base de registres de Windows pour plus d'informations.

Plus d'informations sur les overlays XUL

En plus d'ajouter des contrôles d'interface utilisateur au point de fusion, il est possible d'utiliser des fragments XUL au sein d'overlays afin de :

  • Modifier des attributs sur le point de fusion, par exemple <tt><statusbar id="status-bar" hidden="true"/></tt> (masque la barre d'état)
  • Retirer le point de fusion du document maître, par exemple <tt><statusbar id="status-bar" removeelement="true"/></tt>
  • Contrôler la position des contrôles insérés :
<statusbarpanel position="1" .../>

<statusbarpanel insertbefore="autre-id" .../>

<statusbarpanel insertafter="autre-id" .../>

Création de nouveaux composants d'interface utilisateur

Il est possible de créer vos propres fenêtres et boîtes de dialogues en tant que fichiers .xul séparés, de fournir des fonctionnalités en implémentant des actions utilisateur dans des fichiers .js et d'utiliser des méthodes DOM pour manipuler des contrôles UI. Vous pouvez également utiliser des règles de style dans des fichiers .css pour attacher des images, définir des couleurs etc.

Consultez la documentation XUL pour plus de ressources pour les développeurs XUL.

Fichiers par défaut

Les fichiers par défaut utilisés pour constituer le profil d'un utilisateur doivent être placés dans le dossier <tt>defaults/</tt> à la racine de la hiérarchie du dossier de votre extension. Les fichiers .js de préférences par défaut doivent se trouver dans <tt>defaults/preferences/</tt> - lorsqu'ils y sont placés il seront chargés automatiquement par le système de préférences de Firefox à son démarrage afin d'être accessibles via l'API de préférences.

Composants XPCOM

Firefox permet d'utiliser des composants XPCOM dans les extensions. De nouveaux composants peuvent être implémentées facilement en JavaScript, ou en C++ (à l'aide du SDK Gecko).

Placez tous vos fichiers .js ou .dll dans le répertoire <tt>components/</tt> - ils sont automatiquement enregistrés au premier démarrage de Firefox après l'installation de votre extension.

Lancement de l'application en ligne de commande

Une des utilisations possibles de nouveaux composants XPCOM est d'ajouter un paramètre de ligne de commande à Firefox ou Thunderbird. Cette technique peut être utilisée pour lancer une extension comme s'il s'agissait d'une application :

 firefox.exe -myapp

Ceci devrait se trouver dans la page Ligne de commande. Cela se fait en ajoutant un composant contenant la fonction... function NSGetModule(comMgr, fileSpec) { return myAppHandlerModule; } Cette fonction est exécutée par Firefox à chaque lancement de l'application. Firefox enregistre myAppHandlerModule en appelant sa fonction 'registerSelf()'. Ensuite, la factory de myAppHandlerModule est obtenue via 'getClassObject()'. Celle-ci est alors utilisée pour créer le handle avec sa fonction 'createInstance(). Enfin, la fonction 'handle(cmdline)' traite la ligne de commande cmdline avecses fonctions handleFlagWithParam() et handleFlag().

Consultez Chrome: Ligne de commande et ce sujet de forum pour plus de détails.

Localisation

Pour gérer plus d'une langue, vous devez séparer les chaînes de caractères de votre contenu à l'aide d'entités et de string bundles. Il est beaucoup plus facile de faire au moment du développement de l'extension que d'y revenir par la suite.

Les informations de localisation sont stockées dans le répertoire locale de l'extension. Par exemple, pour ajouter une locale à notre extension, créez un répertoire appelé "locale" dans chrome (là où se trouve le répertoire "content") et ajoutez la ligne suivante au fichier chrome.manifest :

 locale sample sampleLocale chrome/locale/

Pour créer des valeurs d'attributs localisables en XUL, placez les valeurs dans un fichier <tt>.ent</tt> (ou un fichier <tt>.dtd</tt>) placé dans le répertoire locale, qui devrait ressembler à ceci :

<!ENTITY  button.label     "Cliquez ici">
<!ENTITY  button.accesskey "C">

Incluez-le ensuite en haut de votre document XUL (juste en dessous de <?xml version"1.0"?>), comme ceci :

<!DOCTYPE window SYSTEM "chrome://packagename/locale/filename.ent">

window est la valeur localName de l'élément racine du document XUL, et la valeur de la propriété <tt>SYSTEM</tt> est l'URI chrome du fichier d'entités. Dans notre exemple, l'élément racine est overlay.

Pour utiliser les entités, modifiez votre XUL pour qu'il ressemble à ceci :

<button label="&button.label;" accesskey="&button.accesskey;"/>

Le registre chrome s'assurera que le fichier d'entités sera chargé du paquet de localisation correspondant à la locale sélectionnée.

Pour les chaînes que vous utilisez dans des scripts, créez un fichier .properties, un fichier texte ayant une chaîne sur chaque ligne dans ce format :

clé=valeur

et utilisez ensuite <tt>nsIStringBundleService</tt>/<tt>nsIStringBundle</tt> ou la balise <tt><stringbundle></tt> pour charger les valeurs dans le script.

Comprendre le navigateur

Utilisez l'inspecteur DOM (ne fait pas partie de l'installation Standard de Firefox, vous devrez le réinstaller en choisissant l'installation personnalisée et choisir Outils de développement si l'élément « Inspecteur DOM » n'est pas présent dans le menu Outils de votre navigateur) pour examiner la fenêtre du navigateur ou toute autre fenêtre XUL que vous désirez étendre.

Utilisez le bouton de recherche de nœuds par pointage et clic en haut à gauche de la barre d'outils de l'inspecteur DOM pour cliquer sur un élément de la fenêtre XUL afin de le sélectionner. Lorsque vous effectuez cette manipulation, l'arbre hiérarchique DOM de l'inspecteur DOM se positionnera sur le nœud sur lequel vous avez cliqué.

Utilisez le panneau de droite de l'inspecteur DOM pour découvrir les points de fusion et leurs attributs id que vous pouvez utiliser pour insérer vos éléments via des overlays. Si vous n'arrivez pas à découvrir un élément avec un id avec lequel vous pouvez fusionner, il peut être nécessaire d'ajouter un script à votre overlay et d'insérer vos éléments lorsque l'évènement <tt>load</tt> se déclenchera sur la fenêtre XUL maître.

Débogage d'extensions

Outils analytiques de débogage

  • L'Inspecteur DOM - inspectez les attributs, la structure DOM, les règles de style CSS qui sont appliquées (c'est-à-dire découvrez pourquoi vos règles de style ne semblent pas fonctionner sur un élément - un outil indispensable !)
  • Venkman - définissez des points d'arrêt en JavaScript et examinez les piles d'appel
  • arguments.callee.caller en JavaScript - accédez à la pile d'appel d'une fonction

Débogage avec printf

  • Lancez Firefox avec le paramètre <tt>-console</tt> en ligne de commande et utilisez dump("string") (consultez le lien pour plus de détails)
  • Utilisez nsIConsoleService pour écrire dans la console JavaScript

Débogage avancé

{{ wiki.languages( { "de": "de/Erweiterung_erstellen", "en": "en/Building_an_Extension", "es": "es/Creando_una_extensi\u00f3n", "ja": "ja/Building_an_Extension", "pl": "pl/Tworzymy_rozszerzenie" } ) }}

Source de la révision

<p>{{wiki.template('Traduction_à_relire')}}
(<a href="User:Chbok">Chbok</a> 2 jul 2006 à 06:03 (PDT) : Vérifier les liens et captures écran à faire)

</p>
<h4 name="Introduction"> Introduction </h4>
<p>Ce tutoriel va vous présenter les étapes requises pour construire une extension très basique, qui ajoute un bouton contenant le texte « Salut tout le monde ! » à la Barre d'état du navigateur Firefox.
</p>
<div class="note">
<p><b>Note</b> : Ce tutoriel traite de la construction d'extensions pour Firefox 1.5. D'autres tutoriaux existent pour construire des extensions destinées à des versions plus anciennes de Firefox.
</p>
</div>
<h4 name="Configuration_de_l.27environnement_de_d.C3.A9veloppement"> Configuration de l'environnement de développement </h4>
<p>Les extensions sont packagées et distribuées dans des fichiers ZIP, ou <a href="fr/Bundles">Bundles</a>, avec l'extension <tt>xpi</tt> (<i>prononcé « zippy »</i>). Le contenu d'un fichier XPI s'arrange de la manière suivante :
</p>
<pre class="eval">extension.xpi :
              /<a href="fr/Install.rdf">install.rdf</a>
              /<a href="#Composants_XPCOM">components/*</a>
              /<a href="#Lancement_de_l.27application_en_ligne_de_commande">components/cmdline.js</a>
              /<a href="#Fichiers_par_d.C3.A9faut">defaults</a>/
              /<a href="#Fichiers_par_d.C3.A9faut">defaults/preferences/*.js</a>
              /plugins/*
              /<a href="fr/Chrome.manifest">chrome.manifest</a>
              /<a href="fr/Ic%c3%b4nes_de_fen%c3%aatre">chrome/icons/default/*</a>
              /chrome/
              /chrome/content/
</pre>
<p>Par conséquent, il est plus facile de disposer vos fichiers sources selon une méthode similaire, à moins que vous ne désiriez écrire quelque Makefile ou script shell pour packager et zipper tous vos fichiers. Mais même si c'est dans vos cordes, les tests sont plus simples en arrangeant vos fichiers de cette manière à cause d'une particularité du système d'ajout de Firefox 1.5.
</p><p>Bien, commençons. Créez un dossier pour votre extension quelque part sur votre disque dur, par exemple <tt>C:\extensions\monExtension\</tt> ou <tt>~/extensions/monExtension/</tt>. Dans celui-ci, créez un autre dossier nommé <tt>chrome</tt>, et dans ce dernier créez un dossier nommé <tt>content</tt>. (Dans les systèmes Unix, il est habituellement possible de créer ces trois répertoires à la fois en lançant juste <tt>mkdir -p chrome/content</tt> depuis le répertoire racine de l'extension.)
</p><p>À la racine du dossier de votre extension, au même niveau que le dossier <tt>chrome</tt>, créez deux nouveaux fichiers texte vides, l'un appelé <tt>chrome.manifest</tt> et l'autre appelé <tt>install.rdf</tt>.
</p><p>Vous trouverez plus d'astuces sur la mise en place d'un environnement de développement dans la <a class="external" href="http://kb.mozillazine.org/Setting_up_extension_development_environment">Mozillazine Knowledge Base</a>.
</p>
<h4 name="Cr.C3.A9er_le_manifeste_d.27installation"> Créer le manifeste d'installation </h4>
<p>Ouvrez le fichier nommé <tt><a href="fr/Manifestes_d'installation">install.rdf</a></tt> que vous avez créé au premier niveau de la hiérarchie de dossiers de votre extension, et placez ceci à l'intérieur :
</p>
<pre class="eval">&lt;?xml version="1.0"?&gt;

&lt;RDF xmlns="<span class="plain">http://www.w3.org/1999/02/22-rdf-syntax-ns#</span>"
     xmlns:em="<span class="plain">http://www.mozilla.org/2004/em-rdf#</span>"&gt;

  &lt;Description about="urn:mozilla:install-manifest"&gt;
    &lt;em:id&gt;<b>sample@foo.net</b>&lt;/em:id&gt;
    &lt;em:version&gt;<b>1.0</b>&lt;/em:version&gt;
    &lt;em:type&gt;2&lt;/em:type&gt;
   
    &lt;!-- L'application cible de votre extension, 
         avec les versions minimums et maximums supportées. --&gt; 
    &lt;em:targetApplication&gt;
      &lt;Description&gt;
        &lt;em:id&gt;<b>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</b>&lt;/em:id&gt;
        &lt;em:minVersion&gt;<b>1.0+</b>&lt;/em:minVersion&gt;
        &lt;em:maxVersion&gt;<b>1.5.0.*</b>&lt;/em:maxVersion&gt;
      &lt;/Description&gt;
    &lt;/em:targetApplication&gt;
   
    &lt;!-- Méta-données visibles --&gt;
    &lt;em:name&gt;<b>Exemple</b>&lt;/em:name&gt;
    &lt;em:description&gt;<b>Une extension test</b>&lt;/em:description&gt;
    &lt;em:creator&gt;<b>Votre nom ici</b>&lt;/em:creator&gt;
    &lt;em:homepageURL&gt;<b><span class="plain">http://www.foo.com/</span></b>&lt;/em:homepageURL&gt;
  &lt;/Description&gt;      
&lt;/RDF&gt;
</pre>
<p><b>sample@foo.net</b> - L'ID de votre extension. C'est une valeur que vous inventez pour identifier votre extension dans un format d'adresse email (attention, il ne doit pas s'agir de votre email). Il faut qu'il soit unique. Vous pouvez également utiliser un GUID. 
</p><p>Spécifiez <tt>&lt;em:type&gt;2&lt;/em:type&gt;</tt> -- le 2 indique que c'est une extension qui est décrite (voir <a href="fr/Manifestes_d'installation#type">Manifestes d'installation#type</a> pour les autres codes de type).
</p><p><b>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</b> - L'ID de l'application Firefox.
</p><p><b>1.0+</b> - la version minimum de Firefox avec laquelle votre extension fonctionnera. C'est la version minimum avec laquelle vous vous engagez à tester et corriger les bogues.
</p><p><b>1.5.0.*</b> - La version maximum de Firefox avec laquelle votre extension fonctionnera. Elle ne doit pas être supérieure à la dernière version courante !
</p><p>Voir <a href="fr/Manifestes_d'installation">les manifestes d'installation</a> pour une liste complète des propriétés requises et optionnelles.
</p><p>Enregistrez le fichier.
</p>
<h4 name="Extension_du_navigateur_avec_XUL"> Extension du navigateur avec XUL </h4>
<p>L'interface utilisateur de Firefox est écrite en XUL et JavaScript. Le <a href="fr/XUL">XUL</a> est une grammaire XML qui fournit des éléments d'interface comme des boutons, des menus, des barres d'outils, des arbres, etc. Les actions utilisateur sont liées à des fonctionnalités utilisant JavaScript.
</p><p>Pour modifier le navigateur, on remanie des parties de l'interface utilisateur (UI) du navigateur en ajoutant ou modifiant des éléments. Des contrôles sont ajoutés en insérant de nouveaux éléments DOM XUL dans la fenêtre du navigateur, et peuvent être modifiés en utilisant des scripts et en attachant des gestionnaires d'événements.
</p><p>Le navigateur est implémenté dans un fichier XUL nommé <tt>browser.xul</tt> (<tt>content/browser/browser.xul</tt> se trouve dans <tt>$FIREFOX_INSTALL_DIR/chrome/browser.jar</tt>). Dans browser.xul, nous pouvons trouver la Barre d'état, qui ressemble à quelque chose de ce genre :
</p>
<pre class="eval">&lt;statusbar id="status-bar"&gt;
 ... &lt;statusbarpanel&gt;s ...
&lt;/statusbar&gt;
</pre>
<p><tt>&lt;statusbar id="status-bar"&gt;</tt> est un « point de fusion » pour un overlay XUL.
</p>
<h5 name="Les_overlays_XUL"> Les overlays XUL </h5>
<p>Les <a href="fr/Overlays_XUL">overlays XUL</a> sont un moyen d'attacher d'autres éléments d'interface utilisateur à un document XUL au moment de l'exécution. Un overlay XUL est un fichier .xul qui spécifie des fragments de XUL à insérer dans des points de fusion spécifiques au sein d'un document « maître ». Ces fragments peuvent spécifier des élements d'interface à insérer, supprimer ou modifier.
</p><p><b>Exemple de document overlay XUL</b>
</p>
<pre class="eval">&lt;?xml version="1.0"?&gt;
&lt;overlay id="sample" 
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
 &lt;statusbar id="<b>status-bar</b>"&gt;
  &lt;statusbarpanel id="my-panel" label="Salut tout le monde"/&gt;
 &lt;/statusbar&gt;
&lt;/overlay&gt;
</pre>
<p>L'élément <tt>&lt;statusbar&gt;</tt> nommé par l'identifiant <tt><b>status-bar</b></tt> spécifie le « point de fusion » auquel nous voulons nous fixer au sein de la fenêtre du navigateur.
</p><p>L'enfant <tt>&lt;statusbarpanel&gt;</tt> est un nouvel élément d'interface que nous désirons insérer au sein du point de fusion.
</p><p>Prenez l'exemple de code ci-dessus et enregistrez le dans un fichier nommé  <tt><b>exemple.xul</b></tt> dans le dossier <tt>chrome/content</tt> que vous avez créé.
</p><p>Voir plus bas pour plus d'informations au sujet de la fusion d'éléments d'interface et de la modification de l'interface utilisateur en utilisant des overlays.
</p>
<h4 name="Les_URI_chrome"> Les URI chrome </h4>
<p>Les fichiers XUL font parti des « packages chrome » - ensemble de composants d'interface utilisateur qui sont chargés via des URI <tt>chrome://</tt>. Plutôt que de charger le navigateur à partir du disque en utilisant les URI <tt>file://</tt> (puisque la localisation de Firefox sur le système peut changer selon les plateformes et les systèmes), les développeurs Mozilla ont trouvé une solution pour créer des URI que l'application installée connaît pour le contenu XUL.
</p><p>Le navigateur est : <tt>chrome://browser/content/browser.xul</tt> Essayez de rentrer cette URL dans la Barre d'adresse de Firefox !
</p><p>Les URI chrome comprennent plusieurs composants :
</p>
<ul><li> Premièrement, le <b>schéma URI</b> (<tt>chrome</tt>) qui explique à la bibliothèque réseau de Firefox qu'il s'agit d'une URI chrome et que le contenu qui sera chargé doit être manipulé d'une certaine manière.
</li><li> Deuxièmement, un nom de package (dans l'exemple ci-dessus, <tt><b>browser</b></tt> qui identifie le paquet de composants d'interface utilisateur). Il doit être aussi spécifique à votre extension que possible, afin d'éviter les collisions entre extensions.
</li><li> Troisièmement, le type de données requis. Il y a trois types : <tt>content</tt> (XUL, JavaScript, bindings XML XBL, etc., qui forme la structure et le comportement d'une UI d'application), <tt>locale</tt> (DTD, fichiers .properties, etc. qui contiennent les chaînes de caractères pour la localisation de l'UI), et <tt>skin</tt> (CSS et images qui forment le thème de l'UI).
</li><li> Enfin, un nom de fichier à charger.
</li></ul>
<p>Donc, <tt>chrome://foo/skin/bar.png</tt> charge le fichier <tt>bar.png</tt> de la section thème <tt>skin</tt> de <tt>foo</tt>. 
</p><p>Quand du contenu est chargé à l'aide d'une URI chrome, Firefox utilise le registre chrome pour traduire ces URI en adresses de fichiers sources réels sur le disque (ou dans les packages JAR).
</p>
<h4 name="Cr.C3.A9er_un_fichier_chrome.manifest"> Créer un fichier chrome.manifest </h4>
<p>Pour plus d'informations sur les fichiers chrome.manifest et les propriétés qu'ils permettent, voir la référence sur les <a href="fr/Enregistrement_chrome">enregistrements chrome</a>.
</p><p>Ouvrez le fichier nommé <tt><b>chrome.manifest</b></tt> que vous avez créé au même niveau que le répertoire <tt>chrome</tt>, à la racine de la hiérarchie du dossier source de votre extension.
</p><p>Ajoutez ce code :
</p>
<pre class="eval">content     exemple    chrome/content/
</pre>
<p>(<b>N'oubliez pas la barre oblique finale, "<tt>/</tt>"!</b> Sans elle, l'extension ne sera pas chargée.)
</p><p>Ceci spécifie :
</p>
<ol><li> le type de données au sein d'un package chrome
</li><li> le nom du package chrome
</li><li> l'emplacement des fichiers du package chrome
</li></ol>
<p>Donc, cette ligne indique que pour le package chrome <b>exemple</b>, nous pouvons trouver ses fichiers <b>content</b> à l'emplacement <tt>chrome/chromeFiles/content</tt> qui est un chemin relatif à l'emplacement du <tt>chrome.manifest</tt>. 
</p><p>Notez que les fichiers content, locale et skin doivent être maintenus dans des dossiers nommés content, locale et skin au sein de votre sous-répertoire <tt>chrome</tt>.
</p><p>Enregistrez le fichier. Quand vous lancerez Firefox avec votre extension (ceci sera expliqué plus loin dans le tutoriel), il enregistrera le package chrome.
</p>
<h4 name="Enregistrer_un_overlay"> Enregistrer un overlay </h4>
<p>Il est nécessaire que Firefox fusionne votre overlay avec la fenêtre du navigateur à chaque fois qu'il affiche celle-ci. Ajoutez donc cette ligne à votre fichier <tt>chrome.manifest</tt> :
</p>
<pre class="eval">overlay chrome://browser/content/browser.xul chrome://exemple/content/exemple.xul
</pre>
<p>Cette ligne indique à Firefox de fusionner <tt>exemple.xul</tt> dans <tt>browser.xul</tt> lorsque <tt>browser.xul</tt> est chargé.
</p>
<h4 name="Test"> Test </h4>
<p>Tout d'abord, il faut indiquer au navigateur comment trouver votre extension. Dans les jours sombres de Firefox 1.0, cela signifiait un empaquetage de l'extension en un XPI et une installation via l'interface utilisateur, ce qui était franchement fastidieux. À présent, c'est devenu plus simple.
</p>
<ol><li> Ouvrez le dossier des profils http://kb.mozillazine.org/Profile_folder (en)
</li><li> Ouvrez le dossier <b>extensions</b> (ou créez le s'il n'existe pas)
</li><li> Créez un nouveau fichier texte portant le même nom que l'id de votre extension (par exemple <tt>sample@foo.net</tt>), et mettez y le chemin vers le dossier de votre extension (par exemple <tt>C:\extensions\monExtension\</tt> ou  <tt>~/extensions/monExtension</tt>)
</li></ol>
<p>Votre extension est maintenant prête à être testée !
</p><p>(Re)démarrez Firefox. Firefox détectera le lien textuel vers votre extension, et l'installera. À l'apparition du navigateur, vous devriez voir le texte « Salut tout le monde! » dans la Barre d'état (en bas à droite.)
</p><p>Vous pouvez maintenant revenir dans le fichier .xul pour faire d'autres modifications, qui apparaitront après un redémarage.
</p>
<div style="text-align: center;">
<p><img alt="Image:Helloworld_tools_menu.png" src="File:fr/Media_Gallery/Helloworld_tools_menu.png">
<img alt="Image:Helloworld_extensions_wnd.png" src="File:fr/Media_Gallery/Helloworld_extensions_wnd.png">
</p>
</div>
<h4 name="Empaquetage"> Empaquetage </h4>
<p>Maintenant que votre extension fonctionne, vous pouvez l'empaqueter.
</p><p>Compressez au format zip le <b>contenu</b> du dossier de votre extension (pas le dossier de l'extension lui-même), et renommez le fichier zip pour avoir une extension en .xpi. Sous Windows XP, cela peut se faire facilement en sélectionnant tous les fichiers et sous-dossiers du dossier de votre extension, en faisant un clic droit et en choisissant « Envoyer vers -&gt; Dossier Compressé ». Un fichier .zip sera crée pour vous. Renommez le, et c'est terminé.
</p><p>À présent, chargez le .xpi sur votre serveur, en vérifiant qu'il est distribué en tant qu'<tt>application/x-xpinstall</tt>. Vous pouvez créer un lien pour permettre aux personnes intéressées de le télécharger et de l'installer.
</p>
<h5 name="Utilisation_de_addons.mozilla.org"> Utilisation de addons.mozilla.org </h5>
<p>Mozilla Update est un site de distribution où il est possible d'héberger vos extensions gratuitement. Votre extension sera conservée sur le site mirroir de Mozilla pour en garantir la disponibilité de téléchargement, même si elle devenait très populaire. Le site propose également aux utilisateurs une installation facile, et distribuera automatiquement les mises à jour. En plus de cela, il permet aux utilisateurs de commenter et de vous envoyer un retour d'expérience sur votre extension. Il est fortement recommandé d'utiliser Mozilla Update pour distribuer vos extensions.
</p><p>Visitez http://addons.mozilla.org/developers/ pour créer un compte et commencer à distribuer vos extensions.
</p><p><i>Note :</i> Votre extension sera validée plus rapidement et téléchargée plus souvent si vous donnez une bonne description et quelques captures d'écran de l'extension en action.
</p>
<h5 name="Enregistrement_d.27extensions_dans_le_registre_de_Windows"> Enregistrement d'extensions dans le registre de Windows </h5>
<p>Sous Windows, des informations à propos des extensions peuvent être ajoutées à la base de registres, et ces extensions seront identifiées automatiquement repérées au prochain démarrage de l'application. Cela permet aux programmes d'installation d'applications externes d'ajouter facilement des points d'accès à leurs commandes sous la forme d'une extension. Consultez <a href="fr/Ajout_d'extensions_avec_la_base_de_registres_de_Windows">Ajout d'extensions avec la base de registres de Windows</a> pour plus d'informations.
</p>
<h4 name="Plus_d.27informations_sur_les_overlays_XUL"> Plus d'informations sur les overlays XUL </h4>
<p>En plus d'ajouter des contrôles d'interface utilisateur au point de fusion, il est possible d'utiliser des fragments XUL au sein d'overlays afin de :
</p>
<ul><li> Modifier des attributs sur le point de fusion, par exemple <tt>&lt;statusbar id="status-bar" hidden="true"/&gt;</tt> (masque la barre d'état)
</li><li> Retirer le point de fusion du document maître, par exemple <tt>&lt;statusbar id="status-bar" removeelement="true"/&gt;</tt>
</li><li> Contrôler la position des contrôles insérés :
</li></ul>
<pre class="eval">&lt;statusbarpanel position="1" .../&gt;

&lt;statusbarpanel insertbefore="autre-id" .../&gt;

&lt;statusbarpanel insertafter="autre-id" .../&gt;
</pre>
<h4 name="Cr.C3.A9ation_de_nouveaux_composants_d.27interface_utilisateur"> Création de nouveaux composants d'interface utilisateur </h4>
<p>Il est possible de créer vos propres fenêtres et boîtes de dialogues en tant que fichiers .xul séparés, de fournir des fonctionnalités en implémentant des actions utilisateur dans des fichiers .js et d'utiliser des méthodes DOM pour manipuler des contrôles UI. Vous pouvez également utiliser des règles de style dans des fichiers .css pour attacher des images, définir des couleurs etc.
</p><p>Consultez la documentation <a href="fr/XUL">XUL</a> pour plus de ressources pour les développeurs XUL.
</p>
<h4 name="Fichiers_par_d.C3.A9faut"> Fichiers par défaut </h4>
<p>Les fichiers par défaut utilisés pour constituer le profil d'un utilisateur doivent être placés dans le dossier <tt>defaults/</tt> à la racine de la hiérarchie du dossier de votre extension. Les fichiers .js de préférences par défaut doivent se trouver dans <tt>defaults/preferences/</tt> - lorsqu'ils y sont placés il seront chargés automatiquement par le système de préférences de Firefox à son démarrage afin d'être accessibles via l'API de préférences.
</p>
<h4 name="Composants_XPCOM"> Composants XPCOM </h4>
<p>Firefox permet d'utiliser des composants <a href="fr/XPCOM">XPCOM</a> dans les extensions. De nouveaux composants peuvent être implémentées facilement en JavaScript, ou en C++ (à l'aide du <a href="fr/SDK_Gecko">SDK Gecko</a>). 
</p><p>Placez tous vos fichiers .js ou .dll dans le répertoire <tt>components/</tt> - ils sont automatiquement enregistrés au premier démarrage de Firefox après l'installation de votre extension.
</p>
<h4 name="Lancement_de_l.27application_en_ligne_de_commande"> Lancement de l'application en ligne de commande </h4>
<p>Une des utilisations possibles de nouveaux composants XPCOM est d'ajouter un paramètre de ligne de commande à Firefox ou Thunderbird. Cette technique peut être utilisée pour lancer une extension comme s'il s'agissait d'une application :
</p>
<pre class="eval"> firefox.exe -myapp
</pre>
<p><span class="comment">Ceci devrait se trouver dans la page Ligne de commande. Cela se fait en ajoutant un composant contenant la fonction...    function NSGetModule(comMgr, fileSpec) {     return myAppHandlerModule;   }  Cette fonction est exécutée par Firefox à chaque lancement de l'application. Firefox enregistre myAppHandlerModule en appelant sa fonction 'registerSelf()'. Ensuite, la factory de myAppHandlerModule est obtenue via 'getClassObject()'. Celle-ci est alors utilisée pour créer le handle avec sa fonction 'createInstance(). Enfin, la fonction 'handle(cmdline)' traite la ligne de commande cmdline avecses fonctions handleFlagWithParam() et handleFlag().</span>
</p><p>Consultez <a href="fr/Chrome/Ligne_de_commande">Chrome: Ligne de commande</a> et <a class="external" href="http://forums.mozillazine.org/viewtopic.php?t=365297">ce sujet de forum</a> pour plus de détails.
</p>
<h4 name="Localisation"> Localisation </h4>
<p>Pour gérer plus d'une langue, vous devez séparer les chaînes de caractères de votre contenu à l'aide d'entités et de string bundles. Il est beaucoup plus facile de faire au moment du développement de l'extension que d'y revenir par la suite.
</p><p>Les informations de localisation sont stockées dans le répertoire locale de l'extension. Par exemple, pour ajouter une locale à notre extension, créez un répertoire appelé "locale" dans chrome (là où se trouve le répertoire "content") et ajoutez la ligne suivante au fichier chrome.manifest :
</p>
<pre class="eval"> locale sample sampleLocale chrome/locale/
</pre>
<p>Pour créer des valeurs d'attributs localisables en XUL, placez les valeurs dans un fichier <tt>.ent</tt> (ou un fichier <tt>.dtd</tt>) placé dans le répertoire locale, qui devrait ressembler à ceci :
</p>
<pre class="eval">&lt;!ENTITY  button.label     "Cliquez ici"&gt;
&lt;!ENTITY  button.accesskey "C"&gt;
</pre>
<p>Incluez-le ensuite en haut de votre document XUL (juste en dessous de <code>&lt;?xml version"1.0"?&gt;</code>), comme ceci :
</p>
<pre class="eval">&lt;!DOCTYPE <b>window</b> SYSTEM "chrome://packagename/locale/filename.ent"&gt;
</pre>
<p>où <code><b>window</b></code> est la valeur <code><a href="fr/DOM/element.localName">localName</a></code> de l'élément racine du document XUL, et la valeur de la propriété <tt>SYSTEM</tt> est l'URI chrome du fichier d'entités. Dans notre exemple, l'élément racine est <code><b>overlay</b></code>.
</p><p>Pour utiliser les entités, modifiez votre XUL pour qu'il ressemble à ceci :
</p>
<pre class="eval">&lt;button label="&amp;button.label;" accesskey="&amp;button.accesskey;"/&gt;
</pre>
<p>Le registre chrome s'assurera que le fichier d'entités sera chargé du paquet de localisation correspondant à la locale sélectionnée. 
</p><p>Pour les chaînes que vous utilisez dans des scripts, créez un fichier .properties, un fichier texte ayant une chaîne sur chaque ligne dans ce format :
</p>
<pre class="eval">clé=valeur
</pre>
<p>et utilisez ensuite <tt>nsIStringBundleService</tt>/<tt>nsIStringBundle</tt> ou la balise <tt>&lt;stringbundle&gt;</tt> pour charger les valeurs dans le script.
</p>
<h4 name="Comprendre_le_navigateur"> Comprendre le navigateur </h4>
<p>Utilisez l'inspecteur DOM (ne fait pas partie de l'installation <b>Standard</b> de Firefox, vous devrez le réinstaller en choisissant l'installation personnalisée et choisir <b>Outils de développement</b> si l'élément « Inspecteur DOM » n'est pas présent dans le menu Outils de votre navigateur) pour examiner la fenêtre du navigateur ou toute autre fenêtre XUL que vous désirez étendre. 
</p><p>Utilisez le bouton de recherche de nœuds par pointage et clic en haut à gauche de la barre d'outils de l'inspecteur DOM pour cliquer sur un élément de la fenêtre XUL afin de le sélectionner. Lorsque vous effectuez cette manipulation, l'arbre hiérarchique DOM de l'inspecteur DOM se positionnera sur le nœud sur lequel vous avez cliqué. 
</p><p>Utilisez le panneau de droite de l'inspecteur DOM pour découvrir les points de fusion et leurs attributs id que vous pouvez utiliser pour insérer vos éléments via des overlays. Si vous n'arrivez pas à découvrir un élément avec un id avec lequel vous pouvez fusionner, il peut être nécessaire d'ajouter un script à votre overlay et d'insérer vos éléments lorsque l'évènement <tt>load</tt> se déclenchera sur la fenêtre XUL maître.
</p>
<h4 name="D.C3.A9bogage_d.27extensions"> Débogage d'extensions </h4>
<p><b>Outils analytiques de débogage</b>
</p>
<ul><li> L'<a href="fr/Inspecteur_DOM">Inspecteur DOM</a> - inspectez les attributs, la structure DOM, les règles de style CSS qui sont appliquées (c'est-à-dire découvrez pourquoi vos règles de style ne semblent pas fonctionner sur un élément - un outil indispensable !)
</li><li> <a href="fr/Venkman">Venkman</a> - définissez des points d'arrêt en JavaScript et examinez les piles d'appel
</li><li> <code><a href="fr/JS/Objects/Function/arguments/callee">arguments.callee</a>.<a href="fr/JS/Objects/Function/caller">caller</a></code> en JavaScript - accédez à la pile d'appel d'une fonction
</li></ul>
<p><b>Débogage avec printf</b>
</p>
<ul><li> Lancez Firefox avec le paramètre <tt>-console</tt> en ligne de commande et utilisez <code><a href="fr/DOM/window.dump">dump</a>("string")</code> (consultez le lien pour plus de détails)
</li><li> Utilisez <code><a href="fr/NsIConsoleService">nsIConsoleService</a></code> pour écrire dans la console JavaScript
</li></ul>
<p><b>Débogage avancé</b>
</p>
<ul><li> Lancez une compilation debug de Firefox et définissez des points d'arrêt dans Firefox lui-même, ou dans vos composants C++. Pour les développeurs expérimentés, c'est souvent la méthode la plus rapide de diagnostiquer un problème. Consultez la <a href="fr/Documentation_sur_la_compilation">Documentation sur la compilation</a> et <a href="fr/D%c3%a9veloppement_de_Mozilla">Développement de Mozilla</a> pour plus d'informations.
</li><li> Consultez <a href="fr/D%c3%a9bogage_d'une_application_XULRunner">Débogage d'une application XULRunner</a> pour d'autres astuces utiles.
</li></ul>
{{ wiki.languages( { "de": "de/Erweiterung_erstellen", "en": "en/Building_an_Extension", "es": "es/Creando_una_extensi\u00f3n", "ja": "ja/Building_an_Extension", "pl": "pl/Tworzymy_rozszerzenie" } ) }}
Revenir à cette révision