API de restauration de session

Firefox 2 introduit la sauvegarde de session, une nouvelle fonctionnalité qui permet aux extensions de sauvegarder et restaurer des données entre différentes sessions de Firefox. Une API simple permet aux extensions d'accéder à cette fonctionnalité.

Un des cas où l'utilisation de cette fonctionnalité peut être cruciale pour une extension est que Firefox 2 permet à l'utilisateur d'annuler la fermeture des onglets. Pour récupérer proprement l'état de votre extension lorsqu'un onglet est restauré, celle-ci doit utiliser la méthode setTabValue() de l'API de sauvegarde de session pour enregistrer toutes les données devant pouvoir être restaurées par la suite, puis appeler la méthode getTabValue() pour récupérer ces données lorsque l'onglet est restauré.

L'API de sauvegarde de session est implémentée en utilisant l'interface nsISessionStore.

Savoir quand restaurer

Chaque fois que Firefox est sur le point de restaurer un onglet, un événement de type SSTabRestoring est généré. Si votre extension doit pouvoir restaurer des données lorsqu'un onglet est récupéré, vous pouvez mettre en place un listener comme ceci :

function myExtensionHandleRestore(aEvent) {
  Components.classes["@mozilla.org/consoleservice;1"].
             getService(Components.interfaces.nsIConsoleService).
             logStringMessage("Restauration d'onglets");
};

document.addEventListener("SSTabRestoring", myExtensionHandleRestore, false);

Il vous suffit de remplacer le contenu de la fonction myExtensionHandleRestore() avec vos propres actions à effectuer lorsque l'onglet est récupéré. Dans cet exemple, l'interface nsIConsoleService sert à afficher un message dans la console JavaScript.

Cet événement est généré juste avant que l'onglet ne soit récupéré. Un événement de type SSTabRestored est déclenché à chaque fois qu'un onglet a fini d'être récupéré.

Le processus de restauration de session

La séquence exacte d'événements qui surviennent lorsqu'une session est en cours de restauration est la suivante :

1. Un état de session est sur le point d'être restauré. Cela peut se faire au démarrage ou en réponse à une annulation de fermeture d'onglet, puisque les sessions d'onglets fermés sont récupérées onglet par onglet.
2. De nouvelles fenêtres sont ouvertes si nécessaire (une pour chaque fenêtre qui a été sauvegardée dans l'enregistrement de session), les cookies et la liste des onglets récemment fermés sont restaurés.

Ensuite, les étapes suivantes sont lancées pour chaque onglet récupéré :

1. Soit un onglet existant est réutilisé, soit un nouvel onglet est créé. Dans ce dernier cas, un événement TabOpen est généré.
2. Les attributs XUL persistants de l'onglet (ceux dus aux appels de persistTabAttribute()) et les permissions sont restaurés.
3. L'événement SSTabRestoring est généré.
4. L'onglet reçoit l'indication de l'URL à afficher.
5. Lorsque la page est chargée, les champs de saisie et les barres de défilement sont restaurés.
6. Finalement, l'événement SSTabRestored est généré.

Si vous voulez définir des permissions ou manipuler un onglet récupéré avant que la page y soit chargée, vous devrez surveiller SSTabRestoring. Si vous voulez faire une action après le chargement de la page, vous devrez surveiller SSTabRestored.

Ces deux événements sont générés systématiquement pour chaque onglet récupéré. Vous pouvez déterminer quel onglet est concerné par la récupération grâce au champ originalTarget de l'événement.

Il n'y a pas vraiment de moyen pour déterminer quand le dernier onglet a été récupéré à moins de déterminer combien d'onglets doivent être récupérés puis de compter le nombre d'événements SSTabRestored.

Utilisation de l'API de restauration de session

Cette section propose quelques exemples simples sur l'emploi de l'API de restauration de session.

Sauvegarder une valeur avec un onglet

Le code suivant permet d'attacher un couple clef/valeur à un onglet de telle façon que lorsque l'onglet est récupéré, ce couple le soit également.

 var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
                             getService(Components.interfaces.nsISessionStore);
 var currentTab = getBrowser().selectedTab;
 var dataToAttach = "Je veux attacher ceci";
 ss.setTabValue(currentTab, "key-name-here", dataToAttach);

Ce code définit une valeur de <var>dataToAttach</var> à la clef "key-name-here". La donnée peut être n'importe quel objet JavaScript.

Lire une valeur sauvegardée

Vous pouvez lire une valeur associée à un onglet n'importe quand (que l'onglet soit ou non dans un processus de récupération) en utilisant le code suivant :

 var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
                             getService(Components.interfaces.nsISessionStore);
 var currentTab = getBrowser().selectedTab;
 var retrievedData = ss.getTabValue(currentTab, "key-name-here");

Après l'exécution de ce code, la variable <var>retrievedData</var> contient la valeur sauvegardée correspondante à la clef "key-name-here". La variable <var>retrievedData</var> est indéfinie (undefined) si aucune valeur correspondant à cette clef n'a été sauvegardée.

Effacer une valeur associée à un onglet

Pour effacer une valeur d'un onglet, vous pouvez utiliser un code similaire à celui-ci :

 var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
                             getService(Components.interfaces.nsISessionStore);
 var currentTab = getBrowser().selectedTab;
 deleteTabValue(currentTab, "key-name-here");

Remarques

Les fonctions de restauration et de lecture des valeurs d'une fenêtre fonctionnent exactement comme les fonctions pour les onglets portant des noms similaires.

Voir également

nsISessionStore