How to use functions as part of your scripts

Purpose of a function

Functions are reusable blocks of code that carry out a specific task.

To execute the code in a function you ‘call’ it with another smaller piece of script. We call this piece of script a ‘script caller’

A function can be ‘passed’ ‘arguments’ to use, and a function may ‘return’ a ‘value’ to whatever piece of script that called the function.

A function can perform an action on an entire Form or on a specific form field.

A function can be called within a form when an ‘event’ occurs, for example, if the content of a form field changes, or a form loads, or just prior to a document being assembled.

Creating a function

You can create and save functions as the value of a variable, i.e. the whole of the function is stored in the variable. The variable effectively becomes the ‘name’ of the function. You can then call the function using this variable/name and a pair of brackets. This is also called ‘invoking’ the function.

To create a function called ‘add’, use the ‘function’ keyword. You then list the ‘arguments’ in brackets, and then supply a block that contains the function’s code.

Here’s a function that adds two numbers:

var add = function (a, b) {
return a + b;
};

Here ‘a’ and ‘b’ are the function’s parameters, and the value it returns is signified by the ‘return’ keyword. The return keyword also stops execution of the code in the function; nothing after it will be run.

To call the ‘add’ function and store the result in the variable ‘result’:

var result = add(1, 2);

This script calls ‘add’ with the arguments 1 and 2, which, inside ‘add’, become the values of the variables ‘a’ and ‘b’. The variable ‘result’ has now been created with a value of 3.

For larger, less repeatable blocks of script we often use the following syntax when creating the function:

function fnName(arguments) {
	//Insert script here
}

Where fnName is the name of the function, and ‘arguments’ is a list of the arguments or parameters that the function takes (such as ‘a, b’ in the previous example). Below is an example of a function created using this syntax which uses our ‘add’ function created previously.

function valueAdd() {
var a = parseInt(Form.data.Field_Name_A_txt);
var b = parseInt(Form.data.Field_Name_B_txt);
var result = add(a, b);
$(form).setVal('Field_Name_R_scr', result);
}

This function, ‘valueAdd()’, will take the integer values of ‘Field_Name_A_txt’ and ‘Field_Name_B_txt’ and add them together using our repeatable function saved to the variable ‘add’. It will then write that value to the field ‘Field_Name_R_scr’, whenever valueAdd() is run.

Running a function on a form

It is a good design principle to place functions in the Form Script Editor, and then call the functions when the input fields change.

For example placing the script caller 'valueAdd();' inside the following triggers for Field_Name_A_txt and Field_Name_B_txt will ensure that Field_Name_R_scr will update whenever one of these two fields changes.

$('.formio-component-Field_Name_A_txt').find('input').change(function() {
 valueAdd();
});
$('.formio-component-Field_Name_B_txt').find('input').change(function() {
 valueAdd();
});

Functions that run on System Events, like loading a form, or assembling a document, can also be called from the Form Script editor.

If you have any trouble with this script, you can submit a request at the top of this page.