Implement front call modules for GWC

Custom front call modules for the GWC-JS front-end are implemented by using JavaScript™.

GWC-JS custom front call basics

In order to extend the GWC-JS 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 GWC-JS front-end.

With GWC-JS, 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 GWC-JS front-end

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

Basically, you will have to:

Setup GWC-JS customization (install Node.js).
Extract the GWC-JS front-end archive into a project-dir directory,
Copy your custom front calls JavaScript modules in the project-dir/customization,
Rebuild the GWC-JS front-end with the grunt utility.
Configure the GAS to use the customized GWC-JS front-end.

For more details, see GWS-JS customization chapter in the GAS documentation.

Structure of a custom front call JavaScript module

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

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:

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

GWC-JS custom front call API

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

Table 1. GWC-JS 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 occured. 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 asynchroneous front call. See Asynchroneous custom front calls for more details

Synchroneous custom front calls

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

The next code example returns a single value:

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

Following code example returns three values:

   return ["first", "second", "third"];

Asynchroneous custom front calls

JavaScript custom front calls sometimes require asynchroneous 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 value after a delay of 5 seconds:

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

Example

The next JavaScript code example implements a synchroneous and an asynchroneous 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])