How To Make Your Apache Cordova Plugins Plugman Compatible

(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.

What Does Plugman-Compatible Mean?

To satisfy the almighty Plugman, a custom plugin should meet the following requirements.

• The plugin should contain a valid plugin.xml file.
• The plugin should have a valid directory structure.

Requirement #1: Valid plugin.xml

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.

1. Define the document as an XML document.
2. Declare the top-level <plugin> element with a plugin namespace, version, and identifier.
3. Declare the files that contain the plugin functionality in an <asset> or a <js-module> element.
   With the <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.
   With the <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.
4. Declare the platform-specific information for each supported mobile platform in a separate <platform> element.
   1. Declare any transformations that need to be made to the configuration files in a <config-file> element. Set the path and the parent XML element for the changes.
      1. Add the plugin to config.xml to map it to the native APIs.
         For Apache Cordova 2.x projects, use the <plugin> element.
         For Apache Cordova 3.x projects, use the <feature> element.
      2. Add any permissions, activities, intents, and other configuration settings that the plugin requires for Android to AndroidManifest.xml.
         Use the same markup you would use when editing AndroidManifest.xml manually.
      3. Add any configuration settings that the plugin requires for iOS to Info.plist.
         Use the same markup you would use when editing Info.plist manually.
   2. Declare the source, resource, and header files that contain the native functionality for the corresponding platform in <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.

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.

Requirement #2: Valid Directory Structure

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.
• The script file for the plugin goes in a www folder in the root of the plugin.
• Any platform-specific files go in an 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.

Last but Not Least

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.

• How to Write a PhoneGap 3.0 Plugin for Android
• Why Don't My Plugins Work in PhoneGap Android 2.7?
• Cordova Plugin Upgrade Guide