Client-side Storage

From HTML5 Builder
Jump to: navigation, search

You can store data on the user agent (web browser) and retrieve it later.

Local Storage

Local storage is a way for webpages to store key-value pairs within the client web browser from JavaScript. Such data persists even after the web browser is closed.

To take advantage of this HTML feature, you only need to call the different methods available on the localStorage JavaScript global variable.

Functionality

The following code summarizes its basic functionality:

// Save the value ‘John’, associated to the key ‘username’:
localStorage.setItem('username', 'John');
localStorage['username'] = 'John'; // Alternative syntax.

// Retrieve the value:
localStorage.getItem('username'); // Returns ‘John’.
localStorage['username']; // Also returns ‘John’ (alternative syntax).

// Remove the value:
localStorage.removeItem('username');

There are more local storage methods that provide additional functionality:

localStorage.length; // Returns the amount of stored key-value pairs.
localStorage.key(index); // Returns the key of the key-value pair at the given position (index).
localStorage.clear() // Removes any key-value pairs stored by your webpage.

Store Complex Data

The key can be either an integer or a string, whereas the value can only be a string. Hence, whenever you need to store a type other than a string, such as an object, your should use JSON notation:

// Store an object:
localStorage['keyname'] = JSON.stringify(objectVariable);

// Retrieve it:
var variable = JSON.parse(localStorage['keyname']);

Check Web Browser Support

Use the following function to check whether the client browser supports local storage.

function storageIsSupported() {
  try {
    return 'localStorage' in window && window['localStorage'] !== null;
  } catch (e) {
    return false;
  }
}

Limitations

It is also important to be aware of the limitations of localStorage:

  • Any data you store on the web browser using local storage will be available to any webpage from the same origin (schema + hostname + port). That means a page from http://example.com cannot access the data stored by a page from http://example.org. It also means that a page from https://example.com cannot access the data stored by a page from http://example.com.
  • The space for localStorage available for each origin is by default 5 MB in most browsers. If the limit is exceeded, a QUOTA_EXCEEDED_ERR exception will be thrown.

Track Changes

You can also track changes on the local storage data by watching the storage event, that is triggered on the window object.

Note: Pages will be aware of any change on the same origin. Two pages from the same origin would both get the event.

// Associate the event to an event handler.
if (window.addEventListener) {
  window.addEventListener("storage", storageHandler, false);
} else {
  window.attachEvent("onstorage", storageHandler);
};

// Handle the event:
function storageHandler(event) {
  event = event || window.event;
  
  // The event object will contain the following attributes:
  event.key; // The key of the modified key-value pair.
  event.oldValue; // Previous value of the pair (null for a new pair).
  event.newValue; // New value for the pair (null for a deleted pair).
  event.url; // URL from which the change was made.
    // Note: might be named event.uri instead in old browsers.
}

Session Storage

Session storage works the same as local storage. The only differences being:

  • You call the sessionStorage object instead of localStorage.
  • The availability of the data is restricted to the current page.
  • Data is deleted upon page unload, that is, when the current page is closed on the web browser, the data is lost.

Help Resources

Sample Applications

On the Features\ClientStorage folder inside the sample applications directory you will find applications showcasing client-side storage.

Video Tutorials

See Also