Recently, I dug a little further in Phonegap on writing plugins. The official plugin development guide is hard to grasp for beginner. So this is quick note.

JavaScript Interface

Phonegap plugins allow you to use functionalities on native platform through a single JavaScript interface cordova.exec.

cordova.exec(<successFun>, // success callback function
             <failFun>, // fail callback function
             <service>, // the plugin's service
             <action>, // the plugin's service action name
             <args>); // arguments passed into the service action
  • successFun (Function): if your exec call completes successfully, this function is invoked (optionally with any parameters you pass back to it).
  • failFun (Function): if the operation does not complete successfully, this function is invoked (optionally with an error parameter).
  • service (String): the service name to call into on the native side.
  • action (String): the action name to call into.
  • args (Array): arguments to pass into.

Android Plugin

On the native platform, you needs to implement the service (as class name), which extends CordovaPlugin and overides execute method.

Your plugin must be added to the config.xml file in your Cordova-Android application’s res/xml/ folder.

<plugin name="<service_name>" value="<full_name_including_namespace>"/>

This is a plugin template:

public class YourServiceName extends CordovaPlugin {

    @Override
    public boolean execute(String action, JSONArray args, CallbackContext ctx) {
        if (action.equalsIgnoreCase("an action")) {
            // do some thing
            return true;
        }

        return false;
    }

}
  • action: the action name passed in from the JavaScript interface.
  • args: the arguments passed in.
  • ctx: the callback that you can return information to JavaScript.

You can access your cordova activity and context using this.cordova.getActivity() and this.cordova.getActivity().getBaseContext();.

You can pass data back using ctx with ctx.success(), ctx.error() or ctx.sendPluginResult().

For example, you can refer to the source code of Notification API provided by phonegap.

JavaScript Plugin Wrapper

It is better to wrap your plugin calls, instead of calling cordova.exec directly every time. There are two ways doing it:

The Common Way

This is the common way found in phonegap-plugins repos:

(function(cordova){
    var YourService = function() { };

    YourService.prototype.action = function(args, succeed, failed) {
        return cordova.exec(succeed, failed, 'Service', 'Action', args);
    };

    cordova.addConstructor(function() {
        window.YourService = new YourService();

        // backwards compatibility
        window.plugins = window.plugins || {};
        window.plugins.YourService = window.YourService;
    });

})(window.PhoneGap || window.Cordova || window.cordova);

// you can call your plugin as
window.plugins.YourService.action(args, succeed, failed);

The Require Way

This is what I found in cordova.js’s source code:

cordova.define('cordova/plugin/YourService', function(require, exports, module) {    
    var exec = require("cordova/exec");

    var YourService = function() { };

    YourService.prototype.action = function(args, succeed, failed) {
        return exec(succeed, failed, 'Service', 'Action', args);
    };

    module.exports = new YourService();
});

// you can call your plugin as
var Service = cordova.require("cordova/plugin/YourService");
Service.action(args, succeed, failed);

The require is not compatible with old Phonegap (1.x).

References