Conversion des extensions vers Firefox 0.9
Rédigé par ChBok le 6 juin 2004page originale : http://jedbrown.net/mozilla/EM/
Accord obtenu sous réserve d'indiquer le lien vers la page anglaise et de fournir le lien de la vf à l'auteur
Ce document va tenter d’expliquer par des exemples comment utiliser la nouvelle gestion des API pour Firefox 0.9 telle que définit par Ben Goodger pour les extensions à venir.
Bien que son sujet principal soit la conversion des extensions compatibles 0.8 vers la nouvelle API, cet article sera également utile pour quiconque souhaite créer une extension pour Firefox.
1) La nouvelle API : présentation rapide
Actuellement dans Firefox 0.8 et Thunderbird 0.6, les extensions sont listées et affichées dans le panneau des options comme indiqué sur la figure 1
, tandis que le nouveau gestionnaire d’extensions aura sa propre fenêtre comme indiqué sur la figure 2.
Notez que le nouveau gestionnaire d’extensions permet des icones personnalisés pour chaque extension, des liens pour une page d’accueil et d’information, et offre de nouvelles fonctions telles que la désinstallation et les mises à jour.
2) La Structure des XPI
La structure actuelle et ancienne était similaire à ceci :
extension.xpi:
install.js
extension.jar
extension.dll
extension.jar
extension.dll
La nouvelle structure est décrite comme suit :
extension.xpi:
install.rdf
chrome/extension.jar
components/extension.dll
components/extension.js
defaults/extension.something
defaults/preferences/extension.js
chrome/extension.jar
components/extension.dll
components/extension.js
defaults/extension.something
defaults/preferences/extension.js
Par exemple, lÂ’extension quicknote a la structure suivante :
quicknote.xpi:
install.js
quicknote.jar
quicknote.jar
Maintenant, avec la nouvelle API, le fichier .jar devra être dans un répertoire chrome et un nouveau fichier install.rdf devra être créé :
quicknote.xpi:
install.rdf
chrome/quicknote.jar
chrome/quicknote.jar
3) Le fichier RDF install.rdf
Le nouveau fichier install.rdf a été officiellement décrit par Ben Goodger sur sa page concernant les extensions pour Firefox/Thunderbird.Ci dessous, vous trouverez une description s’efforçant de décrire au mieux chaque balise et leur fonction.
Les champs nécessaires :
Comme nous décrivons un fichier XML, nous devons déclarer en premier ce qui suit :
<?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#"> ................. </RDF>
A l’intérieur de la balise RDF, nous devons définir la description de notre extension
<Description about="urn:mozilla:install-manifest"> ...... </Description>
A l’intérieur de la balise description commence les choses sérieuses :
<em:id>{657DDE38-D0B3-4f8a-BF9F-023A6C29119B}</em:id> // GUID, Vous devez en [[http://www.microsoft.com/downloads/details.aspx?FamilyId=94551F58-484F-4A8C-BB39-ADB270833AFC&displaylang=en générer un]] pour votre extension, c’est un identifiant unique.//
<em:name>QuickNote</em:name> // Le nom de votre extension//
<em:version>0.5.9</em:version> // Le numéro de version actuelle//
<em:description>A note taking extension with advanced features Includes required JSlib from May23rd.</em:description> // Une bonne description//
<em:creator>Jed Brown</em:creator> // Noms des auteurs//
<em:contributor>Nickolay Ponomarev.</em:contributor> // Contributeurs optionnels (un ou plusieurs)//
<em:homepageURL>http://quicknote.mozdev.org/</em:homepageURL> // Page Web de lÂ’extension//
<em:optionsURL>chrome://quicknote/content/qnsettings.xul</em:optionsURL> // Lien optionnel vers une fenêtre d’options//
<em:aboutURL>chrome://quicknote/content/about.xul</em:aboutURL> // Lien optionnel vers une fenêtre d’informations (voir ci dessous)//
<em:iconURL>chrome://quicknote/skin/qntoolbar.png</em:iconURL> // Une icône pour identifier votre extension//
<em:updateURL>http://jedbrown.net/dev/Mozilla/QNupdate.rdf</em:updateURL> // Fichier optionnel pour les mises à jour (voir la documentation officielle)//
Si vous ne mettez pas de balise optionnelle <em:aboutURL>, le gestionnaire d’extensions créera sa propre fenêtre d’informations à partir des données ci dessus (fig. 3),
ou vous pouvez la personnaliser comme avec lÂ’extension quicknote (fig. 4)
(Fig. 3)
(Fig. 4)
Ensuite, vous devez spécifier le nom de vos fichiers .jar, les thèmes graphiques et les fichiers de localisation que vous utilisez.
<em:file> <Description about="urn:mozilla:extension:file:quicknote.jar"> // Assurez vous que chrome/extension.jar est écrit correctement// <em:package>content/</em:package> // L’emplacement des fichiers XUL/JS (quicknote.jar > content > quicknote.xul)// <em:skin>skin/classic/</em:skin> // L’emplacement des thèmes graphiques (quicknote.jar > skin > classic > quicknote.css)// <em:locale>locale/en-US/quicknote/</em:locale> // L’emplacement des fichiers de localisation linguistique (quicknote.jar > locale > en-US > quicknote > quicknote.dtd// </Description> </em:file>
Enfin, nous devons indiquer pour quelles applications (Firefox, Thunderbird, etc.) notre extension est dédiée, et avec quelle version de ces applications elle fonctionne.
<em:targetApplication> // Vous devez mettre une balise pour chaque application compatible//
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> // Ceci est lÂ’identifiant unique de Firefox//
<em:minVersion>0.7</em:minVersion> // LÂ’extension quicknote fonctionne pour Firefox 0.7 Ã 0.9//
<em:maxVersion>0.9</em:maxVersion> // Assurez vous de mettre cette balise avec la version 0.9 de Firefox, car les choses pourraient changer dans la version 1.0//
</Description>
</em:targetApplication>
Voici à quoi devrait ressembler toutes les balises décrites, cet exemple peut vous servir de modèle pour votre propre extension :
install.rdf
<?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>{657DDE38-D0B3-4f8a-BF9F-023A6C29119B}</em:id>
<em:name>QuickNote</em:name>
<em:version>0.5.9</em:version>
<em:description>A note taking extension with advanced features Includes required JSlib from May23rd.</em:description>
<em:creator>Jed Brown</em:creator>
<em:contributor>Nickolay Ponomarev</em:contributor>
<em:homepageURL>http://quicknote.mozdev.org/</em:homepageURL>
<em:optionsURL>chrome://quicknote/content/qnsettings.xul</em:optionsURL>
<em:aboutURL>chrome://quicknote/content/about.xul</em:aboutURL>
<em:iconURL>chrome://quicknote/skin/qntoolbar.png</em:iconURL>
<em:updateURL>http://jedbrown.net/dev/Mozilla/QNupdate.rdf</em:updateURL>
<em:file>
<Description about="urn:mozilla:extension:file:quicknote.jar">
<em:package>content/</em:package>
<em:skin>skin/classic/</em:skin>
<em:locale>locale/en-US/quicknote/</em:locale>
</Description>
</em:file>
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>0.7+</em:minVersion>
<em:maxVersion>0.9</em:maxVersion>
</Description>
</em:targetApplication>
</Description>
</RDF>
4) Conservation d’une compatibilité avec la suite Mozilla et les versions antérieures
La conservation de la compatibilité avec des versions antérieures de Firefox/Thunderbird ou avec la suite Mozilla est très facile. Utilisez simplement votre fichier originel install.js et repérez où les fichiers extensions.jar sont ajoutés, c’est à dire par l’appel de la fonction addFile()Exemples de ce que vous devez trouver
addFile(author, version, jarName, folder, null);
ou
addFile('Jed Brown', '0.5.9', 'quicknote.jar', getFolder('Profile', 'chrome'), null);
ou
addFile('Jed Brown', '0.5.9', 'quicknote.jar', getFolder('Profile', 'chrome'), null);
Nous devons dire à l’application que le fichier jar devant être ajouté est situé dans un sous-répertoire chrome. Pour cette opération, nous devons modifier les lignes ci-dessus comme ceci :
addFile(author, version, 'chrome/' + jarName, folder, null);
ou
addFile('Jed Brown', '0.5.9', 'chrome/' + 'quicknote.jar', getFolder('Profile', 'chrome'), null);
ou
addFile('Jed Brown', '0.5.9', 'chrome/' + 'quicknote.jar', getFolder('Profile', 'chrome'), null);
Maintenant, la structure de votre extension xpi devrait ressembler à ceci :
extension.xpi:
install.rdf
install.js
chrome/extension.jar
install.js
chrome/extension.jar
C’est tout ! Votre extension devrait maintenant être prête pour le gestionnaire d’extensions (EM).
Dans ce cas, Firefox 0.9 et suivant (et les futures versions de Thunderbird) ignoreront le fichier install.js et nÂ’appliqueront que ce qui est valide dans le fichier install.rdf, tandis que les anciennes versions de Firefox/Thunderbird et de la suite Mozilla ignoreront le fichier install.rdf et utiliseront seulement le fichier install.js.
Vous pouvez consulter les fichiers install.js et install.rdf sur la page Web mozdev de quicknote.
5) Le fichier Update.rdf (mise à jour de version)
Le nouveau gestionnaire d’extensions permettra à Firefox/Thunderbird de détecter automatiquement une nouvelle version de votre extension lorsqu’elle est disponible. Cette mise à jour s’effectue de deux manières :- Si votre extension est hébergée sur update.mozilla.org, tout sera pris en charge automatiquement à chaque fois que vous y soumettrez une nouvelle version.
- En fournissant votre propre fichier update.rdf à partir duquel vous gérez vos propres mise à jour.
Ce second point va être étudié en détail.
Dans le fichier install.rdf ci dessus servant d’exemple, vous noterez la présence de la balise <em:updateURL>. Celle ci est nécessaire pour ce point 2 car elle contient le lien vers le fichier update.rdf sur votre propre serveur.
Pour QuickNote?, il sÂ’agit de :
<em:updateURL>http://jedbrown.net/dev/Mozilla/QNupdate.rdf</em:updateURL>
Un fichier update.rdf doit contenir les éléments suivants :
update.rdf
<?xml version="1.0"?>
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="http://www.mozilla.org/2004/em-rdf#">
<RDF:Description about="urn:mozilla:extension:{657DDE38-D0B3-4f8a-BF9F-023A6C29119B}">
<em:version>0.6</em:version>
<em:updateLink>http://jedbrown.net/dev/Mozilla/quicknote_dev_0_5_X_ff0.9.xpi</em:updateLink>
</RDF:Description>
</RDF:RDF>
Notez que votre serveur DOIT fournir le fichier rdf avec son type mime correct ; soit text/rdf, soit text/xml (seul text/rdf a été testé).
Vous pourrez savoir si votre serveur fournit le bon type mime en visualisant votre fichier .rdf sous Firefox de deux façons :
1) Le code ci dessus doit sÂ’afficher sous Firefox comme ceci (faites le test) :
2) Lorsque vous visualisez votre fichier .rdf sous Firefox, cliquez sur "Information sur la page" dans le menu contextuel, le type affiché devrait être application/vnd.mozilla.xul+xml.
Si vous avez procédé correctement, lorsque vous proposerez une nouvelle version de votre extension au travers du fichier .rdf, le gestionnaire d’extensions devrait la détecter normalement lors de la sélection d’une mise à jour de l’extension. (fig. 5)
