me.apla.cordova.app-preferences

by apla

App preferences plugin for cordova

198 Stars 189 Forks Last release: Not found Apache License 2.0 298 Commits 17 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Application preferences plugin for Cordova 3+

Why you should use this plugin?

  • Cordova + Promise interface out of the box
  • Supports many platforms (Android, iOS/macOS, Windows and local storage fallback)
  • Have tests (iOS: iOS and browser status, Android: Android status, Windows: Windows status, Browser: iOS and browser status)
  • Supports simple and complex data structures
  • Supports removal of the keys
  • Have preference pane generator for application (for Android and iOS) and can show native preferences
  • (Untested) reference change notification #37
  • (Untested) named preferences files for android and iOS suites #97
  • (Untested) synchronized preferences via iCloud or windows roaming #75

Installing

From plugin registry:

$ cordova plugin add cordova-plugin-app-preferences

From the repo:

$ cordova plugin add https://github.com/apla/me.apla.cordova.app-preferences

From a local clone:

$ cordova plugin add /path/to/me.apla.cordova.app-preferences/folder

https://github.com/apla/me.apla.cordova.app-preferences/issues/97

More information: Command-line Interface Guide.

Using Plugman to Manage Plugins.

Synopsis

function ok (value) {}
function fail (error) {}

var prefs = plugins.appPreferences;

// cordova interface

// store key => value pair prefs.store (ok, fail, 'key', 'value');

// store key => value pair in dict (see notes) prefs.store (ok, fail, 'dict', 'key', 'value');

// fetch value by key (value will be delivered through "ok" callback) prefs.fetch (ok, fail, 'key');

// fetch value by key from dict (see notes) prefs.fetch (ok, fail, 'dict', 'key');

// remove value by key prefs.remove (ok, fail, 'key');

// show application preferences prefs.show (ok, fail);

// instead of cordova interface you can use promise interface // you'll receive promise when you won't pass function reference // as first and second parameter

// fetch the value for a key using promise prefs.fetch ('key').then (ok, fail);

Suites

// support for iOS suites or android named preference files (untested)
var suitePrefs = prefs.suite ("suiteName");
suitePrefs.fetch (...);
suitePrefs.store (...);

// store preferences in synchronized cloud storage for iOS and windows var cloudSyncedPrefs = prefs.cloudSync (); cloudSyncedPrefs.fetch (...); cloudSyncedPrefs.store (...);

Platforms

  1. Native execution on iOS/macOS using
    NSUserDefaults
    — docs for iOS / macOS
  2. Native execution on Android using
    android.content.SharedPreferences
    docs
  3. Native execution on Windows Universal Platform using
    Windows.Storage.ApplicationData
    docs
  4. Native execution on Windows Phone 7 using
    IsolatedStorageSettings.ApplicationSettings
    docs
  5. Execution on BlackBerry10 fallback using
    localStorage

Notes

  1. iOS, macOS, Android and Windows Phone basic values (
    string
    ,
    number
    ,
    boolean
    ) are stored using typed fields.
  2. Complex values, such as arrays and objects, are always stored using JSON notation.
  3. Dictionaries are supported on iOS and Windows 8 only, so on other platforms instead of using the real dictionary a composite key will be written like
    .
  4. On iOS/macOS dictionaries just a key, so appPrefs.store ('dict', 'key', value) and appPrefs.store ('dict', {'key': value}) have same meaning (but different result).

Tests

Tests are available in

src/test.js
. After installing plugin you can add test code from this file and then launch
testPlugin()
function.
  • iOS pass locally, Travis: iOS and browser status
  • Android pass locally, CircleCI: Android status
  • BlackBerry 10 pass locally
  • Windows Phone 8 tests pass locally, Appveyor: Windows status
  • Browser pass locally, Travis: iOS and browser status

Module update for cordova < 5.x

Please note that plugin id is changed for npm publishing, so if you used this plugin before [email protected], you'll have to reinstall it:

$ cordova plugin rm me.apla.cordova.app-preferences $ cordova plugin add cordova-plugin-app-preferences

Show Preference pane

If you have generated preferences, you can programmatically show preference pane (Android and iOS at this time). On Android your application show native interface for preferences, on iOS you'll be switched to the Settings.app with application preferences opened for you. Either way, you must listen for Cordova resume event to perform preferences synchronization.

Preferences interface generator

Preferences generator installed along with plugin and run every time when you prepare you cordova app.

After plugin installation you can find file

app-settings.json
within your app folder.

If you want to disable this functionality, please remove

app-settings.json
.

iOS note: if you have

Settings.bundle
from external source or previous version of generator
cordova prepare
will fail. Current version of preference generator trying not to rewrite existing
Settings.bundle
if it is not generated by plugin. It is save to remove
Settings.bundle
if it came from previous version of plugin.

Supported controls for iOS:

  • group
  • combo
  • switch
  • textfield

Supported controls for Android:

  • group
  • combo
  • switch - not tested
  • textfield - not tested

TODO: Preferences UI for Windows Phone (guide, docs)

Credits

Original version for iOS: https://github.com/phonegap/phonegap-plugins/tree/master/iOS/ApplicationPreferences

Another android implementation for cordova 2.x: https://github.com/macdonst/AppPreferences

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.