Build your own plugin

This article assumes you have worked through Build your own Background Service and now wish to package it as a plugin.

Cordova expects Plugman format plugin - this is basically a collection of file (assets) and a plugin.xml to tell Plugman how to use those assets.

In this article we will:

• Build a folder structure for our plugin
• Copy our java code into the structure
• Create a Javascript wrapper for our service and add that to the structure
• Amend our HTML page and copy that into the structure
• Create the plugin.xml file

Steps

Step 1: Create the folder structure

Create the following folder structure:

c:\
   + MyService\
      + src\
      |   + android\
      + www\

Step 2: Copy in the java code

Copy the MyService.java (created in Build your own Background Service) into c:\MyService\src\android

Step 3: Create the myService.js

Create a file called myService.js in c:\MyService\www

In this file add:

var serviceName = 'com.red_folder.phonegap.plugin.backgroundservice.sample.MyService';

var factory = require('com.red_folder.phonegap.plugin.backgroundservice.BackgroundService')
module.exports = factory.create(serviceName);

Notice that this is very similar to the code in the deviceready block from the previous article. We separate this logic out into a separate js file so that we can take advantage of the plugin logic to add into the module list (see the js-module section in Step 5).

Step 4: Copy in the HTML page

Note that you may not want to include any HTML files in your production plugin. We include it in this plugin (and the bgs-sample) to provide a demonstration of how to use the plugin.

Copy your HTML file to c:\MyService\www (for this article I will assume it is called MyService.html).

Amend the MyService.html - change the deviceready block to:

   document.addEventListener('deviceready', function() {
      myService = cordova.plugins.myService;

      getStatus();
   }, true);

Again, like step 3, we are taking advantage of the plugin logic to encapsulate the Javascript logic for creating the service and adding it to the plugin list (see the js-module section in Step 5).

Step 5: Create the plugin.xml

Create plugin.xml within c:\MyService. Add the following to the file:

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
        xmlns:android="http://schemas.android.com/apk/res/android"
        id="com.red_folder.phonegap.plugin.backgroundservice.sample"
        version="0.1">

   <name>Background Service Plugin - Sample Background Service</name>

   <description>
      Sample service to demonstrate the use of the Cordova Android Background Service
   </description>

   <license>MIT</license>

   <engines>
      <engine name="cordova" version=">=3.0.0"/>
   </engines>

   <!-- Load in the core background service -->
   <dependency id="com.red_folder.phonegap.plugin.backgroundservice" url="https://github.com/Red-Folder/bgs-core.git" commit="9d947a9f1858284b312ad1032de6af590b33fa37" />

   <!-- android -->
   <platform name="android">

      <js-module src="www/myService.js" name="MyService">
         <clobbers target="cordova.plugins.myService" />
      </js-module>

      <asset src="www/myService.html" target="myService.html" />

      <source-file src="src/android/MyService.java" target-dir="src/com/red_folder/phonegap/plugin/backgroundservice/sample" />

      <config-file target="AndroidManifest.xml" parent="/manifest/application">
         <service android:name="com.red_folder.phonegap.plugin.backgroundservice.sample.MyService">
            <intent-filter>         
               <action android:name="com.red_folder.phonegap.plugin.backgroundservice.sample.MyService"/> 
            </intent-filter>     
         </service>
      </config-file>
    
   </platform>
</plugin>

For a full description of the plugin.xml format see Plugin Spec.

The dependency node tells Plugman that this plugin requires the bgs-core. It is recommended that you include the commit version for the version of which you test your plugin against. This will avoid updated to the bgs-core breaking your plugin. It is obviously recommended to watch the bgs-core plugin repository for changes so that you can re-test your plugin and update as accordingly. To get the commit version, click on the copy icon on the top of the bgs-core repository.

As this is an Android only plugin, I've included the rest of the config within a platform block.

The js-mobule block tells the Plugman to use the MyService.js and to create it as cordova.plugins.myService. Thus the changes we made above in steps 3 & 4.

The asset block adds the MyService.html from www and puts into the asset/www directory of the target application.

The source-file block copies in the java file. Note that the target-dir needs to match the package of your class.

The config-file block makes changes to the target projects AndroidManifest.xml and set up your class as a recognized service. Note that this XML code uses the fully qualified name of the class.

Save the plugin.xml.

Step 6: Test the plugin

You should now be able to create a "clean" project and use your plugin.

Use the following steps:

• cordova create hello com.example.hello "HelloWorld"
• cd hello
• cordova platform add android
• cordova plugin add c:\MyService
• Amend the hello\www\config.xml, replace any existing content node with: <content src="myService.html" /> (add the content node if not already present)
• cordova build

What next

This example has shown us how to create a plugin within a local folder structure. To make this plugin available to others it is an easy step to upload to github (using the same folder structure). To install you would then simply do:

cordova plugin add https://github.com/YourRepo/MyService.git

I would encourage you to share your plugins with others.