First if you are unsure about how application preferences are setup on Android go read this tutorial and then come back I'll wait. Oh great, your back. Let's crack on with things.
Functionality
Okay, so the application preferences plugin will provide you with four methods that you can use to interact with the native Android preferences.
get(key, success, fail)
If the key exists in the preferences it will be returned as the single parameter of the success callback that you provide. If the key does not exist the failure callback will be executed with an error object with error.code set to 0 which means no property.
window.plugins.applicationPreferences.get(key, function(value) {
console.log("The value is = " + value);
}, function(error) {
console.log(JSON.stringify(error));
});
set(key, value, success, fail)
If the key exists in the preferences then value will be saved and your the success callback will be executed. If the key does not exist the failure callback will be executed with an error object with error.code set to 0 which again means no property.
window.plugins.applicationPreferences.set(key, value, function(value) {
console.log("set correctly");
}, function(error) {
console.log(JSON.stringify(error));
});
load(success, fail)
Calling load will have the native side loop through all the preferences creating a JSON object that will be returned as the single parameter of your success callback.
window.plugins.applicationPreferences.load(function(value) {
console.log("The object is = " + JSON.stringify(value));
}, function(error) {
console.log(JSON.stringify(error));
});
show(activity, success, fail)
Calling show passing in the class name of your PreferenceActivity class will cause the native Android GUI to be shown so your user can interact with the preferences. If the class name you pass in doesn't exists your failure callback will be called with an error object with error.code set to 1 which means no preferences activity.
window.plugins.applicationPreferences.show("com.simonmacdonald.prefs.QuickPrefsActivity");
which brings up a GUI that looks like this:
Installation
Installation of the Plugin follows along the common steps:
- Add the script tag to your html:
<script type="text/javascript" charset="utf-8" src="applicationPreferences.js"/>
- Copy the Java code into your project to the src/com/simonmacdonald/prefs folder.
- Create a preferences file named res/xml/preferences.xml following the Android specification.
- Finally you'll need to create a class that extends PreferenceActivity in order to be able to view/modify the preferences using the native GUI. Refer back to the tutorial I mentioned for more details.
Oh, and I'm pretty sure that Darren McEntee has already included this plugin in his Live Football on TV app which means this plugin is already in the wild.
Enjoy!
