Cordova JavaScript Plugins

Question

I am beginning to understand the way Cordova works internally more and more; one thing I continue to struggle with is the format of the JavaScript plugins however.

I am used to writing my JavaScript as follows (which is the standard convention, as far as I am aware):

(function () {
    var version = "EXAMPLE",
        v1,
        v2,
        v3
        res;

    function somePrivateFunction(successCallback, errorCallback) {
        someOtherPrivateFunction(sc, ec);
    }

    function someOtherPrivateFunction(successCallback, errorCallback) {
        cordova.exec(sc, ec, 'SomeService', 'SomeMethod', [args]);
    }

    res = {
        VERSION: version,
        doSomething: function (sc, ec) {
            somePrivateFunction(sc, ec);    
        }
    }

    window.myPlugin = res;
}());

However, Cordova uses a format I am completely unfamiliar with. I think (and I have only heard of the term here and there) it uses something called require (judging by the declarations at the top of most plugins).

The format I often see in the official Cordova plugins are like follows:

    var argscheck = require('cordova/argscheck'),
    utils = require('cordova/utils'),
    exec = require('cordova/exec');

var myPlugin = function () {

}

myPlugin.doSomething = function(successCallback, errorCallback) {
    exec(successCallback, errorCallback, 'SomeService', 'SomeMethod', [args]);
}

myPlugin.doSomethingElse = function(successCallback, errorCallback) {
    exec(successCallback, errorCallback, 'SomeService', 'SomeOtherMethod', [args]);
}

modules.export = myPlugin;

Maybe it is because I do not have any knowledge on this require library - but I do not get it? This seems completely foreign to me, in terms of JavaScript.

What is modules, what is the cordova/[...] syntax and what does it indicate. Where are these other cordova modules defined (is that the correct terminology) and where does modules come from?

And finally, what does modules.export do? I am trying to understand the <js-module> tag of plugin.xml and the <clobbers> tag, but this is holding me back I think.

I understand that when Cordova builds the project, it inserts cordova.define surrounding the plugin.

Maybe at least someone can clarify? Thanks!

Answer 1

the require and exec functions are methods of the cordova object. When you install a plugin it gets wrapped in function that give access to the cordova object. Those calls are actually cordova.require and cordova.exec

Here is an example of a plugin js file before and after install:

BEFORE:

var exec = require("cordova/exec");

var VideoPlayer = {
    play: function(url) {
        exec(null, null, "VideoPlayer", "playVideo", [url]);
    }
};

module.exports = VideoPlayer;

AFTER:

cordova.define("com.dawsonloudon.videoplayer.VideoPlayer", function(require, exports, module) {

    var exec = require("cordova/exec");

    var VideoPlayer = {
        play: function(url) {
            exec(null, null, "VideoPlayer", "playVideo", [url]);
        }
    };

    module.exports = VideoPlayer;

});

Additionally, to answer about the config setup, the clobbers command secures the name space of your plugin object. From my plugin:

<js-module src="www/VideoPlayer.js" name="VideoPlayer">
    <clobbers target="VideoPlayer" />
</js-module>

This is stating the name of my JS file, and the object namespace used to call to my plugin in JS.