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.
DISCLAIMER: This article is recommended for more technical users who wish to create their own custom JS snippets to use in Checkbox to extend current functionalities and integrations.
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. |
| 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', } |
|
api.env('environmentVariableName') |
Function |
string, number, array, undefined |
This function allows you to access environment variable values based on 'environmentVariableName'. api.setVariable('outputJSValue', identifierName);
environmentVariableName is the unique name of the environment variable you have created. Please ensure that the environment variable name in the JS snippet is wrapped in ‘ ‘.
OutputJSValue is the output JS value that will be transferred into a Checkbox variable from the JS block. You are free to rename this as necessary but will need to reference this correctly in the JS block.
|
Example: Link to JavaScript Block sample file
FORM page API
This section covers how to use embedded javascript code in FORM blocks, 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 |
| lodash | 3rd party library |
lodash is a popular utility library provided for convenience |
| validator | 3rd party library |
validator is a popular input validation library provided for convenience |
| 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" |