How to Store Values in HTML5 Local Storage

HTML5 local storage makes it possible to store values in the browser which can survive the browser session, just like cookies. Local storage also makes it possible to send events between browser windows. A very useful feature.

Local storage is a new specification in HTML. It is not actually part of the HTML5 specification, but it is born around the same time, and is often referred to as being part of the new HTML platform (which is HTML5). Therefore I include the description of local storage in the HTML5 tutorial.

Here is a list of the topics covered:

• Local Storage Basics
• sessionStorage + localStorage
• Iterating Keys in the Local Storage
• Storage Events
  • Attaching a Storage Event Listener

Local Storage Basics

Local storage offers a simple key - value store, like a hash table or dictionary object. Local storage comes in two versions:

1. Session Storage
2. Local Storage

Session storage is available inside the same browser window for as long as the window is open. When the browser window is closed, the session storage associated with that window is deleted. Multiple windows from the same origin (URL) cannot see each others session storage. Popup windows opened from the same window can see session storage, and so can iframes inside the same window.

Local storage is available in the browser to all windows with the same origin (domain). Data stored in the local storage is also available after the window has been closed. The next time a window is opened and loads the page from the same origin, the page can access the stored values there again.

sessionStorage + localStorage

The session storage and local storage are accessed via these two globally available JavaScript objects:

• sessionStorage
• localStorage

The sessionStorage object and localStorage object are accessed in the same way. It is only they life span and visibility of the data stored that is different.

You can set properties on the sessionStorage and localStorage object just like with a normal JavaScript object. Here is an example:

sessionStorage.myProperty = "Hello World";

localStorage.myProperty   = "Hello World";

The first line of this code example sets the session storage property myProperty to the value Hello World. The second line sets the local storage property myProperty to the value Hello World.

You can only store strings in the session and local storage properties. Nothing else. If you need to store JavaScript objects, you will have to convert them to a JSON string first.

You delete a session or local storage property like this:

delete sessionStorage.myProperty;

delete localStorage.myProperty;

You can also use the following three methods to access properties in the session or local storage:

sessionStorage.setItem    ('propertyName', 'value');
sessionStorage.getItem    ('propertyName');
sessionStorage.removeItem ('propertyName');

localStorage.setItem      ('propertyName', 'value');
localStorage.getItem      ('propertyName');
localStorage.removeItem   ('propertyName');

These methods also only allow string values.

Iterating Keys in the Local Storage

You can iterate the keys (property names) of the key - value pairs stored in the session or local storage, like this:

for(var i=0; i < sessionStorage.length; i++){

    var propertyName = sessionStorage.key(i);

    alert(  i + " : " + propertyName + " = " +
            sessionStorage.getItem(propertyName));
}

The sessionStorage.length property returns the number of properties stored in the sessionStorage object.

The function key() returns the property name (or key name) of the property with the index passed as parameter to the function.

Storage Events

The storage objects fire events which your appliation can listen for. A storage event is fired when you insert, update or delete a session or local storage property.

The storage event is only emitted in other browser windows than the one that inserted, updated or deleted the session or local storage objects.

For session storage this means that events are only visible in pop up windows and iframes.

For local storage, events are visible to all other windows open with the same origin, including pop up windows and iframes.

Attaching a Storage Event Listener

Attaching an event listener to a storage object is done like this:

function onStorageEvent(storageEvent){

    alert("storage event");
}

window.addEventListener('storage', onStorageEvent, false);

The function onStorageEvent() is the event handler function.

The addEventListener() function call attaches the event handler function to storage events.

The storageEvent event object passed to the event handler function looks like this:

StorageEvent {
    key;          // name of the property set, changed etc.
    oldValue;     // old value of property before change
    newValue;     // new value of property after change
    url;          // url of page that made the change
    storageArea;  // localStorage or sessionStorage,
                  // depending on where the change happened.
}

You can access this storage event object from inside the event handler function.