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.

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.

&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
END FUNCTION
...
PRIVATE FUNCTION checkGitVersion(version STRING)
  DEFINE rec RECORD
    git_version STRING
  END RECORD
  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)
      EXIT PROGRAM 1
  END IF
END FUNCTION

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.

Android™ Cordova plugin API internals

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

The 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")) { 

IOS® Cordova plugin API internals

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

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

Debug Cordova plugins

To debug your application using a Cordova plugin, build your project with the plugin enabled. This process is outlined in Including Cordova plugins in your Android APK package. After building your project, move the APK file to the external file directory on your device. This path is outlined in the development client. Alternatively, to find the path to the external file directory, use the getexternalstoragepath frontcall command. Moving the APK file to this directory allows the development client to recognize Cordova plugins packaged in it. This makes it possible to launch and develop your application in remote mode. With a device running on Android 14, for security reasons, this APK file needs to be read-only (file permissions "-r--r--r--"). If the APK file is not read only, the Cordova plugin cannot be loaded.