PhoneGap Android Application Preferences Plugin

So I'm working on a side app that I get to touch about once a month for about 15 minutes and one of the things I ran into is that I need a way to store user preferences. Well I realized that I could build my own HTML page and store the data in localStorage but I wouldn't learn anything new that way. In the end I decided to do a plugin that would allow PhoneGap developers to use Android Application Preferences and I modelled it after the existing iOS plugin by originally by Tue Topholm (Randy McMillian ported it to the updated Plugin API on iOS).

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:

1. Add the script tag to your html:
   

   <script type="text/javascript" charset="utf-8" src="applicationPreferences.js"/>

2. Copy the Java code into your project to the src/com/simonmacdonald/prefs folder.
3. Create a preferences file named res/xml/preferences.xml following the Android specification.  
4. 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. 

That's about it. Give the plugin a try if you need to store native preferences and let me know what you think.

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!