initial commit

1 files changed, 82 insertions, 0 deletions

diff --git a/files/fr/archive/add-ons/api_de_restauration_de_session/index.html b/files/fr/archive/add-ons/api_de_restauration_de_session/index.html
new file mode 100644
index 0000000000..dfae935362
--- /dev/null
+++ b/files/fr/archive/add-ons/api_de_restauration_de_session/index.html
@@ -0,0 +1,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>