A new name
What used to be called HTML5 DOM Storage is now just Web Storage. It has its own spec which defines an
API for persistent data storage of key-value pair data in Web clients
You can think of web storage like an upgrade to cookies. It handles a lot of the same situations but is much more powerful.
Cookies are always strings. Web Storage values are any object that conforms to the structured clone algorithm which is a spec's way of saying: it's not the same object, also no DOM nodes or binary data such as what you can retrieve from the canvas tag.
This is huge! Cookies are transmitted to the server on every single request. Web storage will never leave the user's browser on its own.
Depending on your website design, you can choose to store data only temporarily or keep it long after the browser has closed.
You may be familiar with the term session and in web storage the concept is similar. Use session storage when you only want to keep data around until the user closes the browser window. They are done with your website for now and don't care if has forgotten what they were doing the next time they come back.
Use local storage for data you want to keep around for when the user comes back to your site such as preferences.
You can use both storage types to successfully keep application state across page transitions in the same window. A common situation is having a user click one of many items on a page. You can store the ID of that item in session storage, transition to the next page and retrieve the selected ID to show details.
Local storage maintains your application state even in new windows you create with window.open or links targeting _blank. Changes to local session in one window are visible in the other.
You may be inclind to think that session storage gives you cross-window access because session cookies gave you cross-window access but it doesn't. The spec explicitly defines it differently to avoid state from different sessions leaking into one another. Your session storage will be cloned when you create new windows but updates to one window's storage will not affect the others.
Above & beyond keeping state across windows, local storage also maintains it after all browser windows have been closed and even if the user reboots their computer. This is great for:
- user preferences
- temporary offline storage
Web storage has a very simple API. You look for and choose sessionStorage or localStorage properties in the window object. Both storage objects have the same interface.
- setItem(key, value)
- Adds an item to storage under the given key.
- Retrieves the requested item from storage.
- Removes the requested item from storage.
- Removes all items from storage.
- Maintains the number of items in the storage.
- Returns the key at the given index in storage. A key's index can change as you add and remove items from storage
- The storage event fires whenever you call setItem or removeItem. Since sessionStorage cannot cross page boundaries the use of this event is limited as you, the programmer, have just directly modified the web storage. However, this event becomes a powerful cross-page communication method with localStorage. The user can modify values on one page and if you save the new values in localStorage you can handle the changes and update the UI in a completely separate window.
Firefox 3.5 added full support.
Chrome 4 added support for local storage only.
IE8 added support for both but their storage event is non-standard.
Safari 4 added full support.
Opera 10.5 added support for both but their storage event doesn't fire.
- 5 megabytes
The web storage specification suggests that a user agent should provide at least five megabytes for each storage type for every origin. As far as I can tell, every major browser vendor has taken this to heart.
- userData behavior (IE 6 & 7)
- globalStorage (Firefox 2)
- Gears (Chrome 3)
- SQLite (Safari 3)
From a different page
Similar to how you might handle a site based entirely on the query section of a URL, you should be ready for a page refresh. Handle any stored values passed to your page from another in the startup code such as selected search result.
On the current page
Going a step further, you can track in-page changes made by the user such as a selected tab. Put the tab ID in storage when it changes and handle reselecting that tab in your startup code as well even though it's not coming from another page.
You don't have to rely on browser history to maintain state and only need it if you really want some changes to act as a new page.
I have set up a few sites where, after clicking a search result and switching tabs on the details page I want a refresh to maintain the tab state but still want the back button to or return to the search results.
Include the query string
I suggest also supporting the query string.
In a few websites I build an object based on the query string, then run through the storage object I'm using to overwrite the query properties. This handles cases where, e.g., you want to allow bookmarks to search results as well as a selected result via the URL. Once on the page, the user can see the originally selected item's information but change which result is selected. Now, when they refresh the page, the query string will stay the same but the new selection is maintained.
When a page loads, I find it good practice to remove any storage you're not going to handle in that page. This all really depends on how you want the website to function but for me, returning to search results should clear any tab changes made on a details page.
A word game!Play!
I put together a page to test the for the presence of web storage or one of the fallbacks used by the plugin. You can also play with storing and retrieving data as well as attempt to max out your storage.Test!
Multiple apps on one domain
If you have to split an application out by directory instead of by subdomains, you need to be aware of which keys you use. The two applications will be able to see each other's local storage.
You cannot assume forever
The user can clear storage on you. Because of this, you should store any data that even marginally important to them in a server-side database. That said, there are plenty of uses.
The storage event fires in Internet Explorer but it doesn't give you any information.
Opera don't seem to fire the storage event.
Chrome does not support session storage.
I haven't run into this issue at all yet but the specification warns that, for performance reasons, the storage event is not thread-safe. This makes it possible for one window to update a key in local session while another window is trying to read or update at the same time, so, just keep that in mind.