1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
---
title: API de restauration de session
slug: Archive/Add-ons/API_de_restauration_de_session
tags:
- Extensions
translation_of: Archive/Add-ons/Session_store_API
---
<p><a href="fr/Firefox_2">Firefox 2</a> introduit la sauvegarde de session, une nouvelle fonctionnalité qui permet aux <a href="fr/Extensions">extensions</a> de sauvegarder et restaurer des données entre différentes sessions de Firefox. Une API simple permet aux extensions d'accéder à cette fonctionnalité.
</p><p>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 <code>setTabValue()</code> 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 <code>getTabValue()</code> pour récupérer ces données lorsque l'onglet est restauré.
</p><p>L'API de sauvegarde de session est implémentée en utilisant l'interface <code><a href="fr/NsISessionStore">nsISessionStore</a></code>.
</p>
<h2 id="Savoir_quand_restaurer" name="Savoir_quand_restaurer">Savoir quand restaurer</h2>
<p>Chaque fois que Firefox est sur le point de restaurer un onglet, un événement de type <code>SSTabRestoring</code> 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 :
</p>
<pre>function myExtensionHandleRestore(aEvent) {
Components.classes["@mozilla.org/consoleservice;1"].
getService(Components.interfaces.nsIConsoleService).
logStringMessage("Restauration d'onglets");
};
document.addEventListener("SSTabRestoring", myExtensionHandleRestore, false);
</pre>
<p>Il vous suffit de remplacer le contenu de la fonction <code>myExtensionHandleRestore()</code> avec vos propres actions à effectuer lorsque l'onglet est récupéré. Dans cet exemple, l'interface <code><a href="fr/NsIConsoleService">nsIConsoleService</a></code> sert à afficher un message dans <a href="fr/Console_JavaScript">la console JavaScript</a>.
</p><p>Cet événement est généré juste avant que l'onglet ne soit récupéré. Un événement de type <code>SSTabRestored</code> est déclenché à chaque fois qu'un onglet a fini d'être récupéré.
</p>
<h2 id="Le_processus_de_restauration_de_session" name="Le_processus_de_restauration_de_session">Le processus de restauration de session</h2>
<p>La séquence exacte d'événements qui surviennent lorsqu'une session est en cours de restauration est la suivante :
</p>
<ol><li> 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.
</li><li> 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.
</li></ol>
<p>Ensuite, les étapes suivantes sont lancées pour chaque onglet récupéré :
</p>
<ol><li> Soit un onglet existant est réutilisé, soit un nouvel onglet est créé. Dans ce dernier cas, un événement <code>TabOpen</code> est généré.
</li><li> Les attributs XUL persistants de l'onglet (ceux dus aux appels de <code><a href="fr/NsISessionStore#persistTabAttribute.28.29">persistTabAttribute()</a></code>) et les permissions sont restaurés.
</li><li> L'événement <code>SSTabRestoring</code> est généré.
</li><li> L'onglet reçoit l'indication de l'URL à afficher.
</li><li> Lorsque la page est chargée, les champs de saisie et les barres de défilement sont restaurés.
</li><li> Finalement, l'événement <code>SSTabRestored</code> est généré.
</li></ol>
<p>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 <code>SSTabRestoring</code>. Si vous voulez faire une action après le chargement de la page, vous devrez surveiller <code>SSTabRestored</code>.
</p><p>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 <code>originalTarget</code> de l'événement.
</p><p>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 <code>SSTabRestored</code>.
</p>
<h2 id="Utilisation_de_l.27API_de_restauration_de_session" name="Utilisation_de_l.27API_de_restauration_de_session">Utilisation de l'API de restauration de session</h2>
<p>Cette section propose quelques exemples simples sur l'emploi de l'API de restauration de session.
</p>
<h3 id="Sauvegarder_une_valeur_avec_un_onglet" name="Sauvegarder_une_valeur_avec_un_onglet">Sauvegarder une valeur avec un onglet</h3>
<p>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.
</p>
<pre class="eval"> 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);
</pre>
<p>Ce code définit une valeur de <var>dataToAttach</var> à la clef <code>"key-name-here"</code>. La donnée peut être n'importe quel objet JavaScript.
</p>
<h3 id="Lire_une_valeur_sauvegard.C3.A9e" name="Lire_une_valeur_sauvegard.C3.A9e">Lire une valeur sauvegardée</h3>
<p>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 :
</p>
<pre class="eval"> 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");
</pre>
<p>Après l'exécution de ce code, la variable <var>retrievedData</var> contient la valeur sauvegardée correspondante à la clef <code>"key-name-here"</code>. La variable <var>retrievedData</var> est indéfinie (<code>undefined</code>) si aucune valeur correspondant à cette clef n'a été sauvegardée.
</p>
<h3 id="Effacer_une_valeur_associ.C3.A9e_.C3.A0_un_onglet" name="Effacer_une_valeur_associ.C3.A9e_.C3.A0_un_onglet">Effacer une valeur associée à un onglet</h3>
<p>Pour effacer une valeur d'un onglet, vous pouvez utiliser un code similaire à celui-ci :
</p>
<pre class="eval"> var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
getService(Components.interfaces.nsISessionStore);
var currentTab = getBrowser().selectedTab;
deleteTabValue(currentTab, "key-name-here");
</pre>
<h3 id="Remarques" name="Remarques">Remarques</h3>
<p>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.
</p>
<h2 id="Voir_.C3.A9galement" name="Voir_.C3.A9galement">Voir également</h2>
<p><a href="fr/NsISessionStore">nsISessionStore</a>
</p>
|
