Écrit par Neil Deakin.
Traduit par Alain B. (14/03/2004).
Page originale :
http://www.xulplanet.com/tutorials/xultu/xpiscript.html
Ce chapitre décrit le script d'installation.
Note du Traducteur : ce chapitre ne concerne que la suite Mozilla, et non pas Mozilla Firefox, pour lequel il n'y a pas besoin de faire de script. Voir comment faire des extensions pour firefox sur xulfr.org.
Vous voulez généralement avoir une forme de contrôle sur vos processus d'installation. Par exemple, vous pouvez souhaiter vérifier les versions des fichiers existants et n'installer que des mises à jour, ou peut être souhaiteriez-vous simplement appliquer des corrections. Le script d'installation est même assez souple pour vous permettre de désinstaller des fichiers. Pour ces raisons, les programmes d'installation incluent un script propre à cette tâche.
Le script d'installation doit s'appelé install.js et doit être placé à la racine de l'archive de l'installeur. Ce script contient du code JavaScript qui appelle un certain nombre de fonctions d'installation.
Dans un document HTML ou un document XUL, l'objet
window
est l'objet global racine. Cela signifie que vous pouvez appeler les méthodes
de l'objet window
sans les faire précéder de leur qualificateur, ainsi window.open(...)
peut simplement être écrit open(...)
. Dans un script d'installation,
il n'y a pas de fenêtre associée, toutefois l'objet global
sera l'objet Install
qui contient un certain nombre de
fonctions pour personnaliser le processus d'installation. Certaines fonctions
de l'objet global Install
seront décrites ci dessous.
Le script d'installation doit suivre les étapes suivantes :
Il est important de signaler que pendant l'étape numéro deux, vous n'indiquez seulement quels sont les fichiers qui seront installés et quelles autres opérations vous souhaitez réaliser. Aucun fichier ne sera copié avant l'étape trois. En procédant de la sorte, vous pouvez facilement définir un certain nombre de fichiers à installer, et en cas d'erreurs, vous pouvez annuler tout le processus d'installation sans modifier système de l'utilisateur.
Mozilla tient à jour un fichier qui est un registre de toutes les extensions actuellement installées. Les extensions incluent les nouveaux paquetages chrome, les thèmes graphiques et les plugins. Lorsqu'une nouvelle extension est installée, le registre est mis à jour. Le registre stocke aussi l'ensemble des informations des fichiers et de leurs versions sur les extensions installées. De cette manière, il est aisé de vérifier si une version de votre extension est déjà présente et de la mettre à jour seulement si nécessaire.
Le registre d'extensions fonctionne presque comme la base de registre de Windows. Il consiste en une série hiérarchisée de clefs et de valeurs. Vous n'avez pas besoin d'en savoir plus à son sujet pour créer des applications XUL à moins que vous ne créiez vos propres composants XPCOM.
Ce que vous devez savoir pour une installation est que le registre stocke une série d'informations sur votre application, tels que la liste des fichiers et leurs versions. Toutes ces informations sont stockées dans une clef (et à l'intérieur, des sous clefs) que vous fournissez dans le script d'installation (dans l'étape 1 mentionnée ci dessus).
Cette clef est structurée comme une arborescence de répertoire comme ceci :
/Auteur/Nom du Paquetage
Remplacez le mot Auteur par votre nom et remplacez le Nom du Paquetage avec le nom de votre paquetage que vous installez. Par exemple :
/Xulplanet/Find Files /Netscape/Personal Security Manager
Le premier exemple est celui utilisé pour notre exemple de boite de dialogue de recherche de fichiers. Le second est la clef utilisée pour le gestionnaire de données privées.
L'objet Install
a une fonction, initInstall
,
qui sert à initialiser l'installation. Elle doit être appelée
au lancement de votre script d'installation. La syntaxe de cette fonction
est la suivante :
initInstall( packageName , regPackage , version );
Exemple:
initInstall("Find Files","/Xulplanet/Find Files","0.5.0.0");
Le premier argument est le nom du paquetage sous une forme lisible pour l'utilisateur. Le second argument est la clef du registre utilisée pour mémoriser l'information du paquetage comme décrit ci avant. Le troisième argument est la version du paquetage à installer.
Ensuite, nous devons indiquer le répertoire où seront installés les fichiers. Il y a deux façons de le faire. La méthode simple est d'assigner un répertoire d'installation et d'y copier tous les fichiers. La seconde méthode vous permet d'assigner une destination à chaque fichier (ou répertoire). La première méthode est décrite ci dessous.
La fonction setPackageFolder
assigne un répertoire
d'installation. Pour l'exemple de recherche de fichiers, vous installerons
les fichiers dans le répertoire chrome (nous pourrions aussi bien
les mettre autre part). Cette fonction setPackageFolder
ne requiert qu'un argument, le répertoire d'installation. Pour une
compatibilité maximale, vous ne devez pas spécifier un répertoire
absolu. Au lieu de cela, vous utiliserez un identifiant d'un répertoire
connu et pointerez sur un de ses sous répertoires. Ainsi, si votre
application a besoin d'installer quelques librairies systèmes, vous
n'avez pas besoin de connaître le nom de ces répertoires.
Les identifiants de sélection de répertoires sont expliqués
sur la page de référence.
Pour le répertoire chrome, l'identifiant est Chrome. La
fonction getFolder
peut être utilisée pour
récupérer un de ces répertoires spéciaux. Cette
fonction prend deux arguments, le premier étant l'identifiant et
le second étant un sous répertoire. Par exemple :
findDir = getFolder("Chrome","findfile");
setPackageFolder(findDir);
Ici, nous récupérons l'emplacement du sous répertoire
findfile dans répertoire Chrome et nous le passons directement
à la fonction setPackageFolder
. Le second argument
de la fonction getFolder
est le sous répertoire
qui servira à l'installation de l'exemple et qui n'a pas besoin d'avoir
été créé d'abord. Vous pouvez ignorer cet argument si vous n'en avez pas besoin.
Ensuite, vous devez indiquer quels seront les fichiers à installer.
Deux fonctions doivent être employées pour cela, addDirectory
et addFile
. La fonction addDirectory
précise
à l'installeur un répertoire de l'archive XPI (et tout son
contenu) qui devra être installé à un emplacement particulier.
La fonction addFile
est similaire mais seulement pour un
fichier.
Les deux fonctions addDirectory
et addFile
ont plusieurs paramétrages. Le plus simple ne prend qu'un seul argument
qui est le répertoire servant à l'installation.
addDirectory ( dir );
addFile ( dir );
Exemple:
addDirectory("findfile");
L'exemple ci dessus spécifie que le répertoire findfile de l'archive d'installation est à installer. Nous pouvons appeler ces fonctions autant de fois que nécessaire pour les autres fichiers.
Ensuite, nous voulons enregistrer les fichiers de notre exemple dans le
registre chrome afin de pouvoir les appeler par une
URL chrome. Cela peut être éffectuer
avec la fonction registerChrome
. Elle prend deux
arguments, le premier étant le type d'enregistrement chrome (content
pour du contenu, skin pour du thème graphique, ou locale
pour la localisation), le second pointant vers l'emplacement du fichier
manifest contents.rdf à enregistrer. Comme notre exemple de recherche
de fichiers contient les trois types, la fonction registerChrome
devra être appelée trois fois.
registerChrome(Install.CONTENT | Install.DELAYED_CHROME, getFolder(findDir, "content"));
registerChrome(Install.SKIN | Install.DELAYED_CHROME, getFolder(findDir, "skin"));
registerChrome(Install.LOCALE | Install.DELAYED_CHROME, getFolder(findDir, "locale"));
L'indicateur DELAYED_CHROME sert à indiquer que le chrome devra être installé au prochain lancement de Mozilla.
Les fonctions addDirectory
et addFile
ne copient aucun fichier. Elles ne servent qu'à pointer quels fichiers
devront être installés. De la même manière, la
fonction registerChrome
ne fait que pointer quel chrome
devra être enregistré. Pour achever le processus et commencer
la copie des fichiers, appelez la fonction performInstall
sans argument.
Le script final pour installer notre exemple de recherche de fichiers est le suivant :
Exemple 12.2.1 : Source
initInstall("Find Files","/Xulplanet/Find Files","0.5.0.0");
findDir = getFolder("Chrome","findfile");
setPackageFolder(findDir);
addDirectory("findfile");
registerChrome(Install.CONTENT | Install.DELAYED_CHROME, getFolder(findDir, "content"));
registerChrome(Install.SKIN | Install.DELAYED_CHROME, getFolder(findDir, "skin"));
registerChrome(Install.LOCALE | Install.DELAYED_CHROME, getFolder(findDir, "locale"));
performInstall();
Dans le chapitre suivant, nous verrons quelques fonctions supplémentaires pour l'installation.