Skip to content

Shared preferences for Cordova. Save and retrieve persistent key-value pairs of any Javascript data type.

License

Notifications You must be signed in to change notification settings

adriano-di-giovanni/cordova-plugin-shared-preferences

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Shared preferences for Cordova

Build Status

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 multiple sets 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.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

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.