Monaca Docs
Search…
Custom Cordova Plugins
Cordova Plugin provides a simple way to write a native code onto your program. On this page, we will describe how to create and add custom Cordova plugins into your Monaca project.
You need to subscribe to a valid plan in order to use custom Cordova plugins. Please refer to Monaca Subscription Plans.
Your custom Cordova plugin needs to follow these requirements:
- It should be compatible with Cordova 4.2 or higher.
- It must have a
plugin.xmlfile and is installable withplugmancommand line tool. - It must support iOS and Android platforms.
You can find various Cordova plugins in the Internet, but it is likely that they are either obsolete or their version would not match. Therefore, how to create a custom Cordova plugin from scratch is covered in this page.
Structure of a Cordova plugin
A typical structure of a Cordova plugin is as follows (directories are displayed in bold letters):
- plugin_name
- src
- ios
- plugin_name.h
- plugin_name.h
- www
- plugin_name.js
- plugin.xml
Before getting started, please download the following zip file containing sample plugin code.
When you extract the package, you will see the following files and folders:
plugin.xml file
plugin.xml file is a plugin specification file containing plugin's definitions. For more details, please refer to Cordova Plugin Specification.Below is a
plugin.xml file from the downloaded sample plugin.1
<?xml version="1.0" encoding="UTF-8"?>
2
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
3
id="jp.co.asial.helloworld"
4
version="0.0.1">
5
​
6
<name>HelloWorldPlugin</name>
7
<description>HelloWorldPlugin Description</description>
8
<author>Asial Corporation</author>
9
<license>Apache 2.0 License</license>
10
<engines>
11
<engine name="cordova" version=">=3.5.0" />
12
</engines>
13
<js-module src="www/hello_world.js" name="helloworld">
14
<clobbers target="HelloWorld" />
15
</js-module>
16
​
17
<platform name="ios">
18
<config-file target="config.xml" parent="/*">
19
<feature name="HelloWorldPlugin">
20
<param name="ios-package" value="HelloWorldPlugin"/>
21
</feature>
22
</config-file>
23
<header-file src="src/ios/HelloWorldPlugin.h" target-dir="src/ios" />
24
<source-file src="src/ios/HelloWorldPlugin.m" target-dir="src/ios" />
25
</platform>
26
<platform name="android">
27
<config-file target="res/xml/config.xml" parent="/*">
28
<feature name="HelloWorldPlugin">
29
<param name="android-package" value="mobi.monaca.HelloWorldPlugin"/>
30
</feature>
31
</config-file>
32
<source-file src="src/android/mobi/monaca/HelloWorldPlugin.java" target-dir="src/mobi/monaca" />
33
</platform>
34
​
35
</plugin>
Copied!
hello_world.js file
hello_world.js is defined as js-module in plugin spec. Therefore, it will be automatically loaded by cordova.js, which is included in loader.js.1
var HelloWorld = function() {};
2
​
3
HelloWorld.prototype.say = function(success, fail) {
4
cordova.exec(success, fail, "HelloWorldPlugin","say", []);
5
};
6
​
7
var helloWorld = new HelloWorld();
8
module.exports = helloWorld;
Copied!
For more details about how to write Cordova callback function, please refer to Plugin Development Guide.
iOS and Android native code
Native code must be written in either Objective-C or Java, depending on the platform. It must have the same function as defined in the JavaScript file. Also, please be aware that all callbacks are asynchronous.
Here are the guides about native code development.
Import a custom Cordova plugin
To import a custom Cordova plugin, please do as follows:
- 1.From the Monaca Cloud IDE, go to Configure → Cordova plugin Settings.
- 2.The Cordova Plugins page will be shown. Click the Import Cordova Plugin button.
3. Then, browse your plugin file (zip file) and click OK.
Monaca Debugger with custom Cordova plugin
The standard Monaca Debugger, which can be found in the store such as App Store or Google Play, includes the standard (core) and several third-party Cordova plugins (refer to Third-party Cordova Plugins for the list of all third-party Cordova plugins pre-included in Monaca). For this reason, the standard Monaca Debugger cannot be used with Monaca projects containing custom or other external third-party Cordova plugins. In this case, custom built Monaca Debugger is required to run such projects properly.
Custom built Monaca Debugger is a debugger which is built within Monaca Cloud IDE inside a project containing custom or external third-party Cordova plugins. Please refer to the following links on how to build custom built debugger and the differences between the standard and custom built debugger:
- Please make sure to import the custom or external third-party Cordova plugins before building the custom built debugger.
We also offer technical support (fee required) for developing your custom Cordova Plugin. Please contact our support team here.
Testing a custom Cordova plugin
- 1.Create a project in the Monaca Cloud IDE using the
Minimum Project Template. - 2.
- 3.Add the following snippet in the
index.htmlfile. The code below shows just a simple message dialog using the sample custom Cordova plugin:1<script>2document.addEventListener("deviceready", onDeviceReady, false);3function onDeviceReady() {4window.HelloWorld.say(5function(result) { alert( "success: " + result ); },6function(error) { alert( "error: " + error ); }7);8}9</script>Copied! - 4.Now, run the project in the standard Monaca Debugger. You will see that the message dialog will not be shown because the custom Cordova plugin doesn't exist in the standard debugger.
- 5.Build a custom built Monaca Debugger. Please refer to the following links on how to build a custom built Monaca Debugger:
- 6.Install the custom built Monaca Debugger.
- 7.Open the debugger and check the debugger's information by clicking the About this debugger button.
- 1.You should be able to find the custom Cordova plugin as shown in the screenshot below:
- 1.Login to the debugger and run the project containing the custom Cordova plugin. The message dialog should show if the project runs properly.
Last modified 8mo ago