This is sample cordova plugin (currently for android platform only). Tested with Cordova 5.3.3 + Android 5.1.1
You can get the original codes from here.
How to run example?
Create a new cordova project, for example:
cordova create PluginTest com.shongsu.test PluginTest
Go into the directory you just created.
cd PluginTest
Add Android platform.
cordova platform add android
Add this plugin to your cordova project, type:
cordova plugin add https://github.com/shongsu/cordova-example-plugin.git
or clone this git and add it locally, for example:
cordova plugin add file-path-here
Eidt your www/index.html file, here is full example:
<!DOCTYPE html>
Cordova - Android Plugin Example
```
1. a+b;
2. a-b;
3. a!;
Run application.
In this example, page shuld alert "5 + 3 = 8", "5 - 3 = 2" and "5! = 120".
How it works?
-------------
We have **three files**: native code (.java), javascript code which exposes native code to cordova box (.js) and plugin manifest file (.xml). The structure looks as
ExamplePlugin
│ plugin.xml
│
├─src
│ └─android
│ ExamplePlugin.java
│
└─www
ExamplePlugin.js
<br />
Let's take a look at plugin files:
`src/android//ExamplePlugin.java` contains native code which executes outside of your cordova box.
<br />
`www/ExamplePlugin.js` connects native code with javascript - declares javascript functions `func_add`, `func_sub` and `func_factorial`.
<br />
`plugin.xml` contains info about plugin itself and paths to java and js files.
ExamplePlugin.java
-----------------
package com.shongsu.plugin;
import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CallbackContext;
import org.apache.cordova.PluginResult;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
/**
* This class performs sum called from JavaScript.
*/
public class ExamplePlugin extends CordovaPlugin {
@Override public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException { if (action.equals(“func_add”)) { Integer num1 = args.getInt(0); Integer num2 = args.getInt(1); this.func_add(num1, num2, callbackContext); return true; } else if (action.equals(“func_sub”)) { Integer num1 = args.getInt(0); Integer num2 = args.getInt(1); this.func_sub(num1, num2, callbackContext); return true; } else if (action.equals(“func_factorial”)) { Integer num1 = args.getInt(0); this.func_factorial(num1, callbackContext); return true; }
return false; } ``` ```
private void func_add(Integer num1, Integer num2, CallbackContext callbackContext) { if(num1 != null && num2 != null) { callbackContext.success(num1 + num2); } else { callbackContext.error(“Expected two integer arguments.”); } }
private void func_sub(Integer num1, Integer num2, CallbackContext callbackContext) { if(num1 != null && num2 != null) { int s = num1 - num2; callbackContext.success(s); } else { callbackContext.error(“Expected two integer arguments.”); } }
private void func_factorial(Integer num1, CallbackContext callbackContext) { if(num1 != null && num1 >= 0) { int result = 1; if (num1 == 0 || num1 ==1) { result = 1; } else { for(int i=1;i<=num1;i++) { result *= i; } }
callbackContext.success(result);
} else {
callbackContext.error("Expected a non-negative integer argument.");
} } ``` ```
}
First method `execute` is the same in every plugin, it overrides standard method of CordovaPlugin class and allways has the same parameters:
- Parameter `action` is string containing name of method to execute.
- `args` is array containing variable number of arguments
- `callbackContext` has `.success` and `.error` methods which are called when your function finishes or in case of error.
Note that our plugin class can have many methods, but just one `execute` function. We test `action` argument to see which method we should call.
<br />
Next method `func_add` is our example function: it receives two integers and callbackContext. In case of error it calls `callbackContext.error` with error message string, or in case of success it calls `callbackContext.success` with result.
Same as method `func_sub` and `func_factorial`.
ExamplePlugin.js
---------------
(function (cordova) {
function TestPlugin() {}
TestPlugin.prototype.func_add = function(num1, num2, successCallback, errorCallback) { cordova.exec(successCallback, errorCallback, “ExamplePlugin”, “func_add”, [num1, num2]); };
TestPlugin.prototype.func_sub = function(num1, num2, successCallback, errorCallback) { cordova.exec(successCallback, errorCallback, “ExamplePlugin”, “func_sub”, [num1, num2]); };
TestPlugin.prototype.func_factorial = function(num1, successCallback, errorCallback) { cordova.exec(successCallback, errorCallback, “ExamplePlugin”, “func_factorial”, [num1]); };
window.testplugin = new TestPlugin();
// backwards compatibility window.plugins = window.plugins || {}; window.plugins.testplugin = window.testplugin; })(window.PhoneGap || window.Cordova || window.cordova);
In this file we extend `window.testplugin` object with function `func_add` (for example) which calls `cordova.exec`. Cordova translates that and calls `execute` method from our class declared in ExamplePlugin.java.
Arguments to `exec` are allways the same: two callback functions (success and error callback), plugin class name, action name and array of arguments.
You can pass any number of arguments - they are processed by execute function as described.
plugin.xml
----------
<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
id=”com.shongsu.plugin.ExamplePlugin” version=”1.0.0”>
<description>
Cordova-Android Plugin Example
</description>
<js-module src="www/ExamplePlugin.js" name="ExamplePlugin">
<clobbers target="ExamplePlugin" />
</js-module>
<engines>
</engines>
<!-- android -->
<platform name="android">
</platform>
<!-- more platforms here -->
</plugin>
```
This file tells cordova how to deal with plugin. Package name, class name and (relative) paths to files are defined here. More details about plugin.xml.
For more details refer:
Cordova Plugin Development Guide and Android Plugins
