HTML5 Local Storage

This object provides functions to access a list of key/value pairs.

Each Storage object provides access to a list of key/value pairs, which are sometimes called items. Keys are strings. Any string (including the empty string) is a valid key. Values can be any data type supported by the structured clone algorithm.

BlackBerry 6.0 Support:

This API supports BlackBerry 6.0; however, some BlackBerry 6.0 dot revisions may not be fully supported.

BlackBerry 10 Storage Limit

On BB10 devices, local storage has 25MB of storage per domain instead of the standard 5MB.


Supported Platform(s)

- BlackBerry OS 6.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
localStorage.clear   Y Y Y Y YY
localStorage.getItem   Y Y Y Y YY
localStorage.key   Y Y Y Y YY
localStorage.removeItem   Y Y Y Y YY
localStorage.setItem   Y Y Y Y YY
length   Y Y Y Y YY

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

This API does not require a <feature> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions

static void localStorage.clear ()


This method atomically causes the list associated with the object to be emptied of all key/value pairs, if there are any. If there are none, then the method does nothing.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Object localStorage.getItem (key : String)


Returns a structured clone of the current value associated with the given key.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
key The key for the key/value pair

Return:

The value associated with the given key. Returns null if the given key does not exist.



Code Example:
var cityName=localStorage.getItem("cityName");

static String localStorage.key (index : Number)


Returns the name of the nth key in the list. The order of keys is user-agent defined, but must be consistent within an object so long as the number of keys doesn't change.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
index The nth key in the list

Return:

The name of the nth key in the list. Returns null if the index is greater than or equal to the number of key/value pairs in the object.


static void localStorage.removeItem (key : String)


This method causes the key/value pair with the given key to be removed from the list associated with the object, if it exists. If no item with that key exists, the method does nothing.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
key The key for the key/value pair

Code Example:
localStorage.removeItem("cityName");

static void localStorage.setItem (key : String, value : Object)


This method first creates a structured clone of the given value. The user agent checks if a key/value pair with the given key already exists in the list associated with the object. If it does not, then a new key/value pair must be added to the list, with the given key and with its value set to the newly obtained clone of value. If the given key does exist in the list, then it must have its value updated to the newly obtained clone of value.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
key The key for the key/value pair
value The value for the key/value pair

Throws
Exception If a structured clone of the given value cannot be created. The list associated with the object is left unchanged.
NOT_SUPPORTED_ERR If the structured clone involving the construction of a new ImageData object cannot be created.
QUOTA_EXCEEDED_ERR If the new value couldn't be set (for example, if the user disabled storage for the site, or if the quota has been exceeded).

Code Example:
localStorage.setItem("cityName", "Toronto");

Properties

static readonly Number length


The number of key/value pairs currently present in the list associated with the object.


Supported Platforms
 - BlackBerry OS 6.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:08 GMT-0500 (EST)