Client-side Storage
You can store data on the user agent (web browser) and retrieve it later.
Contents
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, aQUOTA_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 oflocalStorage
. - 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
- HTML5 Builder support for Canvas, Storage & Audio/Video.
- 0:45 — Overview of the Features\ClientStorage sample application.
See Also
- Alternatives: MDB, Server Database Connections.