Web Storage API

From SpinetiX Support Wiki

Jump to: navigation, search

Introduction

The Web Storage API offers permanent & semi-permanent storage of structured data on the client side (HMP, Elementi), through its two global objects: localStorage (permanent storage) and sessionStorage (semi-permanent storage)

  • It was introduced in 3.0.0 firmware release, to complement the Shared Variables API usage, especially in what concerns the permanent storage of data (i.e. resilience to player restarts). See also Project:LocalStorage tester.
  • In 3.1.0 release, the Shared Variables framework was changed in order to have Shared Variables automatically saved into the localStorage object, thus having their values kept upon HMP reboots. Updating a Shared Variable triggers a modification within the localStorage object as well.

The maximum size for each of the two web storage object is limited at 4 MB. To remove the data stored into the web storage, use the .clear() method on both localStorage and sessionStorage objects. Additionally, on the HMP side, this can also be done from HMP Control Center > Content Settings > Web storage tab.

localStorage

The localStorage object enables permanent storage of data, being resilient to player reboots.

The localStorage object provides access to a list of key/value pairs (sometimes called items), that can be set and / or read with the following methods:

// setter
localStorage.setItem(key, value);

// getter
localStorage.getItem(key);

// remove item
localStorage.removeItem(key);

// remove all items from the local storage
localStorage.clear();

sessionStorage

The sessionStorage object is identical to the localStorage object as structure and as methods that can be used on it. The sole difference between them is that the former is reinitialized whenever the project starts (i.e. following a restart or a publish), while the latter is not.

// setter
sessionStorage.setItem(key, value);

// getter
sessionStorage.getItem(key);

// remove item
sessionStorage.removeItem(key);

// remove all items from the session storage
sessionStorage.clear();

Notes

  • When invoking the methods above, except for the getter, a storage event is fired.
  • Starting with 3.1.0 firmware release, the items saved into Web Storage can also be accessed as JavaScript properties (e.g., localStorage.key).
  • Comparing to Shared Variables, using localStorage has the advantage that the value of a item (i.e. object property) can be read at any time independently on the time it has been set.
This page was last modified on 29 August 2016, at 18:13.