API przechowywania sesji

Firefox 2 wprowadza mechanizm przechowywania sesji który umożliwia rozszerzeniom łatwo zapisywać i przywracać dane pomiędzy sesjami Firefoksa. Istnieje też proste API, które umożliwia rozszerzeniom łatwy dostęp do zapisanych sesji.

Przykładem sytuacji, w której wsparcie dla tej funkcji może być kluczowe: Firefox 2 pozwala użytkownikom przywrócić uprzednio zamknięte karty. W celu prawidłowego przechowania stanu Twojego rozszerzenia kiedy karta zostaje przywrócona, musi ono skorzystać z metody API przechowywania sesji setTabValue(), aby zachować wszelkie dane, które potem będzie należało przywrócić, a następnie, podczas przywracania karty, wywołać getTabValue(), aby odzyskać uprzednio zachowane ustawienia.

API przechowywania sesji jest zaimplementowane przy użyciu interfejsu nsISessionStore.

Skąd wiedzieć kiedy przywracać?

Za każdym razem kiedy Firefox ma przywrócić uprzednio zamkniętą kartę, zostaje wysłane zdarzenie SSTabRestoring. Jeżeli chcesz, aby Twoje rozszerzenie mogło przywracać dane podczas przywracania karty, wystarczy, że ustawisz nasłuch (listener) na to zdarzenie:

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

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

Po prostu zastąp treść funkcji myExtensionHandleRestore() swoim własnym kodem. W powyższym przykładzie został użyty serwis (service) nsIConsoleService, do wyświetlenia wiadomość w konsoli.

Zdarzenie jest wysyłane tuż przed przywróceniem karty. Zdarzenie typu SSTabRestored jest wysyłane po przywróceniu ostatniej karty.

Proces przywracania sesji

Dokładna sekwencja zdarzeń, która jest wykonywana podczas przywracania sesji wygląda tak:

1. Stan sesji ma zostać przywrócony. Może się to zdarzyć podczas startu przeglądarki, albo w wyniku akcji Przywróć Zamkniętą Kartę, ponieważ zamknięte karty są przywracane jako sesje pojedyńczych kart.
2. Nowe okna są otwierane zgodnie z kolejnością (jedno na każde okno, które zostało zachowane), następnie przywracane są ciastka oraz ostatnio zamknięte karty.

Po tym, dla każdej przywracanej karty, zostają podjęte następujące kroki:

1. Albo wykorzystywana jest istniejąca karta, albo tworzona nowa. W drugim przypadku, wysyłane jest zdarzenie TabOpen.
2. Przywracane są przechowywane stałe atrybuty XUL (ang. persistent attributes) (te zapisane poprzez odwołania do persistTabAttribute()) oraz uprawnienia.
3. Wysyłane jest zdarzenie SSTabRestoring.
4. Karta zaczyna pobierać URL, który ma wyświetlić.
5. Po zakończeniu ładowania strony, przywracane są stany pól tekstowych i przewijania.
6. Na końcu, wysyłane jest zdarzenie SSTabRestored.

Jeżeli chcesz ustawić uprawnienia lub w inny sposób zmieniać przywracaną kartę przed załadowaniem strony, powinieneś obserwować SSTabRestoring. Jeżeli chcesz zrobić coś po załadowaniu strony, należy obserwować SSTabRestored.

Oba zdarzenia są zawsze wysyłane dla każdej, przywracanej, karty. Możesz określić, która karta jest przywracana przez sprawdzenie pola originalTarget z obiektu zdarzenia.

Właściwie nie istnieje metoda na określenie kiedy ostatnia karta została przywrócona, chyba, że określisz ile kart ma zostać przywróconych, a następnie policzysz zdarzenia SSTabRestored.

Wykorzystanie API przechowywania sesji

Tutaj opisujemy kilka prostych przykładów wykorzystania API przechowywania sesji.

Zachowywanie wartości dla karty

Poniższy kod dołączy do karty parę klucz/wartość. Po przywróceniu karty, ta para będzie z nią powiązana.

 var ss = Components.classes["@mozilla.org/browser/sessionstore;1"].
                             getService(Components.interfaces.nsISessionStore);
 var currentTab = getBrowser().selectedTab;
 var dataToAttach = "Chcę to przyłączyć";
 ss.setTabValue(currentTab, "key-name-here", dataToAttach);

Ten kod ustawia wartość klucza "key-name-here" na <var>dataToAttach</var>. Możesz tu użyć dowolnego obiektu JavaScript jako danych.

Pobieranie zachowanej wartości

W dowolnym momencie możesz pobrać wartość powiązaną z kartą (niezależnie czy karta jest w takcie przywracania czy nie), używając takiego kodu:

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

Po wykonaniu tego kodu, zmienna <var>retrivedData</var> zawiera zachowaną wartość dla klucza "key-name-here". <var>retrievedData</var> pozostanie jako undefined jeśli nie została zachowana żadna wartość dla tego klucza.

Usuwanie wartości powiązanej z kartą

Aby usunąć wartość z karty, możesz skorzystać z poniższego kodu:

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

Uwagi

Funkcje zachowywania i przywracania dla okien działają tak samo jak te dla kart (z uwzględnieniem zmian w nazwach).

Zobacz też

nsISessionStore