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.Supported Platform(s)
- BlackBerry PlayBook
- Ripple Emulator
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 Only) |
|---|
| This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
clear
| static void clear() |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
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 do nothing.
getItem
| static Object getItem(key : String) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
Return a structured clone of the current value associated with the given key.
Returns
the value associated with the given key. If the given key does not exist, this method return null.| Parameter | Type | Description |
|---|---|---|
| key | String | the key for the key/value pair |
Code Example(s)
var cityName=localStorage.getItem("cityName");
key
| static String key(index : Number) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
Return 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.
Returns
the name of the nth key in the list. If index is greater than or equal to the number of key/value pairs in the object, then this method must return null.| Parameter | Type | Description |
|---|---|---|
| index | Number | the nth key in the list |
removeItem
| static void removeItem(key : String) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
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 do nothing.
| Parameter | Type | Description |
|---|---|---|
| key | String | the key for the key/value pair |
Code Example(s)
localStorage.removeItem("cityName");
setItem
| static void setItem(key : String, value : Object) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
This method first create a structured clone of the given value. If this raises an exception, then the exception must be thrown and the list associated with the object is left unchanged. If constructing the structured clone would involve constructing a new ImageData object, then throw a NOT_SUPPORTED_ERR exception instead.
Otherwise, the user agent must then check 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. If it couldn't set the new value, the method must raise an QUOTA_EXCEEDED_ERR exception. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)
| Parameter | Type | Description |
|---|---|---|
| key | String | the key for the key/value pair |
| value | Object | the value for the key/value pair |
| Throws | Description |
|---|---|
| Exception | This method first create a structured clone of the given value. If this raises an exception, then the exception is thrown and the list associated with the object is left unchanged. If constructing the structured clone would involve constructing a new ImageData object, then throw a NOT_SUPPORTED_ERR exception instead. If it couldn't set the new value, the method raises an QUOTA_EXCEEDED_ERR exception. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.) |
Code Example(s)
localStorage.setItem("cityName", "Toronto");
Properties:
| Property | Type | Description | Supported Platform(s) |
|---|---|---|---|
| length |
Static Number readonly |
The number of key/value pairs currently present in the list associated with the object.
|
- BlackBerry PlayBook
- Ripple Emulator |