How to trigger script to run based on system events

Purpose of triggering script based on system events

After you have designed and published your Forms, users will open them up and interact with them, i.e. they will use the forms to make documents.

If you have written Rules and Scripts for your Forms, then you want these to run when the user does something that relates to those Rules and Scripts. For example, if you want to show ‘Field 2’ only if the user selects ‘yes’ for ‘Field 1’, then you want a change to the Field 1 to trigger the showing or hiding of Field 2. This is a simple ‘event’, i.e. selecting yes or no for Field 1. However, our platform deals with many, many events.

As your users interact with your Forms they will do a number of things that are recognised as a ‘trigger event’. For example, when the user first opens a Form, this triggers the platform to load the Form and display it for the user. If the user opened the Form with existing data, the next thing that the platform will do is load that data into the Form.

You can hook into some of these system events to run various scripts when these important events happen. 

The following functions will trigger Script to run when certain events occur. These functions do not need to be called (triggered) separately, they are triggered by the system itself. Otherwise, they are exactly the same as regular functions and all take the following form:

window.SystemEventName = function() {
	//The script inside the function will be run when the SystemEventName event occurs
}

Where "SystemEventName" is replaced by one of the functions listed below

On form load

InitFormData

The window.InitFormData function will run after the Form layout first loads.

We have an article on this here, but the most important things to note are that the function requires a parameter to refer to the current formdata, and this must be returned so that the data can load into the form.

For example:

window.InitFormData = function(formdata) {
    //Some function or script you have created to modify the initial formdata - eg:
    ChangeLoadedData(formdata);
    return formdata;
}

On form save or submission

BeforeFormSave

The window.BeforeFormSave function will be triggered each time the form is saved; whether by a press of the Save button, or automatically when auto-save is enabled.

This event occurs before the form data is saved, allowing you to potentially modify that data before it turns up in the record. This can be useful for modifying data that the user does not need to see. You can also use this event to run apps to send email notifications, by hooking into our API.

The function to trigger script on this event does not need a parameter and does not need to have a return value for data to be updated. You should always use Form.data[FieldName] to reference or update data within this function.

For example:

window.BeforeFormSave = function() {
   ChangeSaveData(); //Neither the BeforeFormSave, or an sub functions need to use a parameter
   Form.data.Form_Was_Saved_scr = "true"; //An example of directly changing the form data
};

BeforeFormSubmit

The window.BeforeFormSubmit function will be triggered each time the form is submitted.

This event occurs before the form data is submitted, allowing you to modify the data before it is assembled in the document.

The function to trigger script on this event requires a parameter to define the data and for that parameter to be returned in order for the changes to take effect. The parameter would take the place of 'Form' in the syntax for the BeforeFormSave function's data modification scripts.

For example:

window.BeforeFormSubmit = function(formdata) {
   ChangeSaveData(formdata); //The BeforeFormSubmit and sub functions need to use a parameter
   formdata.data.Form_Submitted_scr = 'true'; //an example of directly changing the form data
   return formdata
};

AfterFormSubmit

The window.AfterFormSubmit function is triggered after the form's data has been sent to the assembly engine and the data for the record has been saved as part of the submission process.

This event allows you to trigger any script that will modify the page after the data has been successfully submitted. You will not be able to modify the data in any meaningful way here.

An example of how this might be useful is if you want to manually redirect the user away from the form after submission, or have an external workflow you want to use.

The function to trigger script on this event uses the same no-parameter syntax as the BeforeFormSave function. For example:

window.AfterFormSubmit = function() {
   //Redirect
   window.location.replace('https://syntaq.zendesk.com');
};