TP6: étude d'une extension Firefox

De $1

Etude de la structure de base d'une extension

NOTE: si vous avez des soucis pour faire marcher la version du WebServ, voici une version alternative (projet eclipse WebServTP3_alternatif

Installation

Constituez-vous un environnement de développement en vous créant un profil firefox spécifique (cf TP 5).

Télécharger et décompresser l'extension de test feakeext Pour tester cette extension, copier le fichier nommé "fakeext @ isicil.inria.fr" qui se trouve dans l'archive, dans le dossier "extensions" de votre profil firefox de développement. Le nom de ce fichier correspond à l'identifiant de l'extension déclaré dans le fichier install.rdf:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    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:install-manifest">
        <em:aboutURL>chrome://fakeext/content/dialogs/about.xul</em:aboutURL>
        <em:creator>INRIA Sophia</em:creator>
        <em:description/>
        <em:homepageURL>http://isicil.inria.fr</em:homepageURL>
        <em:iconURL>chrome://fakeext/skin/logo/isicil.png</em:iconURL>
        <em:id>fakeext@isicil.inria.fr</em:id>
        <em:name>ISICIL Fake Extension</em:name>
        <em:version>0.1.0</em:version>
        <em:updateURL>https://isicil.inria.fr/updates</em:updateURL>
        <em:type>2</em:type>
        <em:targetApplication>
            <RDF:Description>
                <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
                <em:maxVersion>3.*.*</em:maxVersion>
                <em:minVersion>3.0</em:minVersion>
            </RDF:Description>
        </em:targetApplication>
    </RDF:Description>
</RDF>

Ouvrez ensuite ce fichier qui contient une seule ligne indiquant le chemin du dossier "src" de l'extension. Modifiez ce chemin pour pointer vers le bon dossier (par ex dans mon cas "D:\flimpens\web-pgm\workspace_cours\fakeext\src").

Redémarrez Firefox et allez voir le menu Outils/Modules complémentaires et vérifiez que l'extension ISICIL Fake Extension a bien été installée, elle doit apparaitre sous la forme d'une entrée dans le menu.

Etude de la structure

La structure de l'extension est la suivante:

  • src
  •  chrome.manifest
  •  install.rdf
  •  defaults/
  •    preferences/
  •      prefs.js
  •   chrome/
  •     fakeext/
  •       content/
  •         overlay.xul  
  •         dialogs/   
  •           about.xul    
  •       locale/    
  •        en-EN/      
  •          locale.dtd    
  •        fr-FR/      
  •          locale.dtd
  •       skin/    
  •        global/     
  •             logo/      
  •            isicil.png

Obeservez tout d'abord le contenu du fichier install.rdf (cf ci-dessus) qui contient tous les détails liés à l'identification de l'extension.

Regardez maintenant le fichier chrome.manifest:

  1. content fakeext         chrome/fakeext/content/
  2. skin     fakeext global     chrome/fakeext/skin/global/
  3. locale     fakeext fr-FR     chrome/fakeext/locale/fr-FR/

  4. overlay    chrome://browser/content/browser.xul    chrome://fakeext/content/overlay.xul

C'est dans ce fichier que sont déclarées  les correspondances entre les adresses chrome:// et les dossiers de l'arborescences. Par exemple le fichier image isicil.png sera accessible à l'adresse : chrome://fakeext/skin/logo/isicil.png. A la ligne 5 est déclaré le fichier d'overlay qui sera utilisé pour insérer des éléments dans le navigateur. Ce mécanisme est spécifique aux extensions, en comparaison avec les applications XULRunner vues la séance précédente. Observez la correspondances des adresses et de l'emplacement du fichier overlay.xul. Un "overlay" est un "ajout" à la GUI de firefox.

Regardez maintenant le fichier overlay.xul:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE overlay SYSTEM "chrome://fakeext/locale/locale.dtd">
  3. <?xml-stylesheet href="chrome://fakeext/skin/skin.css" type="text/css"?>
  4. <overlay xmlns="http://www.mozilla.org/keymaster/gat...re.is.only.xul">
  5.     <menupopup id="menu_ToolsPopup">
  6.         <menuitem id="fakeext-menuitem" label="&fakeext.title;"/>
  7.     </menupopup>
  8. </overlay>

 La ligne 2 donne l'adresse du fichier où sont déclarées les entités qui sont des variables accessibles avec la syntaxe "&mavariable;" comme par exemple &fakeext.title; utilisée à la ligne 6 pour donner une valeur au label du "menuitem". La ligne 5 montre comment  est inséré un élément dans le navigateur, c'est à dire en récupérant un élément déjà existant dans firefox (menupopup id="menu_ToolsPopup") puis en le "surchargeant" par des éléments additionels (menuitem id="fakeext-menuitem"). En utilisant le DOM inspector, retrouvez dans le dom du navigateur les éléments correspondants.

NOTE POUR LES EXERCICES : vous devez avoir installé les extensions firefox recommandées lors du TP précédent : 

 

Lorsque vous modifierez un des fichiers de votre extension, au lieu de relancer à chaque fois firefox, utilisez l'option "reload all xul module" de l'extension Developper. Vous pouvez aussi faire apparaitre la barre d'outil de cette extension, ce qui donne un accès immédiat à cette fonctionnalité (dans le menu affichage/Barres d'outils)

Exercice: Ajouter une interaction ouvrant la fenêtre de dialogue:

  1. retrouvez l'adresse chrome de la boite de dialogue about.xul, située dans les sources de l'extension;
  2. ajoutez l'attribut "oncommand" au menuitem de l'extension. Cet attribut prend en valeur un appel à une fonction javascript. Déclarez une fonction qui ouvre la boîte de dialogue about.xul en vous aidant de la référence de la fonction window.openDialog (ref) (ne spécifiez que l'url et le nom de la boite de dialogue, la variable "features" peut être égale à "").

Exercice: Ajoutez un bouton à la fenêtre de dialogue qui ouvre une page dans un nouvel onglet du navigateur.

  1.  ajoutez un boutton à la suite des éléments "description" situés dans la boite de dialogue en vous aidant de la référence de l'élément "button"
  2. ajoutez une image à ce bouton (par exemple isicil.png)
  3. ajoutez un attribut "value" auquel vous donnerez la valeur de l'url de la page à ouvrir (par exemple "http://isicil.inria.fr").
  4. l'attribut "oncommand" permet d'exécuter une fonction lorsque le bouton est cliqué. Dans la valeur de cet attribut, déclarez l'appel à une fonction qui prend en paramètre la valeur de l'attribut "value" (hint: regardez les référence de getAttribute et notez que l'élément en question est l'élément courant)
  5. Déclarez la fonction appelée. Cette fonction prend en paramètre une URL et charge dans un nouvel onglet cet URL. Aidez vous de cette référence vous expliquant comment récupérez un élément "gBrowser" qui correspond au navigateur principal de firefox. Ensuite utilisez la méthode loadOneTab de cet élément (ref).

 

 Etude d'une extension complète

L'extension "boomtag" est un prototype d'extension un peu plus complète et faisant appel à des web services développés dans le cadre du premier cours sur les web services REST.

Déploiement et test de l'extension

Téléchargez et décompressez l'archive boomtag. Cette extension consomme des web services du serveur de bookmarks étudiés dans le séance 1. Une version adaptée pour la création de bookmark et basée sur la version correspondante au TP 3 est disponible ici (la librairie dojo a été supprimée pour un gain de place, si vous souhaitez utilisez ces librairies vous pourrez les récupérez depuis l'archive du TP3 -- si vous aves des soucis avec cette version pour faire marcher le DOJO, voici ici une version alternative WebServTP3_alternatif). Récupérez l'archive et vérifiez que le server fonctionne bien. Le web service qui est appelé à l'ouverture de l'extension est le suivant: http://localhost:9998/bookmark/all.

Pour l'installation et le test, procédez comme pour fakeext : 

  1. copier le fichier boomtag @ sophia.inria.fr dans le dossier extensions de votre profil
  2. modifier le chemin pour qu'il pointe vers le dossier /path/to/Boomtag/srcExtension
  3. relancez Firefox

Cette extension se compose d'une sidebar (sur la gauche) qui est ouverte par défaut au lancement et qui liste les bookmarks donnés par l'appel au web service. Le serveur de tags doit bien sûr avoir été lancé sur votre machine !!!! Vérifiez que tous les bookmarks sont bien listés d'abord en accédant depuis votre navigateur à cette adresse : http://localhost:9998/bookmark/all. Ensuite seulement, votre extension pourra les visualiser dans la side-bar.

Cette extension permet aussi d'enregistrer des bookmarks. Pour l'utiliser faites ALT+SHIFT+D. Une fenetre apparait contenant 3 champs dont certains sont déjà complétés. Le web service pour l'enregistrement des bookmarks nécessite d'être identifié au préalable via le formulaire à l'adresse http://localhost:9998/.

L'objectif maintenant est d'enrichir ce squelette d'extension avec des fonctionnalités de tagging, mais aussi (selon votre inspiration) avec des fonctions gérant l'identification, la recherche des bookmarks par tags, etc.

Etude des spécificités de boomtag

Nous allons maintenant regarder plus en détail le code source de cette extension.

overlay.xul

Regardez l'entête de ce fichier:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE overlay SYSTEM "chrome://boomtag/locale/locale.dtd">
  3. <?xml-stylesheet href="chrome://boomtag/skin/skin.css" type="text/css"?>
  4. <?xul-overlay href="chrome://boomtag/content/overlays/bmtree/bmtree.xul"?>
  5. <overlay xmlns="http://www.mozilla.org/keymaster/gat...re.is.only.xul">
  6.     <script type="text/javascript" src="chrome://boomtag/content/scripts/boomtag.js"/>

Observez ligne 4 la déclaration du fichier d'overlay bmtree.xul où sera écrit le code XUL de la sidebar qui s'intègre directement dans le navigateur, par contraste avec les autre fenêtres de dialogue. Voyez aussi l'externalisation des scripts ligne 6.

 Autre nouveauté la possibilité d'ajouter des menus contextuels grace à l'élément popup:

<popup id="contentAreaContextMenu">
        <menuitem id="boomtag-contextmenu" label="&toolsmenuitem.title;" insertafter="context-stop" command="cmd_showPanel"/>
    </popup>

L'id de l'élément dans lequel s'insère ce code XUL (contentAreaContextMenu) est un attribut du tabbrowser "content", un élément fils du browser. Utilisez le Dom Inspector pour retrouver ces éléments du DOM du navigateur.

Les commandset permettent de déclarer des commandes qui sont ensuite reliés à des appels de fonction javascript contenu dans le fichier inclu en entête. Regardez la commande "showPanel":

<commandset id="boomtag-commandset">
   <command id="cmd_closePanel" oncommand="boomtag.closePanel(event);"/>
   <command id="cmd_showPanel" oncommand="boomtag.showPanel(event);"/>
   <command id="cmd_showBMEditor" oncommand="boomtag.showBMEditor(event);"/>
</commandset>

Ces commandes peuvent être ensuite appelés par d'autres éléments XUL comme les raccourcis claviers, les "keyset". Ici CTRL+SHIFT+F pour appeler la commande showPanel (ainsi que l'autre raccourci évoqué plus haut pour l'éditeur de bookmarks):

<keyset id="boomtag-keyset">
   <key id="search-key" modifiers="shift control" key="F" command="cmd_showPanel"/>
   <key id="bmdialog-key" modifiers="shift alt" key="D" command="cmd_showBMEditor"/>
</keyset>

Ces éléments sont insérés dans un élément "window" main-window. Utilisez le DOM inspector à l'adresse suivante pour vous répérer : chrome://browser/content/browser.xul

Enfin la sidebar est insérée dans l'élément "browser" (id) de type "hbox":

  1. <hbox id="browser">
  2.   <vbox id="boomtag-sidepanel" insertbefore="sidebar-box">
  3.     <sidebarheader align="center">
  4.        <label value="Boomtag" persist="value" flex="1" crop="end" control="sidebar"/>
  5.        <image id="sidebar-throbber"/>
  6.        <toolbarbutton class="tabs-closebutton" tooltiptext="Fermer le panneau latéral" command="cmd_closePanel"/>
  7.      </sidebarheader>
  8.      <hbox align="center">
  9.          <description value="Rechercher"/>
  10.          <textbox flex="1" type="search" class="compact" id="boomtag-searchbox"/>
  11.      </hbox>
  12.      <vbox id="bmtree-container" flex="1" class="panel-frame"/>
  13.   </vbox>
  14.   <splitter id="boomtag-splitter" insertbefore="sidebar-box" collapse="before" persist="state"/>
  15. </hbox>

L1-2 : répérer les éléments du DOM concernés par les insertions (id="browser" et insertbefore="sidebar-box").Vient ensuite l'entête de la sidebar "sidebarheader" (l3-7): n'hésitez pas à avoir recours aux références sur le site XUL pour mieux comprendre les différents attributs des éléments. Voyez l'emploi d'un commandset pour fermer la sidebar (cmd_closePanel).

L8-11 : insertion de la barre de recherche qui pour l'instant n'a pas de fonctions associées. A la ligne 12 est déclarée le conteneur de la liste des bookmarks affichés id="bmtree-container". Cette ID correspond à ce qui est décrit dans le fichier bmtree.xul (dans content\overlays\bmtree) que nous allons maintenant étudier.

bmtree.xul : les templates XML

Remarquez dans l'entête la ligne:

<overlay xmlns="http://www.mozilla.org/keymaster/gat...re.is.only.xul">

qui permet d'associer ce code source à un overlay déclaré dans le fichier overlay.xul. Autre détail important, ligne 6:

<vbox id="bmtree-container" flex="1" class="panel-frame">

Attention de bien respecter l'id déclarée dans le fichier overlay.xul (id=bmtree-container).

Template XML:

Assurez vous d'avoir bien compris les template XML vu au TP précédents. Le principe est ici le même, mais appliqué sur un élément de type "tree" (cf ref):

<tree id="bmtree" seltype="single"
    hidecolumnpicker="false" class="tree" datasources="&datasource.bm.all;"
    ref="*" querytype="xml" flex="1" ondblclick="bmtree.loadData(event, this);">

Les attributs spécifiques au mécanisme de template sont le "datasource" qui fait appel ici à une entitée déclarée dans locale.dtd, "ref", et "querytype". Notez aussi l'interaction dynamique lors d'un doubleclick. Regardez le code correspondant dans le fichier bmtree.js et la méthode loadData. Les propriétés et méthodes spécifiques à l'élément tree sont décrit dans la ref, notamment tree.view.getCellText, etc. Vous retrouverez aussi la fonction loadOneTab associé à l'élément gBrowser qui est ici accesible directement sans passer par window.opener.gBrowser.

Le principe de requête et de "remplissage" du tableau est le même qu'au TP précédent avec la requête XPath "coupée" en 2. Chargez d'abord dans un onglet à part le résultat de  requête correspondant au datasource déclaré (http://localhost:9998/bookmark/all) afin de mieux comprende la requête XPath.

<template>
        <query expr="bookmark">
            <assign var="?id" expr="id" />
            <assign var="?label" expr="title" />

On récupére tous les éléments "bookmark" et pour chacun de ces éléments, on "mappe" le noeud id (expr="id") avec la variable ?id (var="?id"), et ainsi de suite pour les autre noeuds. Ces variables sont ensuites réutilisées pour peupler le "tree" dans la partie "action" du template (ignorez la balise "rule" pour l'instant):

<rule>
    <action>
       <treechildren>
         <treeitem container="false" uri="?">
            <treerow>
              <treecell label="?label" />
              <treecell label="?url"/>
              <treecell label="?id" />

Notez aussi l'attribut uri="?" dans la balise "treeitem" qui permet de "raccrocher" le résultat des requêtes. Chaque variable peut ensuite être utilisée comme valeur d'attribut, ici l'attribut "label" de chaque "treecell".

L'éditeur de bookmarks: bmeditor.xul

L'élement XUL est ici de type "dialog" :

<dialog xmlns="http://www.mozilla.org/keymaster/gat...re.is.only.xul"
title="Boomtag Editor" orient="vertical" buttons="accept,cancel"
style="padding:0" minwidth="600px" minheight="300px"
ondialogaccept="return doOK();"
ondialogcancel="return doCancel();"
onload="bmeditor.init();"
>

Cette fenêtre est appelée par la combinaison ALT+SHIFT+D depuis un onglet du navigateur. La méthode bmeditor.init() déclarée dans le fichier bmeditor.js permet de récupérer des éléments de la page HTML chargé dans l'onglet:

init:function(){
        $("bmtitle").value = window.opener.gBrowser.contentDocument.title;
        $("bmurl").value = window.opener.gBrowser.contentDocument.URL;
        $("bmdescr").value = window.opener.gBrowser.contentWindow.getSelection();    
        $("bmtags").value = ""; // initialisation ajax
    },

Attention à la correspondance des ids des éléments XUL utilisées pour peupler les élements (seuls les tags ne sont pas peuplés) (Notez aussi qu'ici encore, il faut passer par window.opener afin d'accéder au "gBrowser" depuis une fenêtre de dialogue) :

<rows>
            <row align="center">
                <label value="Titre :" />
                <textbox id="bmtitle" flex="1" value=""/>
            </row>

Lorsque l'utilisateur clique sur le bouton OK, la fonction save est appelée depuis bmeditor.js

  1. save:function(){
  2.         var postdata = "title="+$("bmtitle").value
  3.         + "&url="+$("bmurl").value
  4.         + "&descr="+$("bmdescr").value
  5.         + "&tags="+$("bmtags").value;
  6.        
  7.         var urlws="http://localhost:9998/bookmark/create";
  8.         var contenttype="application/x-www-form-urlencoded";
  9.         var async=false;
  10.        
  11.         var xhr=new XMLHttpRequest();
  12.         xhr.open("POST",urlws,async);
  13.         xhr.setRequestHeader("Content-Type",contenttype) ;
  14.         xhr.send(postdata);
  15.         var old_ds = window.opener.document.getElementById("bmtree").getAttribute("datasources");
  16.         window.opener.document.getElementById("bmtree").setAttribute("datasources", "");
  17.         window.opener.document.getElementById("bmtree").setAttribute("datasources", old_ds);
  18.     },

Cette fonction effectue un appel AJAX vers le serveur de bookmark bmserv.

  • Lignes 2-5 : préparation des données au format "POST".
  • L7 : on déclare l'url appelée, l8 le type de contenu attendu en retour
  • L9 déclare que l'appel se fera en mode synchrone, (pour plus de simplicité).
  • l11-14 déclaration et envoie de l'appel.
  • l15-17 : afin que les bookmarks listés dans le tableau de la sidebar soit raffraichi, on réactualise la valeur de l'attribut "datasources".

Observez maintenant la manière dont l'appel est traité côté serveur dans la classe BookmarkResource.java:

  1. @POST
  2.     @Path("/create")
  3.     @Consumes("application/x-www-form-urlencoded")
  4.     @Produces("text/html")
  5.     public String create(@Context HttpServletRequest req, MultivaluedMap<String, String> formParams){
  6.         HttpSession session= req.getSession(true);
  7.         session.getAttributeNames();
  8.         TemplateEngine.setSession(req.getSession());
  9.         String userid = (String) session.getAttribute("userid");
  10.         if (userid!=null) {
  11.                 System.out.println(userid);
  12.                 String urlstr = formParams.getFirst("url");
  13.                 String title = formParams.getFirst("title");
  14.                 String descr = formParams.getFirst("descr");
  15.                 String tags = formParams.getFirst("tags");
  16.                 String bmid = Server.bmh.createBookmark(title, urlstr, descr, userid);
  17.                 String[]taglist = tags.split(" ");
  18.                 for(String t:taglist){
  19.                     Server.tgh.createTagging(userid, bmid, Server.th.createTag(t).getId());
  20.                 }
  21.         }else{
  22.             System.out.println("Impossible de créer le bookmark, l'utilisateur n'est pas authentifié dans le système.");
  23.         }
  24.         return "<html><body><pre>"+formParams.toString()+"</pre></body></html>";
  25.     }

Notez aussi comment est gérée l'identification de l'utilisateur, car celui-ci doit être logué pour pouvoir enregistrer un bookmark. Dans le script boomtag.js :

  1. showBMEditor:function(pEvent){
  2.         var xhr=new XMLHttpRequest();

  3.         var urlws="http://localhost:9998/user/current";
  4.         var async=false;
  5.         xhr.open("GET",urlws,async);       
  6.         xhr.send(null);
  7.        
  8.         if(xhr.responseText != "") {
  9.             window.openDialog(this.bmeditor_url,'bmeditor','chrome,modal,resizable,centerscreen');
  10.         }
  11.         else gBrowser.loadOneTab("http://localhost:9998/form/login");
  12.     },

La fonction showBMEditor vérifie que l'utilisateur est bien logué en faisant un appel AJAX au web service http://localhost:9998/user/current. Ce web service (cf UserResource.java dans le server BMServ) retourne le login de l'utilsateur si celui-ci est logué, ou la chaine de charactère vide sinon. La fonction (cote client) showBMEditor vérifie donc que la réponse ne soit pas égale à "", auquel cas l'utilisateur est redirigé vers la page d'authentification du web service; sinon, le dialogue de bmeditor est ouvert.

 

A vous de jouer !

Vous pouvez maintenant enrichir cette extension :

 

  • en ajoutant des fonctionalités de recherche des bookmarks par tags dans la sidebar. Notez que l'attribut "datasources" des templates peut être modifié dynamiquement via javascript ce qui a pour effet de regénérer automatiquement les données chargées dans le template. ceci peut permettre par exemple de récupérer les bookmarks liés à un tag rentré dans la barre de recherche, etc.
  • en ajoutant des fonctionnalités d'autocompletion dans les champs de recherche ou dans le champ des tags de bmeditor. Pour ce faire vous pouvez faire appel aux webservice listant tous les tags et à la réference XUL ici.
  • en améliorant la fonctionalité d'identification, par exemple en affichant à un endroit de la sidebar le login si l'utilisateur est logué, ou bien un lien vers la page de login dans le cas contraire.
  • Inspirez vous également des fonctionnalités de l'extension de delicious.

 

Mots clés:
FichierTailleDateAttaché par 
 BMServ_TP6.zip
Aucune description
8.44 Mo18:07, 1 Avr 2010flimpensActions
 Boomtag (2).zip
Aucune description
19 Ko22:05, 1 Avr 2010flimpensActions
 fakeext (1).zip
Aucune description
3.51 Ko13:01, 31 Mar 2010flimpensActions
Images (0)
 
Commentaires (0)
Vous devez être connecté pour poster un commentaire.