Il existe de nombreuses façons d'installer des extensions et des thèmes depuis des pages Web, parmi lesquelles un lien direct vers les fichiers XPI et l'utilisation de l'objet InstallTrigger.
Les auteurs d'extensions et de pages Web sont encouragés à utiliser la méthode décrite ci-dessous pour installer des fichiers XPI, c'est celle qui est la plus agréable pour l'utilisateur.
Exemple de script Web
<script type="application/x-javascript">
<!--
function install (aEvent)
{
var params = {
"Foo": { URL: aEvent.target.href,
IconURL: aEvent.target.getAttribute("iconURL"),
Hash: aEvent.target.getAttribute("hash"),
toString: function () { return this.URL; }
}
};
InstallTrigger.install(params);
return false;
}
-->
</script>
<a href="https://www.example.com/foo.xpi"
iconURL="https://www.example.com/foo.png"
hash="sha1:28857e60d043447c5f4550853f2d40770b326a13"
onclick="return install(event);">Installer l'extension</a>
Examinons ce code pièce par pièce. L'élément HTML <a> est le lien d'installation. L'attribut href contient un lien direct vers le fichier XPI de l'extension, c'est ce qui sera affiché dans la barre d'adresse lorsque le pointeur survole le lien. Les visiteurs peuvent enregistrer le fichier XPI sur leur disque facilement en cliquant dessus et en choisissant « Enregistrer sous… »
Lorsqu'on clique sur le lien, il appelle la fonction install en passant l'objet d'évènement en paramètre.
L'installation crée d'abord un bloc de paramètres :
var params = {
"Foo": { URL: aEvent.target.href,
IconURL: aEvent.target.getAttribute("iconURL"),
Hash: aEvent.target.getAttribute("hash"),
toString: function () { return this.URL; }
};
Ceci spécifie le nom (Foo) à afficher dans le dialogue de confirmation, l'URL où trouver l'extension (qui, souvenez-vous, est l'attribut href du lien), l'URL de l'icône à afficher dans le dialogue de confirmation, une empreinte de contrôle du fichier xpi (pour protéger contre les téléchargements corrompus), et une fonction toString qui permettra à ce code de fonctionner avec les versions 0.8 et antérieures de Firefox. Vous pouvez également utiliser l'ancien style de bloc de paramètres ({ "Foo": aEvent.target.href }) si vous le désirez et que vous n'avez pas d'icône à afficher dans le dialogue de confirmation.
InstallTrigger.install est ensuite appelée pour installer l'élément défini dans le bloc de paramètres.
return false;
Cette dernière partie est la plus importante : la fonction d'installation doit renvoyer false afin que, lorsqu'on clique sur le lien, seul le script soit exécuté et le href du lien ne soit pas chargé dans le navigateur. Si vous oubliez cette étape, l'utilisateur risque de voir deux dialogues d'installation, étant donné que vous avez effectivement invoqué deux requêtes d'installation : une avec InstallTrigger et l'autre en essayant de charger directement le fichier XPI.
Paramètres disponibles pour l'objet d'installation
La méthode InstallTrigger.install accepte un objet JavaScript en paramètre, dont plusieurs propriétés seront utilisées au cours de l'installation.
URL
La propriété URL spécifie l'adresse URL du fichier XPI à installer. Cette propriété est obligatoire.
IconURL
La propriété IconURL indique une icône à utiliser dans le dialogue d'installation. Cette propriété est facultative. Si aucune icône n'est spécifiée, l'icône par défaut sera utilisée, habituellement une pièce de puzzle verte. L'icône peut être dans n'importe quel format d'image accepté par Firefox, et doit être d'une taille de 32×32 pixels.
Hash
La propriété Hash spécifie une empreinte cryptographique du contenu du fichier XPI. Celle-ci est utilisée pour vérifier le fichier téléchargé, pour empêcher d'installer, par exemple, un fichier corrompu servi par un serveur de téléchargement miroir. Toute fonction de hachage supportée par nsICryptoHash peut être utilisée. L'empreinte est spécifiée de la manière fonction de hachage:empreinte de contrôle, par exemple, sha1:28857e60d043447c5f4550853f2d40770b326a13.
toString()
La propriété toString() devrait renvoyer l'URL du fichier XPI, pour la compatibilité avec les versions de Firefox antérieures à 1.0, et d'autres applications comme Seamonkey.
Thèmes
À peu près tout ce qui est décrit ci-dessus s'applique également aux thèmes, sauf qu'il faut utiliser la fonction installChrome. Comme beaucoup de sites installaient des extensions en donnant un lien direct vers un fichier XPI en se reposant sur la gestion de contenu interne au navigateur pour invoquer la fenêtre de confirmation, certains procèdent (incorrectement) de même pour les fichiers JAR de thèmes et se demandent pourquoi ils ne sont pas détectés et installés automatiquement. En fait, XPI est une extension spécifique à Mozilla, et ce format peut donc être géré de façon spéciale, mais ce n'est pas le cas de JAR. Tous les fichiers .jar ne sont pas des thèmes pour Firefox, donc si vous cliquez sur un lien vers un .jar vous verrez un dialogue d'enregistrement de fichier. Pour cette raison, vous devriez toujours utiliser l'API InstallTrigger pour installer des thèmes.
Une note à propos d'updateEnabled()
InstallTrigger expose une fonction appelée updateEnabled que certains peuvent être tentés d'appeler avant InstallTrigger.install. Ce n'est pas nécessaire étant donné que l'installation appelle elle-même updateEnabled en interne. De plus, l'appel à updateEnabled peut causer des problèmes si votre site de distribution n'est pas dans la liste blanche de l'utilisateur, parce que Firefox affiche le message « Installation bloquée » uniquement lorsque installChrome est appelé, ou lorsqu'un fichier XPI est chargé. Donc, si vous avez du code qui ressemble à ceci :
if (InstallTrigger.updateEnabled())
InstallTrigger.install({"MonExtension": "foo.xpi"});
… et que votre site n'est pas dans la liste blanche, lorsque l'utilisateur déclenchera ce code, updateEnabled renverra false étant donné que votre site n'est pas dans la liste autorisée, et puisque c'est updateEnabled qui a fait ce constat et pas une demande d'installation, l'utilisateur ne verra rien du tout se produire.
Par conséquent, vous devriez uniquement utiliser updateEnabled pour afficher du contenu dans la page pour avertir l'utilisateur que l'installation est désactivée, ou que votre site n'est pas dans la liste blanche, et ne pas le placer dans le chemin de code menant à l'installation.
(* de toute manière, ceci ne doit pas vous empêcher de développer des systèmes d'installation plus ambitieux, cette documentation est uniquement fournie comme un guide dans l'espoir que la plupart des distributeurs d'extensions l'utiliseront. Elle se comporte en effet bien dans la plupart des cas.)