(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.
You can find the complete plugin.xml specification here. In a glimpse, it breaks down to the following steps.
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.
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.
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.