Add custom cordova plugin to IBM Worklight 6.1

Question

I am trying to add a custom Cordova plugin for the iOS platform, and I am having some issues when I compare that with the process to add a plugin on cordova.

The plugin I am trying to use here is https://github.com/phonegap-build/StatusBarPlugin

With cordova I used to simply use the command line cordova plugin add com.phonegap.plugin.statusbar

First, I tried to modify in native folder, but I noticed that If I do so, It works but It will be erased the next time I deploy again for iOS platform. Second, I tried to add files (plugin js file and cordova_plugins.js file.) under apps/myapp/iphone, or apps/myapp/common, but this causes an issue : The cordova_plugins.js file format seems to become not ok.

Instead of having this working format:

cordova.define('cordova/plugin_list', function(require, exports, module) {
module.exports = [
    {
        "file": "plugins/org.apache.cordova.battery-status/www/battery.js",
        "id": "org.apache.cordova.battery-status.battery",
        "clobbers": [
            "navigator.battery"
        ]
    },
,
    {
        "file": "plugins/com.phonegap.plugin.statusbar/www/statusbar.js",
        "id": "com.phonegap.plugin.statusbar.statusbar",
        "clobbers": [
            "window.StatusBar"
        ]
    }
]
});

It have this format that does not work properly :

/* JavaScript content from worklight/cordova_plugins.js in JS Resources */
/*
* Licensed Materials - Property of IBM
* 5725-I43 (C) Copyright IBM Corp. 2006, 2013. All Rights Reserved.
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
*/
cordova.define('cordova/plugin_list', function(require, exports, module) {
module.exports = [
    {
        "file": "plugins/org.apache.cordova.battery-status/www/battery.js",
        "id": "org.apache.cordova.battery-status.battery",
        "clobbers": [
            "navigator.battery"
        ]
    }
]
});
/* JavaScript content from worklight/cordova_plugins.js in folder common */

/* JavaScript content from worklight/cordova_plugins.js in JS Resources */
/*
* Licensed Materials - Property of IBM
* 5725-I43 (C) Copyright IBM Corp. 2006, 2013. All Rights Reserved.
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
*/
cordova.define('cordova/plugin_list', function(require, exports, module) {
module.exports = [
    {
        "file": "plugins/org.apache.cordova.battery-status/www/battery.js",
        "id": "org.apache.cordova.battery-status.battery",
        "clobbers": [
            "navigator.battery"
        ]
    },
    {
        "file": "plugins/com.phonegap.plugin.statusbar/www/statusbar.js",
        "id": "com.phonegap.plugin.statusbar.statusbar",
        "clobbers": [
            "window.StatusBar"
        ]
    }
]
});

How should I do? Where should I put these file? What is the proper way to add this custom plugin, especially if I want to add it only for iOS and not for Android?

Answer 1

UPDATE: As of MobileFirst 7.1, the SDK is now available as a Cordova plugin.

For those interested in adding 3rd party plugins to their MobileFirst (Worklight) projects I have described my own approach to installing them below, pending a feature release from IBM.

The concept is essentially:

1. create a Cordova project,
2. add the desired plugin,
3. create a MobileFirst project,
4. copy the plugin files from both projects to a staging area (so we can easily identify them),
5. merge the config.xml and cordova_plugin.js files (i.e. supplement the MobileFirst files with the plugin information from the Cordova project) and
6. copy the staged and modified files to MobileFirst.

Disclaimer: as per the accepted answer, IBM do not support/advise modifying the cordova_plugin.js file.

Firstly we need to create the Cordova project (plus the plugin) and MobileFirst projects (steps 1-4). I've used the Ionic Keyboard plugin as an example, needless to say this approach (creating a Cordova project and merging files) works for any supported plugin and target.

## Create a directory to contain your MobileFirst project e.g. mkdir example; cd example; ##
## Create Cordova project ##
mkdir .tmp
cd .tmp/
cordova create plugins com.plugins plugins;
cd plugins/
cordova platform add ios;
cordova plugin add com.ionic.keyboard;
cd ../..
## Create mobile first project ##
mfp create hybrid
cd hybrid/
mfp add hybrid hybrid
mfp add environment iphone
## Generate native files ##
mfp build
cd ..
## Create staging ##
mkdir -p plugins/native/www/default/worklight
mkdir -p plugins/resources/mobilefirst/
mkdir -p plugins/resources/cordova/
mkdir -p plugins/hm/
## Copy config.xml ##
cp hybrid/apps/hybrid/iphone/native/config.xml plugins/resources/mobilefirst/
cp .tmp/plugins/platforms/ios/plugins/config.xml plugins/resources/cordova/
## Copy Cordova files ##
cp -R hybrid/apps/hybrid/iphone/native/www/default/worklight/ plugins/resources/mobilefirst/
## Copy plugins JS ##
cp -R .tmp/plugins/platforms/ios/www/plugins plugins/native/www/default/worklight/
cp -R .tmp/plugins/platforms/ios/www/ plugins/resources/cordova/
## Copy classes ##
cp -R .tmp/plugins/platforms/ios/Plugins/Plugins/com.ionic.keyboard/ plugins/hm/
## Delete the Cordova project as we have copied all of the artefacts we need ##
rm -R .tmp
## Create the config and cordova_plugin.js which is going to override the mfp build version ##
cp plugins/resources/mobilefirst/config.xml plugins/native/
cp plugins/resources/mobilefirst/cordova_plugins.js plugins/native/www/default/worklight/

The staged config.xml and cordova_plugins.js files are now ready to merge (step 5).

Open the plugins/resources/cordova/config.xml file and copy the feature into the plugins/native/config.xml file.

<feature name="Keyboard">
  <param name="ios-package" onload="true" value="IonicKeyboard" />
</feature>

Open the plugins/resources/cordova/cordova_plugins.js file and copy the plugin object into the plugins/native/www/default/worklight/cordova_plugins.js file.

{
  "file": "plugins/com.ionic.keyboard/www/keyboard.js",
  "id": "com.ionic.keyboard.keyboard",
  "clobbers": [
    "cordova.plugins.Keyboard"
  ]
}

Now we are ready to copy the merged files into the MobileFirst project (step 6a).

## Copy from staging to Worklight ##
cp -R plugins/hm/ hybrid/apps/hybrid/iphone/native/Classes/

The first time you copy the files Xcode won't pickup the new classes automatically, so open up the project in Xcode and right click on Classes and 'Add files to ...'. Add the files displayed in the dialog.

Finally, we can copy the files from the plugins/native directory into the MobileFirst project (step 6b). Unfortunately we need to copy this directory after every mfp build, as mfp resets the cordova_plugins.js file each time.

## Do this after every mfp build ##
rm -f hybrid/apps/hybrid/iphone/native/www/default/worklight/cordova_plugins.js
cp -R plugins/native/ hybrid/apps/hybrid/iphone/native/

Once complete, add the client code to your hybrid application and test (don't forget to run step 6 again after the mfp build) e.g.

<input type="text">

window.addEventListener('native.keyboardshow', keyboardShowHandler);

function keyboardShowHandler(e){
    alert('Keyboard height is: ' + e.keyboardHeight);
}

I hope this guide proves useful. I use this process on a daily basis (albeit as part of Grunt) and look forward to a feature release from IBM.

Answer 2

Worklight 6.1.0.x does not yet support adding pre-made Cordova 3.x plug-ins using plugman or any other procedure you would do in a pure Cordova application, including trying to edit the file you're trying to edit. This is a known limitation in current versions of Worklight.

What I would do is read the training material of creating Cordova plug-ins in Worklight, and then take the source of the plug-in you want to add and copy it over.

There are probably other ways to do it, but none is convenient at this time.

Answer 3

There is a issue with the above mentioned solution by Chris. The plugin would surely work if you follow the process correctly but there will be severe consequences later. E.g Since the plugins folder and the cordova_plugins.js file will be overwritten everytime there is a mfp build, the wlapp files generated will never have the plugin code added. Hence if you are using direct update your code will be overwritten once you upload this wlapp file and the plugin would stop working.