1.4 Les fichiers contents.rdf

Écrit par Neil Deakin. Traduit par Benoit Salandre (08/02/2004), mise à jour par Laurent Jouanneau (23/11/2004) .
Page originale : http://www.xulplanet.com/tutorials/xultu/packaging.html

Dans cette section, nous allons voir comment mettre les fichiers XUL et chrome dans un paquetage et créer les fichiers contents.rdf associés.

Paquetages

Un paquetage est un ensemble de fichiers XUL et de scripts qui définissent la fonctionnalité d'une interface utilisateur. Les paquetages peuvent être installés dans Mozilla et référencés avec des URLs chrome. Un paquetage peut contenir tous les fichiers que l'on veut et peut-être découpé en sous-répertoires pour les différentes parties du paquetage. Par exemple, les marque-pages et l'historique font partie du paquetage communicator, mais sont stockés dans des sous-répertoires différents.

Un paquetage peut-être stocké comme un répertoire ou comme une archive JAR. Chaque paquetage aura un fichier manifest, contents.rdf, qui décrit le paquetage. Ce fichier sera placé dans le fichier JAR au côté des fichiers qu'il décrit. Le fichier doit s'appeler contents.rdf et être un fichier au format RDF (Resource Description Framework). Nous en apprendront plus à propos de RDF plus bas.

Les fichiers contents.rdf

Le fichier contents.rdf décrit les contenus d'un paquetage. Il peut aussi être utilisé pour décrire un thème ou une localisation. Les fichiers manifest sont assez faciles à créer une fois que vous savez comment faire. Le modèle ci-dessous peut-être utilisé comme point de départ.

<?xml version="1.0"?>

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

  <RDF:Seq RDF:about="urn:mozilla:package:root">
    <RDF:li RDF:resource="urn:mozilla:package:monapplication"/>
  </RDF:Seq>

  <RDF:Description RDF:about="urn:mozilla:package:monapplication"
        chrome:displayName="Mon Application"
        chrome:author="nom"
        chrome:name="monapplication">
  </RDF:Description>

</RDF:RDF>

Vous pouvez utiliser ce modèle et effectuer quelques petites modifications spécifiques pour votre paquetage. Décomposons celui-ci pour comprendre ce que fait chaque bloc.

<?xml version="1.0"?>

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

Ces trois lignes devront être placées au tout début du fichier contents.rdf. Parce que RDF est un format XML, il contient les mêmes premières lignes standards que tout fichier XML doit posséder. Ensuite, nous déclarons les espaces de nom qui vont être utilisés, ici un pour RDF et un autre pour le système chrome. Si vous ne comprenez pas ce que cela signifie, ne vous inquiétez pas. Ajoutez les simplement au début du fichier.

<RDF:Seq RDF:about="urn:mozilla:package:root">
  <RDF:li RDF:resource="urn:mozilla:package:monapplication"/>
</RDF:Seq>

Ces lignes sont utilisées pour déclarer quels paquetages, thèmes et localisations sont décrits par le fichier manifest. Dans le cas présent, c'est un paquetage qui va être décrit (comme indiqué par le mot package dans le texte). Si vous créez un thème, vous mettriez skin à la place de package, et si vous créez une localisation, vous utiliseriez locale. Le nom du paquetage ici est monapplication. Bien entendu, il faudra le remplacer par le nom du paquetage que vous allez créer. Par exemple, l'application de courrier électronique de Mozilla se nomme 'messenger'. Le nom doit être court et significatif. Ce nom sera utilisé dans les URLs chrome pour le paquetage.

La balise RDF:li ci-dessus est similaire à la balise li du HTML, elle déclare un élément de liste. Ainsi, vous pouvez déclarez plusieurs paquetages par l'utilisation de plusieurs balises RDF:li.

Pour les thèmes, remplacez les deux occurences de package par skin; pour les localisations, remplacez les deux occurences de package par locale. Par exemple, ce qui suit spécifie un thème :

<RDF:Seq RDF:about="urn:mozilla:skin:root">
  <RDF:li RDF:resource="urn:mozilla:skin:blueswayedshoes"/>
</RDF:Seq>

La partie suivante qui spécifie le nom et l'auteur de l'application :

  <RDF:Description RDF:about="urn:mozilla:package:monapplication"
        chrome:displayName="Mon Application"
        chrome:author="nom"
        chrome:name="monapplication">
  </RDF:Description>

Ce bloc est utilisé pour fournir plus de détails sur paquetage, le thème ou la localisation. Vous aurez besoin d'une description pour chaque balise li. La valeur de l'attribut about devrait être identique à l'attribut ressource de la balise li.

Les trois attributs supplémentaires donnent des informations sur le paquetage.

displayName: Le titre du paquetage tel qu'il devra être affiché à l'utilisateur. Par exemple, 'Messenger'.
author: Le nom de l'auteur du paquetage.
name: Le nom du paquetage, du thème ou de la localisation. Cela devrait être la même valeur qui vient après urn:mozilla:package: qui était spécifiée plus haut. Ce nom est utilisé comme première partie d'un URL chrome.

Vous pouvez aussi utiliser une variété d'autres valeurs. Quand Mozilla déclare votre paquetage, ces valeurs sont ajoutées dans le registre chrome.

Ecrivons un fichier contents.rdf pour la boîte de dialogue de recherche de fichiers que nous voulons créer. Il sera nécessaire de décrire le paquetage. Comme il n' y a pas de sous-paquetage, de thème ou de localisation, il est assez semblable au modèle vu plus haut.

<?xml version="1.0"?>

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

  <RDF:Seq RDF:about="urn:mozilla:package:root">
    <RDF:li RDF:resource="urn:mozilla:package:findfile"/>
  </RDF:Seq>

  <RDF:Description RDF:about="urn:mozilla:package:findfile"
    chrome:displayName="Recherche de fichiers"
    chrome:author="N'importe qui"
    chrome:name="findfile">
  </RDF:Description>

</RDF:RDF>

Ici, le composant est appelé 'findfile' ce qui signifie que nous seront capable de le référencer en utilisant l' URL chrome suivante:

chrome://findfile/content/findfile.xul

Installer un Paquetage

La liste des paquetages installés est stockée dans le répertoire chrome dans le fichier chrome.rdf. Vous devriez ne pas modifier ce fichier directement. Il est modifié automatiquement quand vous installez un nouveau paquetage. Comme pour les fichiers contents.rdf, c'est un fichier au format RDF. A première vue, ça a l'air tout à fait différent des fichiers contents.rdf, mais si vous êtes familier de RDF, vous noterez que c'est en fait très proche.

Chaque fois que Mozilla démarre, il fouille le répertoire chrome à la recherche d'un fichier nommé 'installed-chrome.txt'. Ce fichier contient une liste, dans un format très simple, de tous les paquetages, thèmes et localisations qui sont installés. Si ce fichier est modifié, Mozilla parcourt chaque entrée dans la liste et les enregistre ou les met à jour si nécessaire de sorte qu'elles puissent être utilisées.

Donc, pour enregistrer un nouveau paquetage, tout ce que vous avez à faire c'est de rajouter une entrée au fichier 'installed-chrome.txt' et de redémarrer Mozilla. Le nouveau paquetage sera enregistré et le fichier chrome.rdf sera régénéré puisqu'il doit nécessairement contenir le paquetage nouvellement installé. Mozilla possède également un système d'installation appelé XPInstall qui permet à des scripts d'installer automatiquement des paquetages via javascript sans avoir à modifier manuellement ce fichier. XPInstall sera décrit vers la fin de ce tutoriel. Cependant, pendant le développement, nous pouvons modifier directement le fichier.

Le fichier 'installed-chrome.txt' se trouve dans le répertoire chrome. Le fichier contient une liste d'entrée à installer, une par ligne. Par exemple :

content,install,url,resource:/chrome/findfile/content/findfile/
skin,install,url,resource:/chrome/findfile/skin/findfile/

Ce qui précède sera utilisé pour installer le paquetage, ainsi qu'un thème, pour la recherche de fichier. Le format de chaque ligne est assez simple. Il s'agit juste de quatre valeurs séparées par des virgules :

Type: Mettez content pour les paquetages chrome, skin pour les thèmes ou locale pour les localisations.
Install: Mettez le texte install pour que cette entrée soit installée. Pour les thèmes et les localisations, vous pouvez aussi mettre profile à la place pour installer cette entrée dans le répertoire profile de l'utilisateur. Cela signifiera que c'est uniquement installé pour un utilisateur en particulier.
Type d'URL: Mettez le texte url pour spécifier une URL indiquant où le nouveau paquetage, thème ou localisation est stocké. Si vous utilisez path à la place, vous pouvez utiliser un chemin de fichier (qui devra être au format de votre système d'exploitation).
URL: Mettez l'URL ou le chemin de l'emplacement du paquetage. Ce devrait être le répertoire contenant le fichier contents.rdf ou le chemin et le nom du fichier JAR. Comme on se réfère à un répertoire, assurez vous qu'il y'a une barre oblique de division (slash) à la fin sinon le paquetage ne sera pas trouvé.

Notez que les URLs utilisés sont des URLs resource:/. Vous pouvez tout aussi bien utiliser des URLs de fichiers. Les URLs de ressource sont similaires aux URLs de fichier, exceptée qu'elle commence par resource: au lieu de file: et que son répertoire de base est le répertoire où Mozilla est installé plutôt que la racine du système de fichier. Cela signifie que ça peut-être utilisé pour faire référence à des fichiers dans le répertoire de Mozilla ou dans ses sous-répertoires, indépendamment de l'emplacement où est installé Mozilla. L' URL de ressource doit avoir une seule barre de division après les deux points puisqu'il s'agit toujours d'un chemin relatif.

Ainsi, la ligne supplémentaire doit pointer vers le dossier où se trouve le fichier contents.rdf. Si vous avez plus d'un paquetage, ajoutez une ligne pour chacun d'eux.

Bien que Mozilla suive une convention de nommage des répertoires, vous pouvez mettre les fichiers où vous voulez. Par exemple, la ligne suivante installera un nouveau paquetage qui se trouve dans le répertoire /main/calculator/.

content,install,path,/main/calculator/

Vous pourrez noter également que des lignes du fichier installed-chrome.txt ont un autre type d'URL, le type jar:. Si vous compressez vos fichiers dans un fichier JAR, vous pouvez utiliser une URL JAR pour le référencer. Elle possède deux parties, séparées par un point d'exclamation (!). La première partie est l'URL du fichier JAR et la seconde partie est le répertoire ou le fichier dans l'archive. L'exemple ci-dessous pourrait référencer la boîte de dialogue de recherche de fichiers :

jar:resource:/chrome/findfile.jar!/content/findfile/

Cependant, vous n'aures pas besoin normalement de faire attention aux URLs JAR quand vous créerez vos propres paquetages. Vous garderez plutôt les paquetages décompressés et vous vous y référez en utilisant les types d'URLs fichier ou ressource.

Résumé

Les informations du dessus peuvent avoir été confuses. Voici donc un guide rapide pour créer un simple paquetage. Vous pourrez suivre simplement les étapes du dessous et essayer de regarder les détails sur le fonctionnement de l'installation d'un paquetage une fois que vous serez plus familier avec XUL.

Créez un répertoire quelque part sur votre disque. Beaucoup de gens le mettent comme un sous-répertoire à l'interieur du repertoire chrome de Mozilla, mais ce n'est pas nécéssaire. Le répertoire peut être n'importe où sur le disque. Mettez vos fichiers XUL dans ce répertoire.

Créez un fichier appelé contents.rdf et placez le dans ce répertoire. Copiez le texte de la boîte du dessous dans ce nouveau fichier. Il est utilisé pour identifier l'identifiant (id) de votre application, son nom, son auteur, la version etc.


<?xml version="1.0"?>

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

  <RDF:Seq RDF:about="urn:mozilla:package:root">
    <RDF:li RDF:resource="urn:mozilla:package:myapplication"/>
  </RDF:Seq>

  <RDF:Description RDF:about="urn:mozilla:package:myapplication"
          chrome:displayName="Application Title"
          chrome:author="Author Name"
          chrome:name="myapplication"
          chrome:extension="true"/>

</RDF:RDF>

Changez les parties colorées du fichier du dessus avec vos propres informations. Le texte rouge myapplication doit être l'ID de votre application. Vous l'inventerez, mais typiquement l'ID est similaire au nom de votre application. Remplacez le texte coloré en bleu avec le titre et l'auteur de l'application.
Si le champ chrome:extension est à true, l'application est alors une extension Firefox et apparaîtra dans la fenêtre des extensions du navigateur. Si c'est false, elle n'apparaîtra pas.
Sauvez le fichier contents.rdf et soyez sûr qu'il est dans le répertoire crée lors de l'étape 1.
Ouvrez le fichier <mozilla-directory>/chrome/installed-chrome.txt, où <mozilla-directory> est le répertoire de Mozilla. Quitter Mozilla avant de faire cela.
Ensuite nous allons déclarer la nouvelle application dans Mozilla ainsi il saura où la trouver. Ajoutez une ligne à la fin du fichier installed-chrome.txt pointant vers le nouveau répertoire que vous avez créé.
```
content,install,url,file:///main/app/.
```
Changez le texte coloré par l'URL de fichier du répertoire. Soyez sûr que l'URL se termine bien avec un slash et que vous avez pressé enter à la fin de la ligne. Si vous n'êtes pas sûr de l'URL, ouvrez le repertoire crée à l'étape 1 dans le navigateur et copiez l'URL à partir de la barre d'adresse. Notez que la référence doit être un répertoire, pas un fichier.
Effacez le fichier <mozilla-directory>/chrome/chrome.rdf .
Démarrer Mozilla. Vous devriez pouvoir voir n'importe quel fichier que vous mettez dans le répertoire en utilisant un URL de la forme chrome://applicationid/content/fichier.xul, où fichier.xul est le nom du fichier. Votre fichier principal xul doit être applicationid.xul ce qui vous permet de le charger en utilisant le raccourci chrome://applicationid/content/ .

Si vous avez créé des thèmes ou des localisations, répétez les étapes précédentes, excepté que le format du fichier contents.rdf est légèrement différent. Regardez les fichiers contents.rdf d'autres applications pour plus de détails.

Résolution de problèmes

La création d'un paquetage chrome peut souvent être délicat et il est difficile de diagnostiquer les problèmes. Voici quelques astuces si vous n'y arrivez pas.

Ouvrez le fichier <mozilla-directory>/chrome/chrome.rdf. Vous devriez trouver des références à l'ID de votre application. Si ce n'est pas le cas, quelque chose s'est mal passé avec la déclaration. Si elles y sont, vous avez problablement utilisé un mauvais URL chrome quand vous chargez le fichier.
Essayez d'effacer le fichier <mozilla-directory>/chrome/chrome.rdf. Il sera regénéré. Effacez aussi tout le répertoire <mozilla-directory>/chrome/overlayinfo/ si vous utilisez les overlays.
Soyez sûr que l'URL de la ligne que vous avez ajouté au fichier installed-chrome.txt se termine bien par un slash, et que le fichier se termine par une ligne blanche.
Sous windows, les URLs de fichier sont de la forme file:///C:/files/app/ où C est la lettre du lecteur
Soyez sûr que le fichier contents.rdf est dans le bon répertoire et est bien formé. Ouvrez le fichier contents.rdf dans Mozilla pour voir si il l'analyse bien comme étant du XML sans erreur. Si ce n'est pas le cas, vous verrez une erreur sur un fond jaune.
Si vous utilisez une version debug de Mozilla, certaines informations seront affichées dans le terminal au démarrage, indiquant quelles applications chrome ont été vérifiées. Verifiez si votre application est listée.

Dans la prochaîne section, nous créerons une simple fenêtre.