phonegap

Custom Cordova Plugin

By: Ryan Wong at

I haved looked all over and theres no good complete guide to making a cordova plugin that’s not something trival like hello world or one liner android functions.

Step #1
1.Go to github and run the following:

1
git clone https://github.com/don/cordova-plugin-hello.git

2.Change the following in the plugin.xml

  • change plugin id to “com.company.pluginname”
  • change plugin name to your plugin name
  • change asset src to your javascript file in www
  • rename js-module hello src
  • in platform feature, rename Hello to the central java file where it delegates to other function
  • add source-file for each of your java files you will use. for source put “src/android/javafile.java” and target-dir=”src/com/companyname/plugin” even though it’s not physicaly there
  • if you are using external jar files in your project, here’s an example:
    1
    <source-file src="src/android/libs/mail.jar" target-dir="libs" />

3.Now I’ll explain how the www/hello.js file works.

1
2
3
greet: function (name, successCallback, errorCallback) {
        cordova.exec(successCallback, errorCallback, "Hello", "greet", [name]);
    },

The greet function is the name your javascript will call.

successCallback is the call back used if successful.

errorCallback is the call back used if unsuccessful.

name is a parameter that you pass in to this function. To be honest you can add more parameters. Then group all parameters into an array for cordova.

You can add more functions that one.

4.On to the Delegator java file you selected.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
package com.company.plugin;

import org.apache.cordova.*;
import org.json.JSONArray;
import org.json.JSONException;
//add more imports if you want

public class Delegator extends CordovaPlugin {

    @Override
    public boolean execute(String action, JSONArray data, CallbackContext callbackContext) throws JSONException {

        if (action.equals("greet")) {
            String name = data.getString(0);
            String message = "Hello, " + name;
            callbackContext.success(message);
            return true;
        } else if (action.equals("retrieveEmails")){
            String host = data.getString(0);
            String port = data.getString(1);
            String email = data.getString(2);
            String password = data.getString(3);
            //if (success){
	        //    callbackContext.success(data);
            //} else{
            //	callbackContext.error(some message);
            //}
            return true;
        } else{
        	return false;
        }
    }
}

In this class you will use if statements to see which function was called in javascript and you can retrieve the parameters using the getString() function.

5.To test your plugin do the following:

1
2
3
4
cordova new  test com.company.test Test
cordova plugin add ../pluginfolder
cordova platform add android
cordova run android --device

Make sure you open the inspect devices tab in chrome to see how well it did.

#Notes about creating the plugin from the java side
When I was first given the task to make a phonegap plugin that doesn’t exist, I was freaking out that I had to learn android completely and then make this magical plugin but in reality it wasn’t too bad. From the many hours I wasted figuring out how to make the phonegap plugin, I found these tips useful especially if your a beginner at android.

1.Read up what android activity lifecycle is.
2.Read up what android intents are.
3.Create a new project in android with an existing activity.
4.When setting up android studio to work make sure you change gradle to the following settings to save you time.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
apply plugin: 'com.android.application'

android {
    compileSdkVersion 19
    buildToolsVersion "22.0.1"

    defaultConfig {
        applicationId "com.companyname.plugin"
        minSdkVersion 19
        targetSdkVersion 21
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    //    compile 'com.android.support:appcompat-v7:21.0.3'
}

5.Then in the folder (com.companyname.plugin) create a Test.java and just put a basic java program below and run the code to make sure everything is setup:

1
2
3
4
5
6
7
package com.companyname.plugin;
//add import files you will use here
public class Test {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

6.Now just code what you want done in this class. If your not using any
device function then you don’t even need to run it in an emulator.
7.Once it’s correct copy the java files into the “src/android” folder along with libs you used.
8.At this point just add and remove the plugin to make adjustments and test on real phone
How this guide gives you a more complete picture.