Implement front call modules for GBC

Custom front call modules for the Genero Browser Client (GBC) front-end are implemented by using JavaScript.

GBC custom front call basics

In order to extend the GBC with your own front calls, you must be familiar with JavaScript programming concepts.

Important: Custom front call module and function names must be registered in lowercase for the GBC front-end.

With GBC, front-end calls are JavaScript functions executed locally on the workstation where the browser is running.

Note: Executing front calls in the context of a web browser is limited to the OS functions a web browser can do. For example, it will not be possible to delete a file on the computer where the browser executes.

Customizing the GBC front-end

In order to integrate your custom front calls in the GBC front-end, you need to setup the GBC customization environment.

Basically, you will have to:
  1. Setup GBC customization (install Node.js).
  2. Extract the GBC front-end archive into a project-dir directory,
  3. Copy your custom front calls JavaScript modules in the project-dir/customization,
  4. Rebuild the GBC front-end with the gbc build utility.
  5. Configure the GAS to use the customized GBC front-end.

For more information, see the Genero Browser Client User Guide.

Structure of a custom front call JavaScript module

One JavaScript module will define a front call module implementing several front call functions.

The .js file must be copied into the project-dir/customization directory.

A custom front call JavaScript module must have the following structure:

"use strict";

modulum('FrontCallService.modules.module-name', ['FrontCallService'],
  /**
   * @param {gbc} context
   * @param {classes} cls
   */
  function(context, cls) {
    context.FrontCallService.modules.module-name = {

      function-name: function (param1, ...) {
        
           ... user code ...

      {
        return [ values ... ]
      |
          this.setReturnValues([ values ... ]);
      }

      },

      [...]   /* More functions can be defined for this module */

    };
  }
);

Where:

  1. module-name is the name of the front call module, and corresponds to the first parameter of ui.Interface.frontCall().
  2. function-name is the name of the front call function, and corresponds to the second parameter of ui.Interface.frontCall().
  3. param1, param2 ... are the input values provided as third parameter of ui.Interface.frontCall().
  4. values is a JavaScript array containing the values to be returned in the last parameter of ui.Interface.frontCall().

GBC custom front call API

The following JavaScript functions are provided to implement your custom front calls:

Table 1. GBC custom front call API
Method Description 
this.parametersError( [ message ] )

This function can be invoked when an invalid number of parameters is passed to the front call, in order to raise on exception in the BDL program.

The message parameter holds the error message to be returned to the Genero program in the second part of the error -6333 message (see front call error handling in ui.Interface.frontCall).

 
this.runtimeError(  [ message ] )

This function can be used to raise an exception in the BDL program, when the front call needs to warn the program that an error occurred.

The message parameter holds the error message to be returned to the Genero program in the second part of the error -6333 message (see front call error handling in ui.Interface.frontCall).

 
this.setReturnValues( values )

This function sets the values to be returned to the BDL program in the case of an asynchronous front call. See Asynchronous custom front calls for more details

Synchronous custom front calls

Synchronous front calls can directly return the front call values with a classic JavaScript return instruction, by specifying a JavaScript array.

The code example returns a single value: 
   return ["Hello " + name + " !"];
Following code example returns three values: 
   return ["first", "second", "third"];

Asynchronous custom front calls

JavaScript custom front calls sometimes require asynchronous programming. In such case, the custom front call API provides the setReturnValues() function to register values that must be returned to the BDL program.

For example, to return a value after a delay of 5 seconds:

        window.setTimeout(function () {
          this.setReturnValues(["After 5s, Hello " + name + " !"]);
        }.bind(this), 5000);

Example

The JavaScript code in this example implements a synchronous and an asynchronous custom front call function:

"use strict";

modulum('FrontCallService.modules.mymodule', ['FrontCallService'],
  /**
   * @param {gbc} context
   * @param {classes} cls
   */
  function(context, cls) {
    context.FrontCallService.modules.mymodule = {

      add_hello_sync: function (name) {
        if (name === undefined) {
          this.parametersError();
          return;
        }
        if (name.length === 0) {
          this.runtimeError("name shouldn't be empty");
          return;
        }

        return ["Hello, " + name + " !"];
      },

      add_hello_async: function (name) {
        if (name === undefined) {
          this.parametersError();
          return;
        }
        if (name.length === 0) {
          this.runtimeError("name shouldn't be empty");
          return;
        }

        window.setTimeout(function () {
          this.setReturnValues(["After 5s, Hello, " + name + " !"]);
        }.bind(this), 5000);
      }
    };
  }
);
From the Genero BDL program:
DEFINE res INTEGER
CALL ui.Interface.frontcall("mymodule","add_hello_sync", ["world"] , [res])
CALL ui.Interface.frontcall("mymodule","add_hello_async", ["world"] , [res])