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.

$3

* 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

``bash
npm install cordova-plugin-awesome-shared-preferences
`

Usage

Invoke SharedPreferences.getInstance() to retrieve the instance for the default set of preferences:

`javascript
var sharedPreferences = window.plugins.SharedPreferences.getInstance()
`

You can manage than one set of preferences. Invoke SharePreferences.getInstance(name) to retrieve an instance for a specific set:

`javascripts
var sharedPreferences = window.plugins.SharedPreferences.getInstance('settings')
`

Set a new preference using .put():

`javascript
var key = 'fruits'
var value = ['Apple', 'Banana']
var successCallback = function() {
console.log('OK')
}
var errorCallback = function(err) {
console.error(err)
}

sharedPreferences.put(key, value, successCallback, errorCallback)
`

Retrieve a value from the preferences using .get():

`javascript
var key = 'fruits'
var successCallback = function(value) {
console.log(value)
}
var errorCallback = function(err) {
console.log(err)
}

sharedPreferences.get(key, successCallback, errorCallback)
`

If the key doesn't exist, the errorCallback will be invoked. You can override this behavior providing a default value:

`javascript
var key = 'animals' // the key doesn't exist
var defaultValue = 'Dog'
var successCallback = function(value) {
console.log(value) // Dog
}
var errorCallback = function(err) {
console.error(err)
}

sharedPreferences.get(key, defaultValue, successCallback, errorCallback)
`

Delete a key-value pair from the preferences using .del():

`javascript
var key = 'fruits'
var successCallback = function() {
console.log('OK')
}
var errorCallback = function(err) {
console.error(err)
}

sharedPreferences.del(key, successCallback, errorCallback)
`

API reference


* SharedPreferences
* _static_
* [.getInstance([name])](#window.plugins.module_SharedPreferences.getInstance) ⇒ SharedPreferences
* _inner_
* ~SharedPreferences
* [new SharedPreferences([name])](#new_window.plugins.module_SharedPreferences..SharedPreferences_new)
* [.getBoolean(key, [defaultValue], successCallback, [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+getBoolean)
* [.putBoolean(key, value, [successCallback], [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+putBoolean)
* [.getNumber(key, [defaultValue], successCallback, [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+getNumber)
* [.putNumber(key, value, [successCallback], [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+putNumber)
* [.getString(key, [defaultValue], successCallback, [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+getString)
* [.putString(key, value, [successCallback], [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+putString)
* [.get(key, [defaultValue], successCallback, [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+get)
* [.put(key, value, [successCallback], [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+put)
* [.del(key, [successCallback], [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+del)
* [.has(key, successCallback, [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+has)
* [.keys([successCallback], [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+keys)
* [.clear([successCallback], [errorCallback])](#window.plugins.module_SharedPreferences..SharedPreferences+clear)

$3

#### 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
`js
// Retrieve the value for a key that doesn't exist. No default value provided.

var key = 'missingKey' // the key doesn't exist
var successCallback = function(value) {
// it won't be invoked
}
var errorCallback = function(err) {
expect(err).toBeDefined()
expect(err instanceof Error).toBe(true)
expect(err.message).toMatch(/missing key/i)
}

sharedPreferences.getBoolean(key, successCallback, errorCallback)
`
Example
`js
// Retrieve the value for a key that doesn't exist. Default value provided.

var key = 'missingKey' // the key doesn't exist
var defaultValue = false
var successCallback = function(value) {
expect(value).toBe(defaultValue)
}
var errorCallback = function(err) {
// it won't be invoked
}

sharedPreferences.getBoolean(key, defaultValue, successCallback, errorCallback)
`


#### 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
`js
// Retrieve the value for a key that doesn't exist. No default value provided.

var key = 'missingKey' // the key doesn't exist
var successCallback = function(value) {
// it won't be invoked
}
var errorCallback = function(err) {
expect(err).toBeDefined()
expect(err instanceof Error).toBe(true)
expect(err.message).toMatch(/missing key/i)
}

sharedPreferences.getNumber(key, successCallback, errorCallback)
`
Example
`js
// Retrieve the value for a key that doesn't exist. Default value provided.

var key = 'missingKey' // the key doesn't exist
var defaultValue = false
var successCallback = function(value) {
expect(value).toBe(defaultValue)
}
var errorCallback = function(err) {
// it won't be invoked
}

sharedPreferences.getNumber(key, defaultValue, successCallback, errorCallback)
`


#### 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
`js
// Retrieve the value for a key that doesn't exist. No default value provided.

var key = 'missingKey' // the key doesn't exist
var successCallback = function(value) {
// it won't be invoked
}
var errorCallback = function(err) {
expect(err).toBeDefined()
expect(err instanceof Error).toBe(true)
expect(err.message).toMatch(/missing key/i)
}

sharedPreferences.getString(key, successCallback, errorCallback)
`
Example
`js
// Retrieve the value for a key that doesn't exist. Default value provided.

var key = 'missingKey' // the key doesn't exist
var defaultValue = false
var successCallback = function(value) {
expect(value).toBe(defaultValue)
}
var errorCallback = function(err) {
// it won't be invoked
}

sharedPreferences.getString(key, defaultValue, successCallback, errorCallback)
`


#### 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
`js
// Retrieve the value for a key that doesn't exist. No default value provided.

var key = 'missingKey' // the key doesn't exist
var successCallback = function(value) {
// it won't be invoked
}
var errorCallback = function(err) {
expect(err).toBeDefined()
expect(err instanceof Error).toBe(true)
expect(err.message).toMatch(/missing key/i)
}

sharedPreferences.get(key, successCallback, errorCallback)
`
Example
`js
// Retrieve the value for a key that doesn't exist. Default value provided.

var key = 'missingKey' // the key doesn't exist
var defaultValue = false
var successCallback = function(value) {
expect(value).toBe(defaultValue)
}
var errorCallback = function(err) {
// it won't be invoked
}

sharedPreferences.get(key, defaultValue, successCallback, errorCallback)
`


#### 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.