Requirement 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 offers the following functions to use in scripts:

*Hide a field: Flokzu.setHidden([[field]])

*Set a field as required: Flokzu.setRequired([[field]])

*Set a field as editable: Flokzu.setEditable([[field]])

*Set a field as read-only: Flokzu.setReadOnly([[field]])

*Set a value to a field: Flokzu.setFieldValue([[field]], "value")

*Get the value of a field: Flokzu.getFieldValue([[field]])

*Get all the entries of a column in a table: Flokzu.getAllColumnValues([[field::column]])

*Execute a function when the value of a field is changed: Flokzu.onChange([[field]], function);

*Execute a function when an entry in a table field is changed: Flokzu.onTableChange([[field::column]], function);

*Execute a function when a process instance is opened: Flokzu.onInit(function);

*Execute a function when a user makes a decision (selected button): Flokzu.onAction(function); The decision taken is stored in the second parameter of the function.

*Display an error message on a field: Flokzu.error([[field]], "message");

*Get the email of the logged-in user: Flokzu.currentUser();

*Get the id of a field by its name: Flokzu.getFieldByName("fieldName");"

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]]);
  }
   else{	
   	Flokzu.setHidden([[Reason of rejection]]);
  }
}

Flokzu.onAction(test);

### Example getAllColumnValues

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

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

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

Updated on: 29/01/2024