Session store API

Session store 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) {
  var tab = event.originalTarget;        /* the tab being restored */
  var uri = tab.linkedBrowser.contentDocument.location;  /* the tab's URI */
  Components.classes["@mozilla.org/consoleservice;1"]
            .getService(Components.interfaces.nsIConsoleService)
            .logStringMessage("restoring tab: " + uri);
};
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 fires each time a tab has finished restoring. It's worth noting that this event is sent even if tab loading at startup is deferred until the user selects the tab.

Restoring without restarting

Firefox 3.6 knows how to save session store data when the last browser window closes, even if there are still other windows open. Similarly, it can now restore the user's session while in that state. In other words, it's now possible for sessions to be restored even without the browser quitting and being relaunched. This is something you may need to keep in mind if you rely on the behavior of the session store system.

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 = gBrowser.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 = gBrowser.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 = gBrowser.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.

Starting in Firefox 3.5, notifications are sent after reading session store data and before using it, as well as immediately before writing it back to disk. See the list in Observer Notifications.

Using the session store API in SeaMonkey

There are a number of differences between the session store API in Firefox and the API in SeaMonkey 2.0:

• The class name is @mozilla.org/suite/sessionstore;1

var ss = Components.classes["@mozilla.org/suite/sessionstore;1"]
                   .getService(Components.interfaces.nsISessionStore);

• When restoring a window, closed tabs in that window are not currently restored.
• When closing a tab, SeaMonkey does not generate SSTab events. This means that you cannot currently tell if a tab has been saved or restored. However SeaMonkey reuses the browser element (up to the undo close tab limit) which means that you can set state on the browser element and it will be restored with the tab.

See also

nsISessionStore