Créer un thème

Mettre en place l'environement de développement

Les thèmes et extensions sont empaquetés et distribués dans des fichiers ZIP ou Paquets, avec l'extension de fichier XPI (prononcé “zippy”).

Un exemple du contenu d'un fichier XPI typique d'un thème:

example.xpi:
              /install.rdf
              /chrome.manifest
              /preview.png
              /icon.png
              /chrome/
                     browser/
                     communicator/
                     global/
                     mozapps/

Nous souhaitons créer une structure de fichier similaire à celle présentée ci-dessus pour notre tutoriel, donc commençons par créer un dossier pour votre thème quelque part sur votre disque dure (ex: C:\themes\mon_theme\ ou ~/themes/mon_theme/). Dans votre nouveau dossier de thème, créez deux nouveaux fichiers texte vides, l'un nommé chrome.manifest et l'autre appelé install.rdf. Le fichier preview.png est montré comme une prévisulaisation du thème dans le paneau des thèmes de la fenêtre des modules complémentaires. Le fichier icon.png est utilisé comme une icône dans le même paneau. Nous les laisserons de côté pour l'instant, sauf si vous disposez déjà d'éléments graphiques que vous souhaitez utiliser.

Les répertoires restants seront extraits depuis le thème par défaut. Pour commencer, vous devrez créer un répertoire quelque part. Copiez votre fichier omni.ja d'installation Firefox dans ce répertoire. La localisation diffère suivant le système d'exploitation :

Linux: /usr/lib/MozillaFirefox/chrome/classic.jar ou /usr/lib/firefox-*.*.*/omni.ja

Windows: \Program Files\Mozilla Firefox\omni.ja

Mac OS X: /Applications/Firefox.app/Contents/MacOS/omni.ja

Maintenant, ouvrez (ou extrayez) ce fichier dans le répertoire que vous avez créé. Il contient plusieurs dossiers, modules, jssubloader et autres. Les fichiers dont vous aurez besoin sont situés dans le dossier chrome\toolkit\skin\classic.

Créez un dossier nommé chrome dans le dossier de votre thème. Ensuite, le contenu des répertoires suivants dans leur dossiers respectifs de ce dossier.

1. global dans chrome/global
2. mozapps dans chrome/mozapps

À présent que vous avez copié les dossiers global et mozapps, une poignée d'autres dossiers de l'archive browser/omni.ja sont requis. Ils sont situés dans le dossier du navigateur l'emplacement mentionné ci-dessus. Les fichiers dont nous aurons besoins dans l'archive browser/omni.ja sont situés dans chrome/browser/skin/classic.

Copiez les contenu des répertoires suivants dans leurs dossiers respectifs. Ceci nous donnera une base de style avec laquelle nous allons commencer à travailler.

1. browser dans chrome/browser/
2. communicator dans chrome/communicator/

La structure de vos répertoires doit être comme suit :

<ext path>/
          /install.rdf
          /chrome.manifest
          /chrome/
                 browser/
                 communicator/
                 global/
                 mozapps/

Après ces étapes, nous vous recommandons de lire l'article Setting up extension development environment et les indications qui vous y seront données. En particulier, vous devrez installer le DOM Inspector, que nous utiliserons dans les étapes suivantes

Création du Manifeste d'Installation (Install Manifest) Create the Install Manifest

Ouvrez le fichier nommé install.rdf que vous avez créé au en tête de la hierarchie de votre répertoire d'extention et ajoutez y le contenu suivant :

<?xml version="1.0"?>

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

  <Description about="urn:mozilla:install-manifest">
    <em:id>[email protected]</em:id>
    <em:version>1.0</em:version>
    <em:type>4</em:type>
   
    <!-- Target Application this theme can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>29.0</em:minVersion>
        <em:maxVersion>32.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>My Theme</em:name>
    <em:internalName>sample</em:internalName>
    <em:description>A test extension</em:description>
    <em:creator>Your Name Here</em:creator>
    <em:homepageURL>https://www.example.com/</em:homepageURL>
  </Description>      
</RDF>

• [email protected] - c'est l'ID de l'extension. Il s'agit d'un nom de votre choix qui permet d'identifier votre extension sous la forme d'une e-mail (notez que ce n'est pas votre e-mail personnelle). Créez un nom unique. Vous pouvez vous aider d'un GUID. NOTE : ce paramètre DOIT être au format d'une e-mail, même si elle ne DOIT PAS être une e-mail authentique et valide. (exemple.exemple.exemple)
• 4 - le type de l'add-on. '4' informe qu'il s'agit de l'installation d'un thème. Si vous souhaitiez installer une extension ce serait 2 (voir Install Manifests#type pour les autres types de codes).
• {ec8030f7-c20a-464f-9b0e-13a3a9e97384} - ID d'application de Firefox.
• 29.0 - Le numero de la version exacte à partir de laquelle votre extension fonctionne. N'utilisez jamais une asterisque * dans minVersion, cela ne fera pas ce à quoi vous vous attendez.
• 32.* - La version la plus récente de Firefox avec laquelle votre extension va fonctionner. Ne pas définir à une version plus récente que celle actuellement disponible ! Dans ce cas, "32.*" indique que l'extension fonctionne avec Firefox 32 et toutes les sous-version 32.x. Les thèmes sont compatibles par défaut, tant que vous ne définissez pas un mode de compatiblité stricte pour votre thème.

Si vous obtenez un message qui vous informe que install.rdf est malformé, il est utile de le charger dans Firefox en utilisant la commande Fichier->Ouvrir un fichier et il vous rapportera les erreurs XML.

Voir Install Manifests pour une liste complète des propriétés requises et optionelles.

Sauvegardez le fichier.

Styliser l'interface du navigateur avec CSS

L'interface utilisateur de Firefox est écrite en XUL et JavaScript. XUL est une grammaire XML qui fournit des modules d'interface utilisateur comme les boutons, menus, barres d'outils, arbres, etc. Les actions utilisateur possèdent leurs fonctionnalités en utilisant du JavaScript. Ces éléments XUL sont stylisés en utilisant du CSS. Si vous ne connaissez pas le CSS, ce sera une pente abrupte de votre apprentissage, et vous devriez essayer des tutoriels basés sur le HTML pour commencer.

L'interface utilisateur du navigateur a absolument aucun style de base - si vous essayez de commencer avec un thème vide, Firefox deviendra inutilisable, car les boutons seront uniquement du texte. C'est pourquoi nous avons copié le style par défaut dans l'étape d'organisation.

Lors de l'écriture d'un thème, la manière la plus simple de déterminer quels selcteurs CSS vous avez besoin d'écrire est d'utiliser l'inspecteur DOM que vous devriez avoir installé à l'étape d'organisation. Vous pouvez utiliser cela pour inspecter n'importe quel élément dans une page web ou un document XUL, ce qui en fait quelque chose d'important pour les thèmes.

Modifier le style de la barre d'outils

Ouvrez maintenant l'inspecteur DOM (Dans le menu "Outils") et allez dans "Fichier->Inspecter le document chrome". Ce devrait être un menu contenant tous les documents XUL actuellement ouverts dans Firefox.
Prenez le premier document avec un titre de page web, comme "Page de démarrage Firefox" et sélectionnez-le.

Pour ce tutoriel, nous allons modifier la couleur de font des barres d'outils. Sélectionnez l'outil de recherche de noeud (la case de la flèche pour en voir plus dans le coin en haut à gauche de l'inspecteur DOM) et cliquez dans n'importe quel espace non-utilisé d'une barr d'outils. Cela devrait sélectionner un noeud de type "xul:toolbar" dans l'inspecteur DOM.

À partir d'ici, vous pouvez vous amuser avec différents styles pour la barre d'outils et les éléments associés. Par défaut, le panneau de droite devrait montrer le noeud DOM, qui possède des informations importantes comme la classe CSS et le noeud id. L'élément lui-même est de l'id navigator-toolbox, avec aucune idée. Pour accorder son style avec notre thème, nous avons besoin d'écrire une règle de sélecteur pour sélectionner cette classe.

Ouvrez le fichier chrome/browser/browser.css de votre thème. Cherchez dans ce fichier le sélecteur #navigator-toolbox, et ajoutez-lui cette règle background: orange;

Sauvegardez le fichier.

Chrome URIs

Next, we have to tell Firefox where to find the theme files for your theme. CSS, XUL, and other files are part of "Chrome Packages" - bundles of user interface components which are loaded via chrome:// URIs. Rather than load the browser from disk using a file:// URI (since the location of Firefox on the system can change from platform to platform and system to system), Mozilla developers came up with a solution for creating URIs to content that the installed add-on knows about.

The browser window is: chrome://browser/content/browser.xul. Try typing this URL into the location bar in Firefox!

Chrome URIs consist of several components:

• Firstly, the URI scheme (chrome) which tells Firefox's networking library that this is a Chrome URI. It indicates that the content of the URI should be handled as a (chrome). Compare (chrome) to (http) which tells Firefox to treat the URI as a web page.
• Secondly, a package name (in the example above, browser) which identifies the bundle of user interface components.
• Thirdly, the type of data being requested. There are three types: content (XUL, JavaScript, XBL bindings, etc. that form the structure and behavior of an application UI), locale (DTD, .properties files etc that contain strings for the UI's localization), and skin (CSS and images that form the theme of the UI)
• Finally, the path of a file to load.

So, chrome://foo/skin/bar.png loads the file bar.png from the foo theme's skin section.

When you load content using a Chrome URI, Firefox uses the Chrome Registry to translate these URIs into the actual source files on disk (or in JAR packages).

Create a Chrome Manifest

The Chrome Manifest is the file that maps these Chrome URIs to your theme's files. For more information on Chrome Manifests and the properties they support, see the Chrome Manifest Reference.

Open the file called chrome.manifest that you created alongside the chrome directory at the root of your extension's source folder hierarchy.

Add in this code:

skin    browser         sample   chrome/browser/
skin    communicator    sample   chrome/communicator/
skin    global          sample   chrome/global/
skin    mozapps         sample   chrome/mozapps/

Don't forget the trailing slash, "/"! Without it, the package won't be registered. The third column needs to match your theme's internalName value from the install manifest above.

This maps skin directories to locations within your theme. For example, the line skin browser sample skin/browser/ means "when the user has the sample theme selected, use the directory browser/ to look up skins for the browser package." More concisely, this means that the URL chrome://browser/skin/some/path/file.css will look for a file browser/some/path/file.css in your theme's root directory.

Save the file.

Test

First, we need to tell Firefox about your theme. During the development phase for Firefox versions 2.0 and higher, you can point Firefox to the folder where you are developing the theme, and it'll load it up every time you restart Firefox.

1. Locate your profile folder and beneath it the profile you want to work with (e.g. Firefox/Profiles/<profile_id>.default/).
2. Open the extensions/ folder, creating it if need be.
3. Create a new text file and put the full path to your development folder inside (e.g. C:\themes\my_theme\ or ~/themes/my_theme/). Windows users should retain the OS' slash direction, and everyone should remember to include a closing slash and remove any trailing spaces.
4. Save the file with the id of your theme as its name (e.g. [email protected]). No file extension.

Now you should be ready to test your theme!

Start Firefox. Firefox will detect the text link to your theme directory and install the theme. Your theme will not be active the first time you install, and you will need to click "Enable" and restart before you can see your change. After it restarts this second time, you should see the background color of the toolbars is displayed in orange now.

You can now go back and make additional changes to your css files, close and restart Firefox, and see the updates.

Package

Now that your theme works, you can package it for deployment and installation.

Zip up the contents of your theme's folder (not the theme folder itself), and rename the zip file to have a .xpi extension. In Windows, you can do this easily by selecting all the files and subfolders in your extension folder, right click and choose "Send To -> Compressed (Zipped) Folder". A .zip file will be created for you. Just rename it and you're done!

On Mac OS or Linux, you can use the command-line zip tool:

zip -r my_theme.xpi install.rdf chrome.manifest browser communicator global mozapps

Or, if you have 7-Zip installed, you can use that for zipping it up:

7z a -tzip my_theme.xpi chrome chrome.manifest

Note: The command-line tool will update an existing zip file, not replace it - so if you have files you've deleted from your theme, be sure to remove the .xpi file before running the zip command again.

Now upload the .xpi file to your server, making sure it's served as application/x-xpinstall. You can link to it and allow people to download and install it. For the purposes of just testing our .xpi file we can just drag it into the Add-ons Manager via "Tools -> Add-ons Manager", or open it using "File -> Open File...".