Créer une extension 1.5

ProgYSM Carte Développement Documentation Données Test Yan Morin

Sommaire

Le but de ce tutoriel est de créer une extension pour Thunderbird 1.5 qui affiche un ou des courriels en format XML dans une fenêtre de dialogue.

Sommaire
1. Créer la structure (répertoire)
2. Générer le fichier d'installation
3. Intégration aux menus contextuels
4. Écrire le code javascript
5. Tester l'extension

Pour exécuter le tout, nous avons besoin de:

1 gestionnaire de fichier pour créer les répertoires; (konsole, ls, cd, mkdir, touch ont été utilisés)
1 éditeur texte; (vim a été utilisé)
1 navigateur pour lire la documentation (Firefox a été utilisé);
Thunderbird 1.5 pour tester l'extension

1. Créer la structure (répertoire)

La première étape est de trouver un nom à notre application et de créer la structure nécessaire. Ensuite, il suffit de remplir chaque fichier. Je mets tous les fichiers dans un répertoire avec le nom de l'application "export2xml" dans mon cas.

Voici la structure que je vous propose de créer:

export2xml/                                     // racine de tous les fichiers
export2xml/chrome.manifest                      // fichiers distribués dans l'extension
export2xml/components/                          // répertoire pour les librairie non XUL/JS/CSS (C, C++, ...)
export2xml/content/                             // répertoire pour les fichiers xul et javascript (js)
export2xml/content/export2xmldlg.xul            // propre à l'extension, un dialogue xul
export2xml/content/overlay.js                   // script principal javascript, utilisé dans overlay.xul
export2xml/content/overlay.xul                  // overlay.xul est un fichier qui sera ajouté par dessus 
                                                // l'interface de thunderbird (lié avec chrome.manifest)
export2xml/content/src.js                       // propre à l'extension, un script javascript secondaire
export2xml/defaults/                            // options par défauts de l'extension
export2xml/defaults/preferences/                // préférences par défauts de l'extension
export2xml/defaults/preferences/mydefaults.js   // préférences javascript par défauts de l'extension
export2xml/install.rdf                          // fichier d'installation
export2xml/locale/                              // répertoire pour les langues (i18n et l10n)
export2xml/locale/en-US/                        // langue par défaut de Thunderbird/Firefox
export2xml/locale/en-US/overlay.dtd             // fichier des textes traduits
export2xml/skin/                                // répertoire pour les feuilles de styles et images
export2xml/skin/overlay.css                     // feuille de style

Cette structure contient beaucoup de dossiers, mais rassurez vous que la majorité des fichiers ou répertoires sont vides. La structure de base est là pour être cohérente avec tous les types d'extensions et n'est qu'un modèle.

Pour mon extension, je n'ai édité que les fichiers chrome.manifest, install.rdf et ceux dans le répertoire content/.

Une fois les répertoires et les fichiers créés, on peut commencer notre extension.

2. Générer le fichier d'installation

Après avoir créer la structure, on remplie les fichiers pertinents.

2.1 chrome.manifest

On commence avec le fichier le plus court, chrome.manifest. Mon fichier contient ceci:

content export2xml content/
overlay chrome://messenger/content/mailWindowOverlay.xul  chrome://export2xml/content/overlay.xul

locale  export2xml  en-US locale/en-US/

skin  export2xml  classic/1.0 skin/

Il s'agit de 4 lignes qui associent des répertoire ou des fichiers à la hiérarchie spécifique de Thunderbird ou de Firefox (selon le cas).

Catégorie content (contenu), mon extension se nomme 'export2xml' et les fichiers XUL et javascript sont contenus dans le répertoire content/.
Catégorie overlay (par-dessus), je vais intégrer mon fichier export2xml/content/overlay.xul par dessus le fichier de Thunderbird 1.5 messenger/content/mailWindowOverlay.xul. Il s'agit du principe d'overlay en XUL qui s'apparente au principe de cascades en CSS.
Catégorie locale (internalisation), mon extension se nomme 'export2xml', utilise la langue 'en-US' et contient un répertoire locale/en-US/.
Catégorie skin (thème), mon extension se nomme 'export2xml', le thème classic/1.0 de thunderbird sera utilisé, et les fichiers CSS seront dans le répertoire skin/ de mon extension.

2.2 install.rdf

Le fichier d'installation install.rdf contient le nom et diverses informations sur l'extension. On peut générer ce fichier avec mon générateur de fichier "install.rdf". Entrer "Export 2 XML" pour le nom de l'extension, "export2xml" pour le nom du paquetage, générer un nouveau GUID aléatoire et entrer le numéro de version 0.0.1. Choissisez Thunderbird, version 1.5 à 2.0 et laissez I18N à en-US. Entrer votre nom d'auteur et une description si cela vous chante. Enfin, cliquer sur le bouton "Générer install.rdf". Une fois le code du fichier générer, copier le résultat dans le fichier "export2xml/install.rdf" déjà créé à l'étape 1. Si vous voulez, vous pouvez commenter ou enlever la balise <em:file></em:file> qui n'est plus nécessaire. Noter bien le GUID aléatoire généré pour votre extension, il est nécessaire pour tester l'extension à l'étape 5.

3. Intégration aux menus contextuels

3.1 Le fichier "content/overlay.xul"

La majorité des extensions fonctionnent sur le principe d'overlay pour intégrer une extension à une application existente. Donc, en créant un fichier XUL overlay, nous allons ajouter des menus et des options à Thunderbird 1.5.

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://export2xml/skin/overlay.css" type="text/css"?>
<!DOCTYPE overlay SYSTEM "chrome://export2xml/locale/overlay.dtd">
<overlay id="export2xml-overlay"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
     <script type="application/x-javascript" src="overlay.js"/>

        <!-- Message Menu Item -->
        <menupopup id="messageMenuPopup">
          <menuitem id="export2xmlCmd" label="Export Mail to XML"
                    oncommand="export2xml.handleCmd(event);" />
        </menupopup>

        <!-- popup for message -->
        <popup id="messagePaneContext">
          <menuitem id="export2xmlCmd" label="Export Mail to XML"
                    oncommand="export2xml.handleCmd(event);" />
        </popup>

       <!-- popup for threads -->
        <popup id="threadPaneContext">
          <menuitem id="export2xmlCmd" label="Export Mail to XML"
                    oncommand="export2xml.handleCmd(event);" />
        </popup>

</overlay>

Voici quelques explications:

xml-stylesheet href="chrome://export2xml/skin/overlay.css": Permet d'utiliser la feuilles de style propre à l'extension
chrome://export2xml/locale/overlay.dtd: Ce fichier peut contenir des ENTITY accessibles par la syntaxe &Nom.Element;. Dans le même style que les entités < ou > ou  
<overlay id="export2xml-overlay"></overlay>: Un overlay permet de surcharger ou ajouter des fonctionnalité à une interface contrairement à une balise <window> qui crée une fenêtre d'application.
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul": L'espace de nom de tous les fichiers XUL.
<script type="application/x-javascript" src="overlay.js">: Cette ligne permet de charger du code javascript (comme en HTML ou XHTML).
menupopup: menupopup est la balise pour les menus dans la barre de menu. Noter que le id="messageMenuPopup" indique une balise menupopup inscrite dans le code XUL de Thunderbird 1.5, fichier chrome://messenger/content/mailWindowOverlay.xul. Si vous regarder le code de ce dernier fichier, vous pourrez voir "messageMenuPopup", le menupopup pour le menu "Message" de Thunderbird. Note que le fichier overlay.xul a été lié avec mailWindowOverlay.xul dans le fichier chrome.manifest.
popup: popup est une balise pour les menus contextuels.

4. Écrire le code javascript

À chaque balise menuitem, j'ai associé une fonction javascript, définie dans overlay.js.

Je n'expliquerai pas ligne par ligne le code, mais voici comme il fonctionne en gros: 1. j'appelle la fonction handleCmd() de l'objet export2xml. 2. lorsque la fonction récupère tous les courriels, j'ouvre une fenêtre-dialogue (export2xmldlg.xul) avec la fonction window.openDialog(). 3. Ensuite, j'envoies les courriels, formatés en XML.

Overlay XUL
Javascript pour overlay.xul
Dialogue XUL
Javascript pour le dialogue XUL

Désolé, j'ai perdu les fichiers d'origine...

5. Tester l'extension

Pour tester l'extension, rien de plus simple (ou presque).

Dans votre répertoire privé de préférences de Thunderbird (~/.thunderbird/default/???.slt/extensions), créer un fichier qui se nomme {GUID}. Le GUID doit correspondre au GUID créé pour le fichier install.rdf! Donc, par exemple, si j'ai créé le GUID 72263a93-5d94-6243-3947-2a25456b8827, alors mon fichier se nomme {72263a93-5d94-6243-3947-2a25456b8827} avec les accolades {}.
Dans ce fichier, on écrit le chemin absolu du répertoire avec le fichier chrome.manifest. Pour moi, il s'agit du répertoire ~/project/thunderbird/export2xml.
On ouvre Thunderbird 1.5 et on test.

Hyperliens...

Getting Started With Extension Development
Créer une extension sur Firefox 1.0
Canal IRC #thunderbird de Mozilla sur irc.mozilla.org

Lire les commentaires | Laisser un commentaire

doc.progysm.com

Rechercher

Voir aussi...