(This is a guest post by Iva Koevska, a technical writer on the Icenium team at Telerik.)
When you develop hybrid mobile applications with Apache Cordova, at some point in time, you will need to use a device capability that the core Apache Cordova APIs just don't support. That's when you'll either dig through GitHub in search of a custom plugin, or you'll resort to writing one. Whatever the case, once you have the plugin in your hands, you'll need to install it to your project.
Whether you're using Icenium or another set of tools for cross-platform mobile development, the go-to tool for installing custom plugins is Plugman. The thing is, Plugman has its own requirements that your custom plugin must meet.
To satisfy the almighty Plugman, a custom plugin should meet the following requirements.
plugin.xml
file.The plugin.xml
file defines the entire plugin, including its structure, changes to the configuration files, dependencies, and so on. Plugman pulls all the data from plugin.xml
and applies the corresponding changes to the structure and the configuration files of the application package. With a proper plugin.xml
file, you do not need to go and add code to Info.plist
, AndroidManifest.xml
, or config.xml
manually. Also, if you declare the plugin JavaScript file in a <js-module>
element, you do not need to reference the plugin script file in the index.html
file for your app.
You can find the complete plugin.xml
specification here. In a glimpse, it breaks down to the following steps.
<plugin>
element with a plugin namespace, version, and identifier.<asset>
or a <js-module>
element.<asset>
element, you declare one or more files or folders of any type that need to be copied to the application file structure. These files and folders contain the plugin functionality and you need to explicitly reference them from the application code.<js-module>
element, you declare one or more JavaScript files in the CommonJS module format. These files contain the plugin functionality and you do not need to reference them from the application code. You do not need to make any references because Apache Cordova handles any <script>
includes for you.<platform>
element.
<config-file>
element. Set the path and the parent XML element for the changes.
config.xml
to map it to the native APIs.<plugin>
element.<feature>
element.AndroidManifest.xml
.AndroidManifest.xml
manually.Info.plist
.Info.plist
manually.<source-file>
, <resource-file>
, or <header-file>
elements.A more thorough overview of the process, including sample code, is available here.
You can also use the following templates as a starting point. Just replace the placeholders with the correct values for your plugin and comment out or delete any unnecessary elements. Most of the time, the changes you will need to make to these templates will be trivial.
Targeting iOS and Android | Targeting Android | Targeting iOS | |
---|---|---|---|
Targeting Apache Cordova 2.x | A plugin.xml template using the <asset> element.A plugin.xml template using the <js-module> element. | A plugin.xml template using the <asset> element.A plugin.xml template using the <js-module> element. | A plugin.xml template using the <asset> element.A plugin.xml template using the <js-module> element. |
Targeting Apache Cordova 3.x | A plugin.xml template using the <asset> element.A plugin.xml template using the <js-module> element. | A plugin.xml template using the <asset> element.A plugin.xml template using the <js-module> element. | A plugin.xml template using the <asset> element.A plugin.xml template using the <js-module> element. |
Sometimes, plugin.xml
might require additional work though. For example, this is the case with the BarcodeScanner plugin which contains multiple source files and depends on some native iOS frameworks. Here's how you can check out the implementation of the BarcodeScanner plugin and its valid plugin.xml
file in Icenium.
Or, you can enable any of the integrated plugins in an Icenium project and check out their corresponding plugin.xml
files for reference.
This one is more of a recommendation and less of a requirement. The rules are pretty simple.
plugin.xml
goes in the root of the plugin.www
folder in the root of the plugin.src
foler in the root. Android files go in src\android
and iOS files - in src\ios
. Some additional rules apply to the platform-specific folders. (For example, you might need to put the Android files in a folder structure that represents the package
declaration in the JAVA
file for the plugin.)You can find the complete guide for the changes you need to make to the directory structure along with some examples here. After you make all the necessary changes, your folder structure should look like this.
When using a custom plugin, Plugman-compatible or not, make sure that the plugin is compatible with the target Apache Cordova version of your project.
If after you cover the requirements of Plugman, you are still unable to install the custom plugin, you might want to poke around the plugin code and update it. You can check out some of these resources as a starting point.
Iva Koevska is the technical writer on the Icenium team. At the office, she’s poking around the next best feature or interrogating the team about how and why things (don't) work. Off office hours, she’s probably riding her motorcycle, checking out a new food place, or hiking around Vvardenfell. On Twitter she's @admatha.