cordova-plugin-awesome-shared-preferences

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 = window.plugins.SharedPreferences.getInstance()

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 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():

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:

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():

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]) ⇒ SharedPreferences
  • 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.getInstance([name]) ⇒ SharedPreferences

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

// 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

// 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

// 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

// 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

// 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

// 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

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