Global client API

The client DWKit app has a global window object with the name API. You can perform some typical operations via its methods by calling the former from the client user's actions code. This section describes the methods of this object.

Prerequisites

The API object is connected to the (app.jsx) application as follows:

import {API} from './../../scripts/optimajet-app.js'
class App extends React.Component {
    constructor(props) {
        window.DWKitApp = this;
        window.DWKitApp.API = API;
        ...
    }

    ...
}

After that you can call the methods of this object as follows: window.DWKitApp.API.someMethod() or DWKitApp.API.someMethod().

API object methods

Form functions

  • formValidate(args) - is used to launch the default form validation mechanism. Usage example:

    validate: function (args){
      DWKitApp.API.formValidate(args); //standard validation
      var hasError = false;
      var errors = {};
      // custom validation
      // hasErrors = true;
      // errors.ComponentName = 'Error message';
      if(hasError){
       throw {
           level: 1,
           message: 'Check errors on the form!',
           formerrors: {main: errors}
       };
      }
      return {};
    }
  • clearErrors() - removes errors for all form controls.

  • setDataField(key,value) - sets a form's data object setting. Usage example:

    {
      var data = ... //getiing data for a grid
      DWKitApp.API.setDataField("gridName", data); //the data will be shown in the grid with name "gridName"
    }
  • changeModelControl(args, key, name, value) - sets the value value to the name property of the control with the key name. Usage example:

    init: function(args){
      return DWKitApp.API.changeModelControl(args, 'someControlWithImage', 'src', '/images/someimage.svg')
    }

    This code will set the URL of the image to be loaded for the control that displays the image. Please, note, that in order for the call of this method to have an effect, the result returned by this method should be returned from client user's action.

  • changeModelControls(args,controlsParameters) - changes properties of several controls. controlsParameters - an array of objects{key,name,value}; the object fields have the same meaning as the changeModelControl method. Usage example:

    init: function(args){
      return DWKitApp.API.changeModelControls(args, [
              {key: 'someControlWithImage', name:'src', value:'/images/someimage.svg'},
              {key: 'someControlWirhContent', name:'content', value:'NewContentValue'},
          ]);
    }

    Please, note, that in order for the call of this method to have an effect, the result returned by this method should be returned from client user's action.

  • rewriteControlModel(controlkey, rewriter) - this is another way of changing control properties. controlkey - the name of the control. rewriter - a function that changes the contol's properties. When called, rewriter receives one parameter - model - an object with all control properties which can be modified. Usage example (adding columns to a grid):

    addColumnsToGrid: function (args){
      //custom data request
      $.get(url).done(function (data) {
          //adding new columns tu the grid based on the response
          var gridModelRewriter = function (model){
              model.columns = [];
              if(Array.isArray(data) && data.length > 0){
                  for(var p in data[0]){
                      if(p == "Id") continue;
                      model.columns.push({key: p, name: p, resizable: true, width: 150, sortable: true});
                  }
              }
          }
          DWKitApp.API.rewriteControlModel("grid", gridModelRewriter); //rewrite grid model with new columns
          DWKitApp.API.setDataField("grid", data); //set data to the grid
      })
      .fail(function (jqxhr, textStatus, error) {
         alertify.error(textStatus);
      });
    }
  • createElement(type,props,children) - create a React component of the type (string) type, with the props properties and child componentschildren or value, which should be displayed by the component. Usage example (creating a hyperling instead of displaying values in a grid column):

    init: function(args){
      var gridModelRewriter = function (model) {
          model.columns[1].customFormatter = function(p){
              var url = "/form/DocumentEdit/" + p.row.Id;
              return DWKitApp.API.createElement("a", { href: url}, p.value);
          };
          return model;
       };
      DWKitApp.API.rewriteControlModel("grid", gridModelRewriter);
    }

Redirect functions

  • redirect(type,name,parameters) - loads a page with the URL formed as /{type}/{name}/{parameters}

  • redirectToForm(name, parameters) - loads a page with the URL formed as /form/{name}/{parameters}

  • redirectToFlow(name, parameters) - loads a page with the URL formed as /flow/{name}/{parameters}

Security functions

Read more about security here.

  • checkRole(roleName) - checks role assigned to current user.
  • checkPermission(permissionName, modalId) - checks permission assigned to current user. If this function is called from a modal window, in the second parameter it is necessary to pass args.modalId. Read more about modal windows here.

Read more about modal windows here.

  • openModal(name, filter, {type, viewType, sidebarWidth, sidebarFrom, onOpenFunc, onCloseFunc}) - opens a modal window with assigned settings. This function is used to be called in the chain of actions which handles the event. It must be used with return statement. Use it in the following way:

    someActionHandler: function (args) {
      return DWKitApp.API.openModel(...);
    }

    Modal window will open after executing all actions in the chain. This function parameters are:

    • name - name of the form or Business flow opened.
    • filter - filter with which data in the form will be filtered; in most cases it's just document ID or server action filter name.
    • type - can take string value 'form' or 'flow', where 'form' is default. Determines whether a form or Business flow will be open.
    • viewType - modal window type; can take string value 'modal' or 'sidebar', where 'sidebar' is default.
    • sidebarWidth - opened sidebar width, string (for example percent value '50%').
    • sidebarFrom - sidebar orientation, string, 'right' or 'left', where 'right' is default.
    • onOpenFunc - callback function called when opening the window.
    • onCloseFunc - callback function called when closing the window.
      The only obligatory parameter is name. For example:
    createTask: function (args){
      return DWKitApp.API.openModal("taskshort", undefined, { type: "form", viewType: "sidebar", sidebarWidth: "50%", onCloseFunc: function(){
          DWKitApp.onRefresh();
      }});
    }
  • openModalDispatch(name, filter, {type, viewType, sidebarWidth, sidebarFrom, onOpenFunc, onCloseFunc}) - opens a modal window with assigned settings. This function is used to call from any javascript code, executed in DWKit. It is used without return statement in the following way:

    someActionHandler: function (args) {
      DWKitApp.API.openModelDispatch(...);
    }

    Modal window will open immediately after calling the function. This function parameters are identical to openModal function.

Server code actions call

  • callServerCodeAction(name, request, callback) - calls server Action. This function is used to be called in the chain of actions handling the event. It must be used with return statement. It is used in th following way:

    someActionHandler: function (args) {
      return DWKitApp.API.callServerCodeAction(...);
    }

    The result which returns server action, will be applied to the global state of the client application after executing all actions in the chain. This function parameters are:

    • name - server action name
    • request - object which will be transmitted to the server and converted into dynamic.
    • callback(response) - callback function called when receiving response from server, but before applying changes to the global state of the client application. The only obligatory parameter is name.
  • callServerCodeActionDispatch(name, request, callback) - call server Action. This function is used to call from any javascript code, executed in DWKit. It is used without return statement in the following way:

    someActionHandler: function (args) {
      DWKitApp.API.callServerCodeActionDispatch(...);
    }

    The result, which returns server action, will be applied to the global state of the client application after receiving server response. This function parameters are identical callServerCodeAction function.