Connecting Custom JavaScript-Function

Web application Designer of business applications

The path to the folder with installed web application if plugin description is added in the config.json file:

In Linux OS: /opt/foresight/fp10.x-webserver/r.
In Windows OS: C:\Program Files (x86)\Foresight\Analytics Platform 10.x Web Application\r.

The path to the folder with installed designer of business applications:

If the designer of business applications back end is installed automatically on Apache2 web server or manually on IIS:

In Linux OS: /opt/ERROR: Variable (Company_distr) is undefined./fpERROR: Variable (Version_for_setup) is undefined.-dba;
In Windows OS: C:\Program Files (x86)\ERROR: Variable (Company) is undefined.\DBA_ERROR: Variable (Version_for_setup) is undefined.. The DBA_ERROR: Variable (Version_for_setup) is undefined. folder is created manually and may differ.

If the designer of business applications back end is installed manually on Apache2 web server, Java or automatically on IIS:

In Linux OS: /opt/foresight/dba/10.x.
In Windows OS: C:\Program Files (x86)\Foresight\Designer of Business Application 10.x Web Server.

TIP. To facilitate the use of plugins, create the Plugins folder, which will store plugins.

In Linux OS grant permissions for the custom folder with plugins/created JS file in Debian-based distributions for the www-data user. When working in other Linux OS distributions replace www-data with apache for RedHat-based distributions or with apache2 for ALT Linux.

After executing the operations the custom JS-function is connected to the corresponding object when function name is specified in JS-function call settings.

The main tool file for the Dashboards tool is dashboard.html, the main tool file for the Reports tool is reporter.html. The files are located in the App folder with installed web application of Foresight Analytics Platform.

A custom JS-function can be added as a single file or inserted into the main tool file. Consider the example of adding a function:

To add a JS-function as a single file:

Create a JS-file and write custom JS-function code in it. For example, create the Func.js file with the following code:

function myFunc(){

   alert("Example of calling custom JS-function from file");

}

Add a link to the created JS-file to the <head> tag of the main tool file. For example, if JS-file and main tool file are located in the same folder, the link will look as follows:

Save changes in the main tool file.

To add a JS-function to the main tool file:

Add the <script> tag with JS-function text to the <head> tag of the main tool file. For example:

<script type="text/javascript">
  function myFunc(){

    alert("Example of calling custom JS-function from file");

  }	
</script>

Save changes in the main tool file.

Signatures of Custom JS-functions

Custom JS-function signature for dashboards:

function <function name>(<custom parameters>, args)
{
...
}

Parameters:

Custom parameters. Custom parameter values according to the signature of the called function. Optional parameter.
args. Function arguments. They allow for getting access to the object, from which JS-function was executed.

To work with dashboards, use the KapBox component as the first argument.

The example of the JS-function that displays the number of dashboard blocks in the information message:

function countBlocks(args)
{
  activeSlideBlocks = args.KapBox.getActiveSlideBlocks();
  count = activeSlideBlocks.length;
  alert("Number of slide blocks:  " + count);
}

Custom JS-function signature for regular reports and data entry forms if custom button action is set up:

function <function name>(<custom parameters>, callback, args)
{
...
}

Parameters:

Custom parameters. Custom parameter values according to the signature of the called function. Optional parameter.
callback. Callback function. Mandatory parameter.
args. Function arguments. They allow for getting access to the object, from which JS-function was executed. A detailed description of available methods in the args parameter is given in the Available Methods of Platform Namespace Objects in Regular Report/Data Entry Form JS-Functions section

The examples of functions:

// Display various notifications
async function showNotifications(callback) {
  Platform.Notification.error('Error', 'Error saving data. Invalid value type.');
  Platform.Notification.warning('Warning', 'Calculation may take a long time.');
  Platform.Notification.success('Successful', Calculation is finished.');
  Platform.Notification.info('Information', 'A new report version is available.');
  callback();
}
 
// Refresh regular report/data entry form
function refreshPrx(callback, args) {
  const { moduleId } = args;
  const refresh = Platform.Managers.Prx(moduleId).actions.refresh(); //For data entry form specify Platform.Managers.DataEntryForm(moduleId).actions.refresh()
  callback();
}
 
// Send JSON query
async function closeControlPanel(callback, args) {
  const { moduleId } = args;
  const openId = Platform.Managers.Prx(moduleId).selectors.openId(); //For data entry form specify Platform.Managers.DataEntryForm(moduleId).selectors.openId()
  const closeControlPanel = {
    request: {
      SetPrxMeta: {
        mon: openId,
        tArg: {
          meta: {
            options: {
              controlPanelVisible: false,
            },
          },
        },
      },
    },
    handleResult: (response) => response?.SetPrxMetaResult,
  };
  const response = await Platform.Bi.sendRequest({}, closeControlPanel);
  callback();
}
 
// Batch query execution
async function batchRequests(callback, args) {
  // Queries 
  const request1 = {
    request: {
      // First query
    },
  };
  const request2 = {
    request: {
      // Second query
    },
  };
  const response = await Platform.Bi.sendRequest({batched: true}, request1, request2);
  callback();
}
 
// Call unit/assembly method. The unit/assembly is located outside the container in the repository
async function ExportDataRepo(callback, args) {
  const { moduleId } = args;
  const Id = Platform.Managers.Prx(moduleId).selectors.id();//For data entry form specify Platform.Managers.DataEntryForm(moduleId).selectors.id()
  await Platform.Bi.execMethod(
    null,
    Platform.Managers.MetaBase.connectionId()+'!EXPORT_JS_REPO',// Moniker of opened repository+'!identifier of unit/assembly from repository'
    'Export',// Name of called method
    [Id]// Sent parameter
  );
  callback();
}
 
// Call unit/assembly method. The unit/assembly is located in the contained in the repository
async function ExportDataCont(callback, args) {
  const { moduleId } = args;
  const Id = Platform.Managers.Prx(moduleId).selectors.id();//For data entry form specify Platform.Managers.DataEntryForm(moduleId).selectors.id()
  await Platform.Bi.execMethod(
    'CONT_JS',// Container identifier
    'EXPORT_JS',// Identifier of the unit/assembly in the container
    'Export',// Name of called method
    [Id]// Sent parameter
  );
  callback();
}

Custom JS-function signature in regular report/data entry form to set up hyperlink:

function <function name>(<custom parameters>, args)
{
...
}

Parameters:

Custom parameters. Custom parameter values according to the signature of the called function. Optional parameter.
args. Function arguments. They allow for getting access to the object, from which JS-function was executed. Detailed description of available methods in the args parameter is given in the Available Methods of Platform Namespace Objects in Regular Report/Data Entry Form JS-Functions section.

The examples of functions:

// Refresh report/data entry form
function refreshPrx(args) {
  const { moduleId } = args;
  const refresh = Platform.Managers.Prx(moduleId).actions.refresh();//For data entry form specify Platform.Managers.DataEntryForm(moduleId).actions.refresh()
}
 
// Send JSON query
async function closeControlPanel(args) {
  const { moduleId } = args;
  const openId = Platform.Managers.Prx(moduleId).selectors.openId(); //For data entry form specify Platform.Managers.DataEntryForm(moduleId).selectors.openId()
  const closeControlPanel = {
    request: {
      SetPrxMeta: {
        mon: openId,
        tArg: {
          meta: {
            options: {
              controlPanelVisible: false,
            },
          },
        },
      },
    },
    handleResult: (response) => response?.SetPrxMetaResult,
  };
  const response = await Platform.Bi.sendRequest({}, closeControlPanel);
  const refresh = Platform.Managers.Prx(moduleId).actions.refresh(); //For data entry form specify Platform.Managers.DataEntryForm(moduleId).actions.refresh()
}
 
// Batch query execution
async function batchRequests(args) {
  // Queries 
  const request1 = {
    request: {
      // First query
    },
  };
  const request2 = {
    request: {
      // Second query
    },
  };
  const response = await Platform.Bi.sendRequest({batched: true}, request1, request2);
  const refresh = Platform.Managers.Prx(moduleId).actions.refresh(); //For data entry form specify Platform.Managers.DataEntryForm(moduleId).actions.refresh()
}
 
// Call unit/assembly method. The unit/assembly is located outside the container in the repository
async function ExportDataRepo(args) {
  const { moduleId } = args;
  const Id = Platform.Managers.Prx(moduleId).selectors.id();//For data entry form specify Platform.Managers.DataEntryForm(moduleId).selectors.id()
  await Platform.Bi.execMethod(
    null,
    Platform.Managers.MetaBase.connectionId()+'!EXPORT_JS_REPO',// Moniker of opened repository+'!identifier of unit/assembly from repository'
    'Export',// Name of called method
    [Id]// Sent parameter
  );
}
 
// Call unit/assembly method. The unit/assembly is located in the contained in the repository
async function ExportDataCont(args) {
  const { moduleId } = args;
  const Id = Platform.Managers.Prx(moduleId).selectors.id();//For data entry form specify Platform.Managers.DataEntryForm(moduleId).selectors.id()
  await Platform.Bi.execMethod(
    'CONT_JS',// Container identifier
    'EXPORT_JS',// Identifier of the unit/assembly in the container
    'Export',// Name of called method
    [Id]// Sent parameter
  );
}

Custom JS-function signature for web application and designer of business applications:

Platform.Events.on('<event name>',(args)=>
{
...
})

Parameters:

Event name. Subscription for the following events is available:

startOpenPage. Handle page rendering start event.
startOpenObject. Handle object opening start event.
startOpenFolder. Handle folder open event in the object navigator.

Mandatory parameter. The event returns the arguments that can be used.

args. Function arguments. Optional parameter. They allow for getting event information:

ref. Link to the DOM node, in which the event occurs. It is used for the startOpenPage, startOpenObject, startOpenFolder events.
classNames. Root DOM nodes classes. It is used for the startOpenPage, startOpenObject, startOpenFolder events.
page. Type of opened page:

login. Page displaying login dialog box to log in to the system.
navigator. In the web application - page displaying object navigator. In the designer of business applications - page displaying object navigator or opened object with navigation menu;
object. In the web application - page displaying opened object. In the designer of business applications - page displaying opened object without navigation menu. Object without navigation menu can be opened from another object, for example, from ETL task.

It is used for the startOpenPage event.

object. Object/folder description. It is used for the startOpenObject/startOpenFolder event.
openMode. Tool opening mode. It is used for the startOpenObject event.

NOTE. If the user is subscribed to the startOpenPage and startOpenObject events at the same time, the events are handled one by one: during object opening, the page rending start event is handled first, then the object opening start event is handled.

The example of the JS-function that handles the event of object opening in the web application/business application:

console.log(Platform.Events);
Platform.Events.on('startOpenObject', (args) =>
{
  console.log(args.object.key);
  console.log(args.classNames);
  console.log(args.openMode);
  var d = document.createElement("div");
  d.style="background-color: red;width: 10px;height: 10px;position: absolute;top: 18px;left: 10px;border-radius: 5px; z-index: 1";
  var rootNode = document.getElementsByClassName(args.classNames)[0];
  rootNode.style.position = 'relative';
  if (rootNode )
    rootNode.appendChild(d);
});

To work with regular reports/data entry forms on setting up hyperlink action or custom button action, the following parameters can be used in JS-function signature:

Report. The parameter for managing report.
ReportOdId. Report moniker.
DataEntryForm. The parameter for managing a data entry form.
DataArea. The parameter for managing table area in data entry form.

The example of JS-function when hyperlink is used:

function addAttachmentsTB(row, col, args)
{
  var rep = args.Report;
  var da = args.DataArea;
  var grid = da.getGridView();
  var tabSheet = grid.getTabSheet();
  var tabSheetRange = tabSheet.getCell(row, col);
  attachFile(da, tabSheetRange);
}
function attachFile(da, tabSheetRange){
  var rep = da.getSource();
  var grid = da.getGridView();
  var tabSheet = grid.getTabSheet();
  if (tabSheetRange && tabSheetRange.isValid()) {
       var cells = tabSheetRange.getCells();
       if (cells.length == 1) {
             var cell = cells[0];
             var coord = cell.getCoord();
             var range = { top: coord.rowIndex, left: coord.colIndex, width: 1, height: 1 };
             var views = rep.getGridViews(range);
             var gridKey = views.length ? views[0].key : undefined;
             var attachDlg = da.getGridView().showAttachmentDialog(gridKey, coord.rowIndex, coord.colIndex);
       }
  }
}

Available Methods of Platform Namespace Objects in Regular Report/Data Entry Form JS-Functions

The moduleId field returns unique identifier of the opened object instance, from which JS-function is called. This identifier is used by methods of the Platform.Managers object.

Platform.Managers - object that allows access to opened repository objects, from which JS-functions are called. In the current implementation the following objects are implemented for this object:

The following objects of the Platform namespace are also available when working with regular reports/data entry forms in JS-functions: