Navigation

HTML5 localStorage

HTML5 localStorage is a mechanisms provided from the browser, for storing structured data on the client side. The mechanism is similar to HTTP Session Cookies. localStorage is a part of area Web Storage in the upcoming final HTML5 sepcification.


History

In some circumstances web sites need to save data on the client, for example session data for items in a shopping cart or an unique user identifier to distinct every user advertisement purposes. So far web sites utilized HTTP Cookies for that purpose. But there are two considerable disadvantages with HTTP Cookies:
  • HTTP Cookies will be transmitted with every HTTP Request
  • HTTP Cookies are not encrypted
  • The capacity of a HTTP Cookie is maximal 4 kilobyte
With HTML5 localStorage the W3C consortium provides a specification for user agents for implementing a better way to save data on the client. HTML5 localStorage allows to store data directly in the browser without creating a HTTP Request. Using this technology means, that all disadvantages of HTTP Request are omitted. Currently the most browser allow to store round about 5 megabyte data, that is much more than a HTTP Cookie can store.
There are two different ways to this:
  • SessionStorage: This storage is available for all web pages of a site for one user. When the user leaves the site the data in the storage will be deleted.
  • LocalStorage: This storage is available for all web pages of site for one user. When the user leaves the site the data in the storage will not be deleted

The API

This section describes the most important key messages of the API specification.

Storage Interface
interface Storage {
  readonly attribute unsigned long length;
  getter DOMString key(in unsigned long index);
  getter any getItem(in DOMString key);
  setter creator void setItem(in DOMString key, in any value);
  deleter void removeItem(in DOMString key);
  void clear();
};
The storage interface is a contract for both types of storage, sessions storage and local storage. The data in a storage is stored as a list of key / value pairs. Hereby the order of keys in a storage is user-agent defined. It is possible to access the data with the getItem() method or with the index or name of properties, for example localStorage[1] and localStorage['keyName']. 
If you as the user do not want that web sites store data, you can disable this functionality for web sites. But it depends on the user-agent you use.
The following gives you more detail information about the storage interface.
  • getItem(key) returns a structured clone of the value associated with the given key
  • setItem(key, value) creates a structured clone of the given value and stores the clone with the associated key in the list, a exsiting value associated with this key will be overwritten
  • image data cannot be stored

sessionStorage

[Supplemental, NoInterfaceObject]
interface WindowSessionStorage {
  readonly attribute Storage sessionStorage;
};
Window implements WindowSessionStorage;
If a web site request a session storage, the user agent must return a storage object which is associated with the user-agents storage area. When you clone browsing context, for example you open the same site in another tab of the browser, the new browsing context should start with the same content of the session storage, but but the two sets must from that point on be considered separate, not affecting each other in any way.

localStorage

[Supplemental, NoInterfaceObject]
interface WindowLocalStorage {
  readonly attribute Storage localStorage;
};
Window implements WindowLocalStorage;
If a web site request a session storage, the user agent must return a storage object. When the user wants to delete data, data should expired by the user-agent.

Events

interface StorageEvent : Event {
  readonly attribute DOMString key;
  readonly attribute any oldValue;
  readonly attribute any newValue;
  readonly attribute DOMString url;
  readonly attribute Storage storageArea;
  void initStorageEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in any oldValueArg, in any newValueArg, in DOMString urlArg, in Storage storageAreaArg);
};
When a storage area changes, the user agent should throw an event object which implements the StorageEvent interface. Because web sites can listen to storage events, they can perform further action when a event is thrown by the user-agent.

Disk Space

Currently the most browser provide 5 megabyte of space for storage areas. If a web site needs more space, the web site can ask the user to grant the site more space. The user-agents are to be transparent regarding to showing the disk space of a site.

Privacy 

Privacy depends on the implementation of the user-agent. This means, that the HTML5 specification does not dictate how the user-agents are to implement the privacy features. The HTML5 specification gives only some suggestions for privacy features. 
  • user agents should block storage access for third-party cross site domain scripts
  • data can be expired after a user controlled period
  • a clearing of cookies should also clear the storage, otherwise application can backup their data in both ways
  • white-list for sites, that get the grant of the user to access the storage
  • shared domain blacklist to share blacklists with other user to create communities or global blacklist databases

Security

For security reasons each storage object has a member, the document of the window object. It is necessary because a non-member script are not to be accessing the storage. If this happens, the user-agent must throws an SECURITY_ERR .
  • to avoid DNS spoofing attacks, pages should use TLS
  • if different authors share content on one host name, then a web site should avoid to use localStorage
  • user agents should implement localStorage as specified to avoid information leakage (hostile site can read a wishlist from another domain) and information spoofing (hostile site can write items to the wishlist of another site)

Browser Support

Currently most of the modern browser support the localStorage and the sessionStorage functionality. The following table is provided by the web site http://www.findmebyip.com .



Examples

With the following snippet you can check if the user agent provides supports localStorage.

function supportsLocalStorage({
  return "localStorage" in window;
}

The following example stores a string value myValue in the local storage associated with the key myKey.

localStorage['myKey'"myValue";

The following example stores at first line a JSON represented string data in the localStorage. In line 2 the string data will be read from the localStorage. In line 3 the string data will be parsed with the JSON parser to a regular JavaScript object. In line 4 and 5 the value of the both properties foo and bar will be shown on the display.

localStorage['myKey''{"foo": "bar", "bar": "foo"}';
str localStorage['myKey'];
obj JSON.parse(str);
alert(obj.foo)// bar
alert(obj.bar)// foo


In the following example all data associated with the site and stored in the localStorage will be deleted.

localStorage.clear();


Demo

Draggable DIV Elements

The Draggable DIV Elements demo was created by me to show the functionality of localStorage functionality. If your browser supports localStorage, you can drag boxes on the web site, otherwise you get a message that your browser does not support the localStorage functionality. Every time you drag a box on the web page, the new position of the dragged box will be saved in the localStorage of the browser. After you have dragged the boxes on the web page, you can close the web page and reopen the web page in anther tab. You will see, that the boxes appears on the same positions.

You also can push the clear button to delete data associated with the site in the localStorage. After pushing the button, the site will refresh and the boxes will appear on the top left corner.

Please visit the site http://www.az13.de/html5/local_storage_example.html to see and to test the example.

ToDo-List

This demo let the user create a to do list stored in the localStorage of the browser. 

See the Stored Key Value Pairs

In this demo you can store, delete or modify your own key value pairs in the localStorage.


References

External Links

Comments