Enregistrement chrome

Gecko 1.8 (Firefox 1.5/2.0, Thunderbird 1.5, XulRunner ...) - Version courte pour débuter

Attention, ici, on décrit un processus simplifié pour enregistrer dans le chrome une application XUL. Il est fortement recommandé de lire cette page en entier.

Dans votre répertoire Firefox (il est recommandé d'avoir votre propre version de Firefox, pas celle de votre OS), allez dans le répertoire chrome, et créez un fichier

 foobar.manifest

qui contiendra :

 content foobar foobar/content/

créez les répertoires foobar/content

Allez dans le répertoire foobar/content

Créez les fichiers

 foobar.xul
 foobar.js

Le fichier foobar.xul contiendra par exemple :

 <?xml version="1.0"?>
 <?xml-stylesheet href="[[chrome://global/skin/]]" type="text/css"?>
 <?xml-stylesheet href="[[chrome://foobar/content/foobar.css]]" type="text/css"?>
 <window
	title = "Foobar"
	xmlns  = "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
	<script src="[[chrome://foobar/content/foobar.js"/]]>
	<hbox>
		<button flex="1" label="test" oncommand="test()"/>
	</hbox>
 </window>

Le fichier foobar.js contiendra par exemple :

 function test() {
   alert("foobar");
 }

Cliquer ensuite sur ce lien pour accéder au formulaire permettant de générer le fichier install.rdf: http://xulfr.org/outils/wiz_install_rdf.(..)

Cliquer sur le bouton "générateur GUID", une sorte de numéro vous sera fourni. Copier ce numéro et créér un répertoire du même nom dans le répertoire "extension" ce qui donnera par exemple : "C:\Program Files\Mozilla Firefox\extensions\{c1b16e94-7682-5562-91ac-684f471326c2}"

Note : depuis Firefox 2.0, vous pouvez utiliser autre chose que ce genre de numéro comme identifiant de votre extension. ex : monprojet@monsite.com

Revenez sur le formulaire et remplisser les infos demandées (Attention aux numéro de version "max" de firefox, mettez par exemple : 2.5.* )

Une fois le formulaire rempli cliquer sur le bouton "créer install.rdf", enregistrez le fichier générer dans le nouveau repertoire dans extension que vous venez de créer ce qui donnera par exemple : "C:\Program Files\Mozilla Firefox\extensions\{c1b16e94-7682-5562-91ac-684f471326c2}/install.rdf"

Lancez Firefox et chargez l'url :

 [[chrome://foobar/content/foobar.xul]]

Il est recommandé de rajouter dans le fichier pref.js de votre profil les lignes suivantes :

 user_pref("nglayout.debug.disable_xul_cache", true); // désactive le cache XUL
 user_pref("nglayout.debug.disable_xul_fastload", true); // lié au précédent, facultatif
 user_pref("javascript.options.strict", true); // active l'affichage de toutes les erreurs d'exécutions
 user_pref("javascript.options.showInConsole", true); // active l'affichage de toutes les erreurs de syntaxe
 user_pref("browser.dom.window.dump.enabled", true); // active le dump sur la console

cf: ConfigurerMozillaPourDevelopper.

NOTE : sous firefox 2, il suffit d'entrer l'URL "about:config" dans la barre d'adresse du navigateur et de cliquer deux foix sur les options à modifier (utilisez le filtre accessible en haut pour trier les options) : %%% javascript.options.strict

javascript.options.showInConsole

Ici, nous utilisons le terme foobar comme exemple, remplacez le par le nom de votre appli.

Gecko 1.8 (Firefox 1.5/2.0, Thunderbird 1.5, XulRunner ...)

Dans Gecko 1.8, il n'y a plus de fichiers contents.rdf, ni de fichier installed-chrome.txt. Ils sont remplacés par des fichiers *.manifest.

Dans le cas de la création d'un fichier XPI, vous devez fournir un fichier chrome.manifest situé à la racine de votre fichier XPI.

création du repertoire de l'extension pour le dev

En phase de développement, comme dans Gecko 1.7, il est tout à fait possible de mettre les répertoires content, locale et skin de votre extension où bon vous semble, que ce soit dans le répertoire "chrome/" de Firefox (ou Thunderbird etc..), ou ailleurs sur votre disque dur, dans ~/projets_extensions/monExtension/ par exemple. Vous pouvez éviter ainsi de générer un fichier XPI à chaque modification.

Vous devez alors créer dans le répertoire /extensions/ de votre profil (ou celui de l'application), un fichier qui a pour nom l'identifiant de votre extension (la valeur du champ <em:id> de votre fichier install.rdf). Dans ce fichier texte, vous écrirerez une simple ligne indiquant le chemin du répertoire racine de votre extension, répertoire dans lequel Firefox s'attend à trouver le fichier chrome.manifest.

Par exemple, un fichier nommé extension@nom.org dans le répertoire /extensions/ du profil utilisateur contenant :

 ~/projets_extensions/monExtension/ (sous linux)
 ou
 C:\projet\monExtension\ (sous windows)

À noter que :

• si un répertoire comporte des espace, son nom n'a pas besoin d'être échappé.
• une barre de séparation de répertoire est facultative à la fin du chemin (/ sous Linux ou \ sous Windows).
• Il ne faut pas laisser trainer un espace à la fin de la ligne sinon l'extension n'est pas reconnue, et le fichier texte peut être effacé au lancement de Firefox.

Fichier install.rdf

Dans le repertoire de votre extension, vous devez écrire un fichier install.rdf).

Description des fichiers *.manifest

Ces fichiers manifest ont une syntaxe qui rappelle un peu l'ancien installed-chrome.txt. Chaque ligne du fichier déclare un répertoire ou un fichier à intégrer dans le chrome. Sa structure est différente selon le type du répertoire ou fichier.

En général, vous aurez un seul fichier, nommé chrome.manifest dans le repertoire de votre extension.

Vous pouvez y déclarer les répertoires de type content, skin, locale et les overlays comme dans Gecko 1.7, mais aussi, chose nouvelle, déclarer des feuilles de styles supplémentaires qui seront appliquées à des fichiers XUL d'autres paquets, et déclarer des fichiers remplaçant ceux d'autres paquets.

Les chemins de répertoire déclarés peuvent être absolus, ou relatifs à l'emplacement du fichier manifest.

répertoire content

Syntaxe de la ligne :

  content   ''nom_paquet_chrome''   ''chemin_repertoire_content''   ''[options]''

Exemple :

 content  monappli   chrome/monappli/content/

répertoire de locale

Syntaxe de la ligne :

  locale   ''nom_paquet_chrome''  ''code_langue''  ''chemin_repertoire''   ''[options]''

Exemple :

 locale   monappli   fr-FR   chrome/monappli/locale/fr-FR/

répertoire skin

Syntaxe de la ligne :

  skin   ''nom_paquet_chrome''  ''nom_thème''  ''chemin_repertoire''   ''[options]''

Exemple :

 skin   monappli  global  chrome/monappli/skin/global/

Overlays

Syntaxe :

 overlay ''[[chrome://uri_du_fichier_concerné']]'   ''[[chrome://uri_de_l'overlay']]'  ''[options]''

Exemple :

 overlay [[chrome://browser/content/browser.xul]]  [[chrome://monappli/content/overlay-firefox.xul]]

Feuilles de styles additionnelles

Ce sont des feuilles de styles qui seront appliquées à des fichiers d'autres paquets (des overlays CSS en quelque sorte).

Syntaxe :

 style ''[[chrome://uri_du_fichier_à_styler']]'   ''[[chrome://uri_du_fichier_css']]'

Exemple :

 style  [[chrome://browser/content/browser.xul]]  [[chrome://monappli/content/firefox.css]]

Remplacement de fichier

Vous pouvez fournir dans une extension un fichier qui en remplacera un autre dans un autre paquet

Syntaxe :

 override   ''[[chrome://uri_du_fichier_à_remplacer']]'  ''uri_du_nouveau_fichier''

Exemple :

 override  [[chrome://browser/content/browser.xul]]  [[chrome://monappli/content/browser-firefox.xul]]

(ici on refait totalement l'interface de firefox ! ;-) )

Les options

Pour certaines déclarations, vous pouvez ajouter des options.

• *Option application**

Dans le cas où vous fournissez une extension qui peut s'appliquer à une ou plusieurs applications différentes (par exemple, vous faites une extension qui peut s'installer à la fois dans Firefox et à la fois dans Thunderbird), il est nécessaire de spécifier dans le manifest quelles déclarations concernent quelle application. Cette option permet de l'indiquer.

 application=''uuid''

Exemple :

  content  monappli   chrome/monappli/content/firefox/ application=ec8030f7-c20a-464f-9b0e-13a3a9e97384
  content  monappli   chrome/monappli/content/thunderbird/ application=3550f703-e582-4d05-9a08-453d09bdfdc6

• *option appversion**

Cette option permet d'indiquer à quelle version de l'application l'extension est destinée.

 appversion=version
 appversion<version
 appversion<=version
 appversion>version
 appversion>=version

Vous pouvez indiquer plusieurs appversions sur une même ligne. Voyez sur devmo pour le format de numéro de version : http://developer.mozilla.org/en/docs/Too(..)

• *option platform**

Indiquez cette option quand vous fournissez des contenus spécifiques à des plate-formes (n'est donc utilisable que pour les lignes content). Pour cela, vous devez avoir dans votre répertoire de type content, des répertoires propres à chaque plateforme : win, mac, unix.

Exemple:

  content  monappli   chrome/monappli/content/  platform

Vous devez alors avoir chrome/monappli/content/win, chrome/monappli/content/mac et chrome/monappli/content/unix. Si vous appelez chrome://monappli/content/foo.xul, Gecko ira chercher le fichier chrome/monappli/content/win/foo.xul , chrome/monappli/content/wmax/foo.xul ou chrome/monappli/content/unix/foo.xul suivant que vous vous trouviez sous windows, mac ou unix (linux..).

• *option xpcnativewrappers**

Mettez xpcnativewrappers=no si vous ne voulez pas d'accès sécurisé à vos fichiers. par défaut, elle est à yes depuis Firefox 1.5 beta.

voir les explications pour XPCNativeWrapper.

Dans le contexte du développement de votre extension

Pour développer une extension ou application, vous n'allez pas à chaque modification créer un nouveau fichier XPI. Il est tout à fait possible de mettre les repertoires content, locale et skin de votre extension où bon vous semble, que ce soit dans le répertoire "chrome/" de Firefox (ou thunderbird etc..), ou ailleurs sur votre disque dur. Il faut ensuite les déclarer "à la main" dans le chrome, via le fichier chrome/installed-chrome.txt.

Prenons l'exemple d'une extension "monappli", qui contient un répertoire content, deux répertoires locale, et un répertoire skin.

Quand vos répertoires se trouvent dans le répertoire chrome, vous déclarez comme ceci :

 content,install,url,resource:/chrome/monappli/content/
 locale,install,url,resource:/chrome/monappli/locale/fr-FR/
 locale,install,url,resource:/chrome/monappli/locale/en-US/
 skin,install,url,resource:/chrome/monappli/skin/

Quand vos répertoires se trouvent dans par exemple /home/laurent/projets/monappli, alors le fichier installed-chrome.txt devra contenir ceci :

 content,install,url,file:///home/laurent/projets/monappli/content/
 locale,install,url,file:///home/laurent/projets/monappli/locale/fr-FR/
 locale,install,url,file:///home/laurent/projets/monappli/locale/en-US/
 skin,install,url,file:///home/laurent/projets/monappli/skin/

ou alors, plutôt que d'utiliser une url, vous pouvez utiliser un chemin (notez le remplacement de url,file:// par path) :

 content,install,path,/home/laurent/projets/monappli/content/
 locale,install,path,/home/laurent/projets/monappli/locale/fr-FR/
 locale,install,path,/home/laurent/projets/monappli/locale/en-US/
 skin,install,path,/home/laurent/projets/monappli/skin/

Sous windows, il faudra bien sûr adapter la syntaxe du chemin :

 content,install,path,d:\projets\monappli\content
 locale,install,path,d:\projets\monappli\locale\fr-FR
 locale,install,path,d:\projets\monappli\locale\en-US
 skin,install,path,d:\projets\monappli\monappli\skin

Note : le chemin indiqué en fin de ligne ne doit pas contenir d'espaces.

Ce qu'il faut retenir, c'est que vous pouvez développer votre application n'importe où, du moment que vous la déclarez dans le fichier installed-chrome.txt pour qu'elle ait les privilèges chrome.