Table of Contents

1. Javascript Block Overview
   1. When should you use Javascript in Checkbox?
   2. What is the difference between using JS snippets in FORM and JS blocks?
   3. What are the 3 key components of setting up JavaScript in Checkbox?
   4. Do you need to code to add extra JS functionalities in Checkbox?
   5. How to set up a JavaScript snippet in Checkbox
2. API List

Javascript Block Overview

When should you use Javascript in Checkbox?

Checkbox allows users to upload JavaScript (JS) snippets in FORM and JS blocks to extend the existing functionalities of Checkbox Apps by enabling:

• Complex programmatic logic beyond standard Checkbox capabilities with conditions
• API calls to public or custom endpoints to enable custom functionality & integration
• Control over the content of a FORM page through an event-based AP

 

What is the difference between using JS snippets in FORM and JS blocks?

FORM Block

When JS snippets are used in FORM blocks, the JS functions will be executed in the front-end (i.e. on the FORM page). JS snippets uploaded and embedded in FORM blocks can be executed through changes in user input fields, clicking “Next” or “Submit” or once a page has been loaded.

Common use cases include:

• ABN Lookup
• ACN Lookup
• Auto-population of fields
• Redirect after completing an Assessment

JS Block

When JS snippets are used in JS blocks, the JS functions are executed in the back-end.

Common use cases include:

• Variable manipulation (e.g. variable overwrite)
• Integrations (e.g. push/pull data from Xakia, Salesforce etc)
• Complex calculations

 

What are the 3 key components of setting up JavaScript in Checkbox?

There are 4 key components that are part of setting up a JS snippet in Checkbox to add extra functionalities and integrations. However, depending on the JS snippet, not all components are necessary for a JS snippet to be executed.

1. JS File
   This is the file that will include all the JS code to allow the function to be executed through the FORM or JS block.
   
   
2. Input Mapping
   
   a. Variable in Checkbox (only if required)
   This is the variable name of a Checkbox field which will be treated as an input value to execute the extra functionality or integration in the JS snippet. Therefore, JS functionalities and integrations can be executed by end user inputs during an Assessment. The Checkbox variable name must be used in conjunction with the Input JS variable name.
   
   b. Variable in JavaScript (only if required)
   This is the name of the variable within the JS snippet that will be assigned the input value of the provided Checkbox variable to execute the extra functionality or integration in the JS snippet. Therefore, this is where the Checkbox App can become connected to the JS snippet.
   
   
3. Output Mapping
   
   a. Variable in Checkbox (only if required)
   This is the variable which will be treated as the output variable that can be referenced inside a Checkbox App. This variable will have an auto-generated variable name by default but can be edited. The Checkbox variable must be used in conjunction with the variable used in JavaScript.
   
   b. Variable in JavaScript (only if required)
   This is the name of the output variable of the JS snippet that holds the output value. This output value is then assigned to a Checkbox variable in the FORM/JS block to use within the App or inside a document.

The possible combinations of using the above components to set up JavaScript include:

1. Only the JS file is required
2. The JS File, Checkbox variable name and input JS variable name are required
3. Only the JS file and output JS variable name is required
4. All four components are required

Do you need to code to add extra JS functionalities in Checkbox?

No. You do not need to code to include extra JS functionalities in Checkbox. Go to our plug-and-play JS Library where you can use pre-made JS snippets that can be quickly incorporated in your App to extend existing Checkbox functionalities and integrations.

However, if you are confident in your coding skills and wish to add any other custom JS snippets to your App, that is still possible. Please see the instructions below on how to set up a JS snippet. 

 

How to set up a JavaScript snippet in Checkbox

JS Block

1. Drag in a JS Block into the Studio and click on it
   
   
2. Click on “UPLOAD JAVASCRIPT” to upload a custom JavaScript snippet file
   
   
   

   
   If input variable(s) of the JavaScript are required, continue following Steps 3-5. If output variable(s) of the JavaScript are required, skip to steps 6-9:
   
   

3. Click “+Add variable” to add input variables to connect the Checkbox platform with the JS snippet
   
   
4. Insert the Checkbox variable and the corresponding input JavaScript variable name
   
   

   
   
   
   

5. Click “SAVE” once changes have been made

    

   The following instructions are for implementing output variable(s) of the JavaScript are required

6. Using the drop-down, select the output variable type (i.e. Text, Number, List, Date or User) and click "+Add variable" to add the output variable from the JS snippet
   
   
   
   
   
7. Insert the variable name used in the JS snippet in the "Variable in JavaScript" field
   
   Note: The variable name that will be used in Checkbox for the output JS variables can be renamed (i.e., TXT86 in the screenshot below can be renamed)
   
   
   
   
   
8. [Optional] Expose the output JS variable by checking the checkbox in the same row
   
   
   
   
9. Click “SAVE” once changes have been made

 

FORM Block

Enabling JavaScript in the FORM Block is very similar. Just a few extra steps in the beginning.

1. Click onto a FORM block and click onto the “JAVASCRIPT” tab in the right panel
   
   
   
   
   
2. Check the “Enable JavaScript" option
   
   
   
   
3. Follow the steps from the JS Block instructions above as required.
   
   
   

API List

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. 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', }
api.env('environmentVariableName')	Function	string, number, array, undefined	This function allows you to access environment variable values based on 'environmentVariableName'. Sample code: const identfierName = api.env('environmentVariableName'); api.setVariable('outputJSValue', identifierName); Definitions: identifierName  is the name of the identifier to call the JS API to retrieve the unique environment variable value. You are free to rename this as necessary.   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 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"