Custom JavaScript

Premium Checkbox Feature

Usage of this feature requires account access to Premium Checkbox features. For queries related to your licence agreement, ask your account administrator to contact your Checkbox Account Manager.

SKIP AHEAD TO
Studio Interface
Javascript API

This is an advanced, technical topic which requires knowledge of the JavaScript programming language.

Checkbox allows for the use of embedded JavaScript code in Custom JS blocks, FORM pages and most Quick Pages (excluding LIST pages). This feature enriches the functionality of an application by enabling:

  • Complex programmatic logic beyond normal Checkbox rules capabilities
  • API calls to public or custom endpoints to enable custom integrations & functionality
  • Near-complete control over the content of a Form page through an event-based API

 

JavaScript Block and FORM page have a different set of APIs, so please ensure you are viewing the correct section for your use case.

 

Studio Interface (Shared)


mceclip0.png

Variable Mapping

Variable mapping is required to inject Checkbox variables into the JavaScript code execution context, and to define what variables will be created by the embedded JavaScript code (if any)

Output Variables

Output variable types must be of one of the following types:

  • Text
  • Number
  • List

 

 JavaScript API


JavaScript Block

This section covers how to use embedded javascript code in the JavaScript Block to retrieve or send data to external systems as well as the JavaScript APIs available or update a variable’s value. Checkbox provides a number of functions and objects are provided to the JavaScript execution context, which can be called from the JavaScript code that is embedded in the JavaScript Block. 

 

API Type Return Type Description
api.getVariable('VarName') Function string, number, array, undefined

This function allows you to access variables passed into this JavaScript Block based on 'VarName', which corresponds to their mapped variable name.

i.e. InputJSVarName in the example above

api.setVariable('VarName', varValue)  Function  

This function allows you to set the value of output to be created by this JavaScript Block based on 'VarName', which corresponds to their mapped variable name.

i.e. OutputJSVarName in the example above

api.makeRequest(options) Function axios response object

Makes an asynchronous request & acts as a wrapper around axios. Returns the axios response object.

Link to axios library

api.getFileURL('fileName' | 'reportName') Function array

This function returns an array of URLs which users can paste into a browser to download uploaded files or reports. The array returned will have a length corresponding to the number of files associated with the 'fileName' or 'reportName'. The URLs within the returned array can be accessed using index notation.

Only REPORT or FILE variables can be passed into this function.

api.getESignInfo() Function array

This function returns an array of all E-Sign pages that were instantiated during the current assessment. The array of details includes pageID, current e-signature status, report name and link to signed document, and original document variable name.  Below is an example:

{

 page: "ESIGN2",

 status: "Completed",

 signedDocuments: [{

   name: "NDA.pdf",

   file: "link_to_file",

 }],

 original: 'FILE1',

}

Example: Link to JavaScript Block sample file

 

FORM page API

This section covers how to use embedded javascript code in FORM & Quick pages, as well as the APIs available. Checkbox provides a number of functions and objects are provided to the JavaScript execution context, which can be called from within the embedded code.

NOTES:

  • Comments must be wrapped in the /* */ style, comments starting with // are not supported
  • async await is supported
API Type Description
addEvents Function Required: addEvents takes in an object with keys corresponding to the Event types listed below. Each key should have a callback attached, which is executed when the corresponding Event is triggered.
input Object

input is an object for which the keys correspond to the JS variable names that have been mapped to input variables.

In the example above, input.InputJSVarName will allow you to access the variable CheckboxVarName 

input only contains variables passed in via the mapping interface, and does NOT reference any of the fields in the current Form page

output Object

output is an object that allows you to bind variables created within the JS file, to Checkbox variables that can be used later.

In the example above, output.OutputJSVarName = "hello" will set the value of the created variable TXT197 to "hello".

This is only available in the submit event context

form Object

form is a set of APIs to interact with the Form itself. Full list of methods can be found below.

E.g. form.SetValue("TXT13", "new value!")

axios 3rd party library

axios is a popular HTTP client provided for convenience

Link to library

lodash 3rd party library

lodash is a popular utility library provided for convenience

Link to library

validator 3rd party library

validator is a popular input validation library provided for convenience

Link to library

done(); Function

Required in submit function

done() tells the engine that the javascript execution is finished when in the submit function, to allow for any asynchronous calls.

 Example: Link to sample FORM page JS file here

 

addEvents Event types

Event type Example Description
onLoad onLoad: async () => {}

The onLoad event callback is triggered on the initial load of the Form page.

Useful for prepopulating fields based on previous variables.

submit submit: asnyc () => {}

The submit event callback is triggered when the user successfully submits the form (passing all validation).

The output api is only available in this event callback context

change

'change:TXT13': async () => {}

'change:NAME': async () => {}

The change event callback is triggered after a field is changed.

Useful to perform custom validation or highly dynamic form customisation.

 

form API (FORM page only)

API & Example Return Type Description
GetValue("FieldRefName")

string, number, undefined

Returns current value of the field "FieldRefName".

GetAllValues()

object

Returns an object of current form fields, with their Variable name as the keys.

ShowField("TXT13")

 

Shows the field "TXT13"

HideField("NUM14")

 

Hides the field "NUM14"

SetValue("TXT13", "Hello")

 

Sets the value of the field "TXT13" to "Hello"

SetOptions("SEL12", ["A", "B"])

 

Sets the options of the RADIO or DROPDOWN field to ["A", "B"]

SetError("Global error notification")

 

Generates an error pop-up on the top right of the screen saying "Global error notification"

ShowCustomValidation("TXT13", [cb1, cb2])   Adds array of callback functions to the field "TXT13", where the callback function takes the value of the field, and returns a string error message or undefined if there is no error.
HideCustomValidation("TXT13")   Removes any custom validation callbacks from the field "TXT13"