|
| 1 | +# Shared preferences for Cordova |
| 2 | + |
| 3 | +[](https://travis-ci.org/adriano-di-giovanni/cordova-plugin-shared-preferences) |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +This plugin uses [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences.html) on Android and [NSUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults?language=objc) on iOS. |
| 8 | + |
| 9 | +### Highlights |
| 10 | + |
| 11 | +* save and retrieve key-value pairs of any Javascript data type using JSON serialization and parsing with `.put()` and `.get()`; |
| 12 | +* also save and retrieve key-value pairs of booleans, numbers and strings mapping to native data types with `.putBoolean()`, `.getBoolean()`, `.putNumber()`, `.getNumber()`, `.putString()`, `.getString()`; |
| 13 | +* fallback to user-defined default value if the key doesn't exist; |
| 14 | +* manage multiple sets of preferences; |
| 15 | +* well-tested cross-browser implementation. |
| 16 | + |
| 17 | +Please, refer to [Installation](#installation), [Usage](#usage) and [API reference](#api_reference) sections for more information. |
| 18 | + |
| 19 | +## Supported platforms |
| 20 | + |
| 21 | +* Android |
| 22 | +* iOS |
| 23 | + |
| 24 | +## Installation <a name="installation"></a> |
| 25 | + |
| 26 | +```bash |
| 27 | +npm install cordova-plugin-awesome-shared-preferences |
| 28 | +``` |
| 29 | + |
| 30 | +## Usage <a name="usage"></a> |
| 31 | + |
| 32 | +Invoke `SharedPreferences.getInstance()` to retrieve the instance for the default set of preferences: |
| 33 | + |
| 34 | +```javascript |
| 35 | +var sharedPreferences = window.plugins.SharedPreferences.getInstance() |
| 36 | +``` |
| 37 | + |
| 38 | +You can manage than one set of preferences. Invoke `SharePreferences.getInstance(name)` to retrieve an instance for a specific set: |
| 39 | + |
| 40 | +```javascripts |
| 41 | +var sharedPreferences = window.plugins.SharedPreferences.getInstance('settings') |
| 42 | +``` |
| 43 | + |
| 44 | +Set a new preference using `.put()`: |
| 45 | + |
| 46 | +```javascript |
| 47 | +var key = 'fruits' |
| 48 | +var value = ['Apple', 'Banana'] |
| 49 | +var successCallback = function() { |
| 50 | + console.log('OK') |
| 51 | +} |
| 52 | +var errorCallback = function(err) { |
| 53 | + console.error(err) |
| 54 | +} |
| 55 | + |
| 56 | +sharedPreferences.put(key, value, successCallback, errorCallback) |
| 57 | +``` |
| 58 | + |
| 59 | +Retrieve a value from the preferences using `.get()`: |
| 60 | + |
| 61 | +```javascript |
| 62 | +var key = 'fruits' |
| 63 | +var successCallback = function(value) { |
| 64 | + console.log(value) |
| 65 | +} |
| 66 | +var errorCallback = function(err) { |
| 67 | + console.log(err) |
| 68 | +} |
| 69 | + |
| 70 | +sharedPreferences.get(key, successCallback, errorCallback) |
| 71 | +``` |
| 72 | + |
| 73 | +If the key doesn't exist, the `errorCallback` will be invoked. You can override this behavior providing a default value: |
| 74 | + |
| 75 | +```javascript |
| 76 | +var key = 'animals' // the key doesn't exist |
| 77 | +var defaultValue = 'Dog' |
| 78 | +var successCallback = function(value) { |
| 79 | + console.log(value) // Dog |
| 80 | +} |
| 81 | +var errorCallback = function(err) { |
| 82 | + console.error(err) |
| 83 | +} |
| 84 | + |
| 85 | +sharedPreferences.get(key, defaultValue, successCallback, errorCallback) |
| 86 | +``` |
| 87 | + |
| 88 | +Delete a key-value pair from the preferences using `.del()`: |
| 89 | + |
| 90 | +```javascript |
| 91 | +var key = 'fruits' |
| 92 | +var successCallback = function() { |
| 93 | + console.log('OK') |
| 94 | +} |
| 95 | +var errorCallback = function(err) { |
| 96 | + console.error(err) |
| 97 | +} |
| 98 | + |
| 99 | +sharedPreferences.del(key, successCallback, errorCallback) |
| 100 | +``` |
| 101 | + |
| 102 | +## API reference <a name="api_reference"></a> |
| 103 | + |
| 104 | +{{#module name="SharedPreferences"}} |
| 105 | +{{>body~}} |
| 106 | +{{>member-index~}} |
| 107 | +{{>separator~}} |
| 108 | +{{>members~}} |
| 109 | +{{/module}} |
| 110 | + |
| 111 | +## License |
| 112 | + |
| 113 | +This project is licensed under the MIT license. |
0 commit comments