Shared preferences for Cordova
This plugin provides the ability to save and retrieve persistent key-value pairs of any Javascript data type. You can use this plugin to save any data: arrays, booleans, numbers, strings and objects. This data will persist across user sessions.
This plugin uses SharedPreferences on Android and NSUserDefaults on iOS.
Highlights
- save and retrieve key-value pairs of any Javascript data type using JSON serialization and parsing with
.put()
and.get()
; - also save and retrieve key-value pairs of booleans, numbers and strings mapping to native data types with
.putBoolean()
,.getBoolean()
,.putNumber()
,.getNumber()
,.putString()
,.getString()
; - fallback to user-defined default value if the key doesn't exist;
- manage multiple sets of preferences;
- well-tested cross-browser implementation.
Please, refer to Installation, Usage and API reference sections for more information.
Supported platforms
- Android
- iOS
Installation
npm install cordova-plugin-awesome-shared-preferences
Usage
Invoke SharedPreferences.getInstance()
to retrieve the instance for the default set of preferences:
var sharedPreferences = windowpluginsSharedPreferences
You can manage than one set of preferences. Invoke SharePreferences.getInstance(name)
to retrieve an instance for a specific set:
var sharedPreferences = window.plugins.SharedPreferences.getInstance('settings')
Set a new preference using .put()
:
var key = 'fruits'var value = 'Apple' 'Banana'var { console}var { console} sharedPreferences
Retrieve a value from the preferences using .get()
:
var key = 'fruits'var { console}var { console} sharedPreferences
If the key doesn't exist, the errorCallback
will be invoked. You can override this behavior providing a default value:
var key = 'animals' // the key doesn't existvar defaultValue = 'Dog'var { console // Dog}var { console} sharedPreferences
Delete a key-value pair from the preferences using .del()
:
var key = 'fruits'var { console}var { console} sharedPreferences
API reference
- SharedPreferences
- static
- .getInstance([name]) ⇒
SharedPreferences
- .getInstance([name]) ⇒
- inner
- ~SharedPreferences
- new SharedPreferences([name])
- .getBoolean(key, [defaultValue], successCallback, [errorCallback])
- .putBoolean(key, value, [successCallback], [errorCallback])
- .getNumber(key, [defaultValue], successCallback, [errorCallback])
- .putNumber(key, value, [successCallback], [errorCallback])
- .getString(key, [defaultValue], successCallback, [errorCallback])
- .putString(key, value, [successCallback], [errorCallback])
- .get(key, [defaultValue], successCallback, [errorCallback])
- .put(key, value, [successCallback], [errorCallback])
- .del(key, [successCallback], [errorCallback])
- .has(key, successCallback, [errorCallback])
- .keys([successCallback], [errorCallback])
- .clear([successCallback], [errorCallback])
- ~SharedPreferences
- static
SharedPreferences
SharedPreferences.getInstance([name]) ⇒ Returns a SharedPreferences instance
Kind: static method of SharedPreferences
Param | Type | Description |
---|---|---|
[name] | String |
The name of the preferences file. |
SharedPreferences~SharedPreferences
Kind: inner class of SharedPreferences
- ~SharedPreferences
- new SharedPreferences([name])
- .getBoolean(key, [defaultValue], successCallback, [errorCallback])
- .putBoolean(key, value, [successCallback], [errorCallback])
- .getNumber(key, [defaultValue], successCallback, [errorCallback])
- .putNumber(key, value, [successCallback], [errorCallback])
- .getString(key, [defaultValue], successCallback, [errorCallback])
- .putString(key, value, [successCallback], [errorCallback])
- .get(key, [defaultValue], successCallback, [errorCallback])
- .put(key, value, [successCallback], [errorCallback])
- .del(key, [successCallback], [errorCallback])
- .has(key, successCallback, [errorCallback])
- .keys([successCallback], [errorCallback])
- .clear([successCallback], [errorCallback])
new SharedPreferences([name])
Creates a SharedPreferences
instance
Param | Type | Description |
---|---|---|
[name] | String |
The name of the preferences file |
sharedPreferences.getBoolean(key, [defaultValue], successCallback, [errorCallback])
Retrieves a boolean value from the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to retrieve. |
[defaultValue] | Boolean |
The value to return if the key doesn't exist. If omitted, errorCallback will be invoked if key is missing. |
successCallback | function |
A callback which is called if the key exists. Invoked with (value) . |
[errorCallback] | function |
A callback which is called if an error occurs. If defaultValue is omitted, it will be invoked if the key is missing. Invoked with (err) . |
Example
// Retrieve the value for a key that doesn't exist. No default value provided. var key = 'missingKey' // the key doesn't existvar { // it won't be invoked}var { } sharedPreferences
Example
// Retrieve the value for a key that doesn't exist. Default value provided. var key = 'missingKey' // the key doesn't existvar defaultValue = falsevar { }var { // it won't be invoked} sharedPreferences
sharedPreferences.putBoolean(key, value, [successCallback], [errorCallback])
Sets a boolean value in the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to set. |
value | Boolean |
The new value for the preference. |
[successCallback] | function |
A callback which is called if the operation is completed successfully. Invoked with () . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
sharedPreferences.getNumber(key, [defaultValue], successCallback, [errorCallback])
Retrieves a number from the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to retrieve. |
[defaultValue] | Boolean |
The value to return if the key doesn't exist. If omitted, errorCallback will be invoked if key is missing. |
successCallback | function |
A callback which is called if the key exists. Invoked with (value) . |
[errorCallback] | function |
A callback which is called if an error occurs. If defaultValue is omitted, it will be invoked if the key is missing. Invoked with (err) . |
Example
// Retrieve the value for a key that doesn't exist. No default value provided. var key = 'missingKey' // the key doesn't existvar { // it won't be invoked}var { } sharedPreferences
Example
// Retrieve the value for a key that doesn't exist. Default value provided. var key = 'missingKey' // the key doesn't existvar defaultValue = falsevar { }var { // it won't be invoked} sharedPreferences
sharedPreferences.putNumber(key, value, [successCallback], [errorCallback])
Sets a number in the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to set. |
value | Boolean |
The new value for the preference. |
[successCallback] | function |
A callback which is called if the operation is completed successfully. Invoked with () . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
sharedPreferences.getString(key, [defaultValue], successCallback, [errorCallback])
Retrieves a string value from the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to retrieve. |
[defaultValue] | Boolean |
The value to return if the key doesn't exist. If omitted, errorCallback will be invoked if key is missing. |
successCallback | function |
A callback which is called if the key exists. Invoked with (value) . |
[errorCallback] | function |
A callback which is called if an error occurs. If defaultValue is omitted, it will be invoked if the key is missing. Invoked with (err) . |
Example
// Retrieve the value for a key that doesn't exist. No default value provided. var key = 'missingKey' // the key doesn't existvar { // it won't be invoked}var { } sharedPreferences
Example
// Retrieve the value for a key that doesn't exist. Default value provided. var key = 'missingKey' // the key doesn't existvar defaultValue = falsevar { }var { // it won't be invoked} sharedPreferences
sharedPreferences.putString(key, value, [successCallback], [errorCallback])
Sets a string in the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to set. |
value | Boolean |
The new value for the preference. |
[successCallback] | function |
A callback which is called if the operation is completed successfully. Invoked with () . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
sharedPreferences.get(key, [defaultValue], successCallback, [errorCallback])
Retrieves a value from the preferences using JSON parsing.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to retrieve. |
[defaultValue] | The value to return if the key doesn't exist. If omitted, errorCallback will be invoked if key is missing. |
|
successCallback | function |
A callback which is called if the key exists. Invoked with (value) . |
[errorCallback] | function |
A callback which is called if an error occurs. If defaultValue is omitted, it will be invoked if the key is missing. Invoked with (err) . |
Example
// Retrieve the value for a key that doesn't exist. No default value provided. var key = 'missingKey' // the key doesn't existvar { // it won't be invoked}var { } sharedPreferences
Example
// Retrieve the value for a key that doesn't exist. Default value provided. var key = 'missingKey' // the key doesn't existvar defaultValue = falsevar { }var { // it won't be invoked} sharedPreferences
sharedPreferences.put(key, value, [successCallback], [errorCallback])
Sets a value in the preferences using JSON serialization.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to set. |
value | The new value for the preference. | |
[successCallback] | function |
A callback which is called if the operation is completed successfully. Invoked with () . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
sharedPreferences.del(key, [successCallback], [errorCallback])
Removes a value from the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to remove. |
[successCallback] | function |
A callback which is called if the operation is completed successfully. Invoked with () . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
sharedPreferences.has(key, successCallback, [errorCallback])
Checks whether the preferences contains a preference.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
key | String |
The name of the preference to check. |
successCallback | function |
A callback which is called if the operation is completed successfully. Invoked with (result) . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
sharedPreferences.keys([successCallback], [errorCallback])
Retrieves all keys from the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
[successCallback] | function |
A callback which is called if the operation is completed successfully. Invoked with (keys) . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
sharedPreferences.clear([successCallback], [errorCallback])
Removes all values from the preferences.
Kind: instance method of SharedPreferences
Param | Type | Description |
---|---|---|
[successCallback] | function |
A callback which is called if the operation is completed successfully. Invoked with () . |
[errorCallback] | function |
A callback which is called if an error occurs. Invoked with (err) . |
License
This project is licensed under the MIT license.