Articles on: Developers
This article is also available in:

Setting up required and visibility of fields by script?

Visibility by script allows you to set dynamic visibilities for form fields. You can define if certain fields should be required, editable, read-only or hidden, based on the value of another field or on a decision made.

Available functions

Flokzu’s API offers the following functions to use in scripts:

Flokzu.setHidden( [[field]] ); //Hides a field
Flokzu.setRequired( [[field]] ); //Sets a certain field as required
Flokzu.setEditable( [[field]] ); //Sets a certain field as editable
Flokzu.setReadOnly([[field]]): //Sets a certain field as read-only
Flokzu.setFieldValue( [[field]] , "value" ); //Overwrites a field value to the specified value
Flokzu.getFieldValue( [[field]] ); //Obtains a field’s value
Flokzu.getAllColumnValues( [[field::column]] ); //Obtains all the values of a column from a table field
Flokzu.onChange( [[field]] , function ); //When a field changes, function is executed
Flokzu.onTableChange( [[field::column]], function ); //When a column from a table changes, function is executed
Flokzu.onInit(function); //Function is executed when the form is initiated (i.e. when the page loads)
Flokzu.onAction(function) //Function is executed when a button is clicked (i.e. a decision is made). The value of the chosen button is stored on the second parameter.
Flokzu.error( [[field]] , "message" ); //If the field generates an error, the corresponding message is shown.
Flokzu.currentUser(); //Returns the email address of the logged in user
Flokzu.getFieldByName( "fieldName" ); //​Returns the field id from its name

Field names and button names must be written exactly as they are, respecting the capital letters, lower case letters, spaces and special characters you have used.

Methodology for scripts development

With the exception of the API’s functions and the special manner of referencing fields using [[]], the rest of the code is JavaScript and it follows the Javascript development rules.

A visibility script is basically a group of functions that determines under which conditions the visibility of a field should be modified.
In addition, each function should be subscribed to the field it wants to ‘listen’ to, so that when the field value changes, the function executes automatically. If a function must be executed immediately when a process instance is opened (e.g. to hide a field), it will also need to be subscribed to the method Flokzu.onInit.

RULE: In order to modify the field visibility dynamically, the field whose visibility will change must have been set as editable in the process (for the task that has the script). On the contrary, when the field is modified, the visibility by script will not behave properly.

Script structure

1) Write all necessary functions to set the dynamic visibility.
To define a function you must write:
function functionName(){ ... function’s content ... }

2) Subscribe all the functions to corresponding fields and/or the Start Event. Subscriptions must be below the definition of the function.
//Subscription to a field to execute a function
Flokzu.subscribe( [[fieldName]] , functionName );

//Subscription to the Start Event
Flokzu.onInit( functionName );

Where to place the script?

1) While creating or editing a process, clic on Visibility settings and Scripts button on the form tab.

2) Once in the visibility pop-up, click on Scripts tab and then select the task in which you want the script to be executed.
Finally, place the script there and Flokzu will make an evaluation, if everything is ok you'll be able to Continue if not, Flokzu will tell you where's the error.

Scripts can be applied to the Start Event, Middle Tasks of a process or even, End States.

- Master script - The script defined in that option would be embed in all active tasks (not end states). This is totally useful when you have a behavior that must be applied in all tasks.

Example according to a field value

In this example, we have a manual combo field called ‘Marital Status’ and when a user selects the option ‘Other’, the field ‘Please specify’ will be shown as required. On the contrary, this field will be hidden.

The first step is to define the following function:

//Function maritalStatus to evaluate the content of the field ‘Marital Status’
function maritalStatus(){
	if ( Flokzu.getFieldValue( [[Marital Status]] ) ==  ‘Other’ ){
		//We establish the field as required
		Flokzu.setRequired( [[Please specify]] );
	} else {
		// In any other case, this field will be hidden
		Flokzu.setHidden( [[Please specify]] );

Then, it is necessary to subscribe the function to the corresponding field:

//We must ‘listen’ to the field ‘Marital Status’ and when it changes, the function must be executed.
Flokzu.onChange( [[Marital Status]] , maritalStatus);

//Given that the field ‘Marital Status’ will be editable (by RULE), we want that immediately after the process instance is opened, it remains hidden if the value is not “Other”. For this reason, the function must be subscribed to the Start Event.
Flokzu.onInit( maritalStatus );

Final result

Example according to selected button

Sometimes, the visibility of a field will depend on the decision made. For example, if a request is rejected, we can establish the field “Reason of rejection” to be required. On the contrary, if the request is approved, this field will be hidden. For these cases, the defined function should include 2 parameters:

function test(msg,button){
   if(button== "Reject"){
		Flokzu.setRequired([[Reason of rejection]]);
   	Flokzu.setHidden([[Reason of rejection]]);


### Example getAllColumnValues

To iterate through all elements in a column you can do the following:

function funcX(msg, data){   
	$(Flokzu.getAllColumnValues( [[field::column]] )).each( 
			alert( $(this).attr('value') ); // Launches an alert per each value.

Flokzu.onTableChange( [[field::column]] , funcX );

Updated on: 14/08/2023

Was this article helpful?

Share your feedback


Thank you!