Using a Cordova plugin API

Cordova plugin features can be used by invoking cordova front calls.

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.

It is a good practice to implement BDL wrapper functions that encapsulate the Cordova front calls specific to this plugin. BDL wrapper libraries are provided with the plugins on the FOURJS Cordova GitHub.

Identifying and verifying the version of available Cordova plugins at runtime

At runtime, the code of an app can query available Cordova plugins with the cordova.listPlugins and get details of the plugin with cordova.getPluginInfo front calls.

To verify the git version in the wrapper modules for usage in direct mode and GAS mode, implement an initialization function in the wrapper module, to check that the GIT_VERSION string defined in the git_version.txt file (found nearby the wrapper library sources) corresponds to the current available plugin version returned by the cordova.getPluginInfo front call:
&include "git_version.txt"  -- defines GIT_VERSION
DEFINE initialized BOOLEAN
PUBLIC FUNCTION initialize()
    IF initialized THEN
        -- exclusive library usage
        DISPLAY "The library is already in use."
        EXIT PROGRAM 1
    END IF
    CALL checkGitVersion(GIT_VERSION)
    LET initialized = TRUE
PRIVATE FUNCTION checkGitVersion(version STRING)
    git_version STRING
  CALL ui.interface.frontcall("cordova","getPluginInfo",["Accelerometer"],[rec])
  IF NOT version.equals(rec.git_version) THEN
      DISPLAY sfmt("fglcdvMotion.4gl version mismatch, git version:%1, expecting:%2.",
                   rec.git_version, version)

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 "":

CALL ui.Interface.frontCall( "cordova", "call",
        ["NetworkStatus","getConnectionInfo"], [result] )
Note: In the files of the plugins, the available methods for the plugins are documented for the JavaScript wrappers and not the underlying native calls.

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
 MENU "network"
   COMMAND "Info"
     CALL ui.Interface.frontCall( "cordova", "call",
             ["NetworkStatus","getConnectionInfo"], [result] )
     CALL fgl_winMessage("Result",result,"info")
   COMMAND "Exit"

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


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

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

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