13.2 Les scripts d'installation

Écrit par Neil Deakin , mise à jour par les contributeurs à MDC .
Traduit par Alain B. (04/04/2007).
Page originale : http://developer.mozilla.org/en/docs/XUL_Tutorial/Install_Scripts

Attention : Ce tutoriel est ancien et n'est pas mis à jour. Bien que beaucoup d'informations soient encore valables pour les dernières versions de gecko, beaucoup sont aussi obsolètes. Il est préférable d'aller consulter cette page sur la version française de ce tutoriel sur developer.mozilla.org.

NdT : Attention, cette section décrit le mécanisme XPInstall propre à la suite Mozilla et à des versions anciennes de Mozilla Firefox. Pour les versions récentes de Mozilla Firefox, ce mode d'installation n'est plus le même, mais il n'est pas encore décrit dans ce tutoriel. Voir comment faire des extensions pour firefox sur xulfr.org.

Cette section décrit le script d'installation.

Création d'un script d'installation

Note : Pour des extensions Firefox, install.js n'est plus utilisé. Vous devez utiliser install.rdf à la place.

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'appeler 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. Il 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 :

Initialiser l'installation en précisant le paquetage et sa version.
Utiliser les fonctions d'installation pour spécifier les fichiers et les répertoires qui doivent être installés. Vous pouvez aussi spécifier les fichiers à déplacer ou à effacer.
Démarrer le processus qui installe les fichiers nécessaires.

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 plusieurs fichiers à installer, et en cas d'erreurs, vous pouvez annuler tout le processus d'installation sans modifier le système de l'utilisateur.

Le registre d'extensions

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.

Initialisation de l'installation

L'objet Install a une fonction, initInstall(), servant à 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.

Marquage des fichiers d'installation

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. La fonction registerChrome() est utilisée pour cela. 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.

Finalisation de l'installation

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 13.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 la section suivantes, nous verrons quelques fonctions supplémentaires pour l'installation.