Session store API

  • Revision slug: Session_store_API
  • Revision title: Session store API
  • Revision id: 127561
  • Created:
  • Creator: Jomel
  • Is current revision? No
  • Comment /* Deleting a value associated with a tab */ Correcting example

Revision Content

Firefox 2 introduces session store, a new feature that makes it possible for extensions to easily save and restore data across Firefox sessions. There is a simple API that lets extensions access the session store feature.

One key scenario in which supporting this feature can be crucial for an extension: Firefox 2 lets users undo the closing of tabs. In order to properly restore your extension's state when a tab is restored, it needs to use the session store API's setTabValue() method to save any data it will need in order to restore its state, and then call getTabValue() to retrieve the previous setting when the tab is restored.

The Session Store API is implemented using the nsISessionStore interface.

Knowing when to restore

Each time Firefox is about to restore a tab, an event of type SSTabRestoring is sent. If your extension wants to be able to restore data when tabs are restored, you can install a listener like this:

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

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

Simply replace the contents of the function myExtensionHandleRestore() with whatever you need to do when the tab is restored. In this example, nsIConsoleService is used to display a message to the console.

This event is sent just before a tab is restored. An event of type SSTabRestored is sent after the last tab is restored.

The session restore process

The exact sequence of events that occurs when a session is being restored is:

  1. A session state is about to be restored. This can be on startup or in response to Undo Close Tab, since closed tabs are restored as single-tab sessions.
  2. New windows are opened as required (one for each window that was saved in the session store), and cookies and the list of recently closed tabs are restored.

After that, the following steps are taken for each tab being restored:

  1. Either an existing tab is reused or a new tab is created. In the latter case, a TabOpen event is sent.
  2. The tab's persistent XUL attributes (those saved due to calls to persistTabAttribute()) and permissions are restored.
  3. The SSTabRestoring event is sent.
  4. The tab is told to load the URL it should be displaying.
  5. When the page is finished loading, text fields and scroll state are restored.
  6. Finally, the SSTabRestored event is sent.

If you want to set permissions or otherwise manipulate a restored tab before the page is loaded into it, you should watch SSTabRestoring. If you want to do something after the page is loaded, you should watch SSTabRestored.

Both events are always sent for each tab being restored. You can determine which tab is being restored by looking at the event's originalTarget field.

There's not really a way to determine when the last tab has been restored unless you determine how many tabs need to be restored then count the SSTabRestored events.

Using the session store API

This section provides a few simple examples of how to make use of the session store API.

Saving a value with a tab

The following code will attach a key/value pair to a tab, so that when the tab is restored, that pair is still associated with it.

 var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
                             getService(Components.interfaces.nsISessionStore);
 var currentTab = getBrowser().selectedTab;
 var dataToAttach = "I want to attach this";
 ss.setTabValue(currentTab, "key-name-here", dataToAttach);

This code sets the value of the key "key-name-here" to dataToAttach. You may use any JavaScript object as the data.

Fetching a saved value

You can fetch a value associated with a tab at any time (whether the tab is in the process of being restored or not), using code similar to the following:

 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");

After this code executes, the variable retrievedData contains the value saved for the key "key-name-here". retrievedData is undefined if there is no value saved for that key name.

Deleting a value associated with a tab

To delete a value from a tab, you can use code similar to the following:

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

Remarks

The window value save and restore functions work exactly like the tab-based functions by similar names.

See also

nsISessionStore

{{ wiki.languages( { "es": "es/API_de_restauraci\u00f3n_de_sesi\u00f3n", "fr": "fr/API_de_restauration_de_session", "ja": "ja/Session_store_API", "pl": "pl/API_przechowywania_sesji" } ) }}

Revision Source

<p><a href="en/Firefox_2">Firefox 2</a> introduces session store, a new feature that makes it possible for <a href="en/Extensions">extensions</a> to easily save and restore data across Firefox sessions.  There is a simple API that lets extensions access the session store feature.
</p><p>One key scenario in which supporting this feature can be crucial for an extension: Firefox 2 lets users undo the closing of tabs.  In order to properly restore your extension's state when a tab is restored, it needs to use the session store API's <code>setTabValue()</code> method to save any data it will need in order to restore its state, and then call <code>getTabValue()</code> to retrieve the previous setting when the tab is restored.
</p><p>The Session Store API is implemented using the <code><a href="en/NsISessionStore">nsISessionStore</a></code> interface.
</p>
<h2 name="Knowing_when_to_restore">Knowing when to restore</h2>
<p>Each time Firefox is about to restore a tab, an event of type <code>SSTabRestoring</code> is sent.  If your extension wants to be able to restore data when tabs are restored, you can install a listener like this:
</p>
<pre>function myExtensionHandleRestore(aEvent) {
  Components.classes["@mozilla.org/consoleservice;1"].
             getService(Components.interfaces.nsIConsoleService).
             logStringMessage("restoring tabs");
};

document.addEventListener("SSTabRestoring", myExtensionHandleRestore, false);
</pre>
<p>Simply replace the contents of the function <code>myExtensionHandleRestore()</code> with whatever you need to do when the tab is restored.  In this example, <code><a href="en/NsIConsoleService">nsIConsoleService</a></code> is used to display a message to the <a href="en/JavaScript_Console">console</a>.
</p><p>This event is sent just before a tab is restored.  An event of type <code>SSTabRestored</code> is sent after the last tab is restored.
</p>
<h2 name="The_session_restore_process">The session restore process</h2>
<p>The exact sequence of events that occurs when a session is being restored is:
</p>
<ol><li> A session state is about to be restored.  This can be on startup or in response to Undo Close Tab, since closed tabs are restored as single-tab sessions.
</li><li> New windows are opened as required (one for each window that was saved in the session store), and cookies and the list of recently closed tabs are restored.
</li></ol>
<p>After that, the following steps are taken for each tab being restored:
</p>
<ol><li> Either an existing tab is reused or a new tab is created.  In the latter case, a <code>TabOpen</code> event is sent.
</li><li> The tab's persistent XUL attributes (those saved due to calls to <code><a href="en/NsISessionStore#persistTabAttribute.28.29">persistTabAttribute()</a></code>) and permissions are restored.
</li><li> The <code>SSTabRestoring</code> event is sent.
</li><li> The tab is told to load the URL it should be displaying.
</li><li> When the page is finished loading, text fields and scroll state are restored.
</li><li> Finally, the <code>SSTabRestored</code> event is sent.
</li></ol>
<p>If you want to set permissions or otherwise manipulate a restored tab before the page is loaded into it, you should watch <code>SSTabRestoring</code>.  If you want to do something after the page is loaded, you should watch <code>SSTabRestored</code>.
</p><p>Both events are always sent for each tab being restored.  You can determine which tab is being restored by looking at the event's <code>originalTarget</code> field.
</p><p>There's not really a way to determine when the last tab has been restored unless you determine how many tabs need to be restored then count the <code>SSTabRestored</code> events.
</p>
<h2 name="Using_the_session_store_API">Using the session store API</h2>
<p>This section provides a few simple examples of how to make use of the session store API.
</p>
<h3 name="Saving_a_value_with_a_tab">Saving a value with a tab</h3>
<p>The following code will attach a key/value pair to a tab, so that when the tab is restored, that pair is still associated with it.
</p>
<pre class="eval"> var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
                             getService(Components.interfaces.nsISessionStore);
 var currentTab = getBrowser().selectedTab;
 var dataToAttach = "I want to attach this";
 ss.setTabValue(currentTab, "key-name-here", dataToAttach);
</pre>
<p>This code sets the value of the key "key-name-here" to <var>dataToAttach</var>.  You may use any JavaScript object as the data.
</p>
<h3 name="Fetching_a_saved_value">Fetching a saved value</h3>
<p>You can fetch a value associated with a tab at any time (whether the tab is in the process of being restored or not), using code similar to the following:
</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>After this code executes, the variable <var>retrievedData</var> contains the value saved for the key "key-name-here".  <var>retrievedData</var> is undefined if there is no value saved for that key name.
</p>
<h3 name="Deleting_a_value_associated_with_a_tab">Deleting a value associated with a tab</h3>
<p>To delete a value from a tab, you can use code similar to the following:
</p>
<pre class="eval"> var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
                             getService(Components.interfaces.nsISessionStore);
 var currentTab = getBrowser().selectedTab;
 ss.deleteTabValue(currentTab, "key-name-here");
</pre>
<h3 name="Remarks">Remarks</h3>
<p>The window value save and restore functions work exactly like the tab-based functions by similar names.
</p>
<h2 name="See_also">See also</h2>
<p><a href="en/NsISessionStore">nsISessionStore</a>
</p>{{ wiki.languages( { "es": "es/API_de_restauraci\u00f3n_de_sesi\u00f3n", "fr": "fr/API_de_restauration_de_session", "ja": "ja/Session_store_API", "pl": "pl/API_przechowywania_sesji" } ) }}
Revert to this revision