Using a Cordova plugin API

How to access Cordova plugin APIs

Cordova plugin APIs are available to the front-end and therefore need to be called through Cordova plugin front calls.

Before calling a Cordova plugin function, you need to identify what native APIs are available. If provided, check the Cordova plugin API documentation for available functions.

Identifying Cordova plugin native APIs in JS sources

Cordova plugins are primarily targeted for JavaScript. Each plugin source directory has a www directory with JavaScript wrapper code calling into the native code.

For example, with the cordova-plugin-network-information plugin, the www/network.js file implements the following "getInfo" JavaScript function, that performs an exec() call of the "NetworkStatus.getConnectionInfo" native Cordova function:

NetworkConnection.prototype.getInfo =
    function(successCallback, errorCallback) {
        exec(successCallback, errorCallback,
             "NetworkStatus", "getConnectionInfo", []);
    };

The BDL equivalent of the above exec() call is done with the generic Cordova front call "cordova.call":

CALL ui.Interface.frontCall( "cordova", "call",
        ["NetworkStatus","getConnectionInfo"], [result] )

In order to find available native Cordova APIs, such as getConnectionInfo, search for the exec() calls in the js files of the www directory. The native Cordova function name is the fourth parameter of the exec() function.

Implementing an app that uses the Cordova plugin

After installing a plugin, you can create a Genero program using a function of this plugin, by using the generic front call for Cordova APIs.

For example:

IMPORT FGL fgldialog
MAIN
 DEFINE result STRING
 MENU "network"
   COMMAND "Info"
     CALL ui.Interface.frontCall( "cordova", "call",
             ["NetworkStatus","getConnectionInfo"], [result] )
     CALL fgl_winMessage("Result",result,"info")
   COMMAND "Exit"
     EXIT MENU
 END MENU
END MAIN

Compile and build your app as usual (the installed Cordova plugins will be included).

Cordova plugin front calls overview

Cordova plugin front calls are generic functions that give access to the native Cordova APIs, in conjunction with the predefined cordovacallback action.

The cordova.call function issues a synchronous Cordova function call. In this case, the underlying native function is executed and the program waits until it returns. Results are provided in the front call output parameters.

The cordova.callWithoutWaiting function performs an asynchronous Cordova function call. The program continues while the Cordova function executes in parallel. The program can implement a trigger for the cordovacallback predefined action, to detect when results are available. To retrieve results of asynchronous calls, use the cordova.getCallbackDataCount, cordova.getCallbackData and cordova.getAllCallbackData front calls.

See these front calls in action in the demos provided on the FOURJS Cordova Github.

Implement BDL wrappers on top of Cordova front calls

For better code readability and maintenance, we strongly suggest you implement BDL functions that encapsulate Cordova front calls, as done with plugins available on the FOURJS Cordova Github.

Cordova plugin API internals

The IOS code is located in the src/ios directory of a plugin.

The Android™ code is located in the src/Android directory of a plugin.

The IOS code in src/ios/CDVConnection.m contains a method called

 (void)getConnectionInfo:(CDVInvokedUrlCommand*)command

This is the native objective-C method called by the front call.

The Android code in src/android/NetworkManager.java, contains an execute method for handling the getConnectionInfo string:

public boolean execute(String action, JSONArray args, CallbackContext callbackContext) {
 if (action.equals("getConnectionInfo")) {