Lesson 3. Writing an OnFieldChange ruleset

Updated jordan.diamante 2024-01-15

In this lesson, we will cover the creation and editing of a ruleset for the OnFieldChange event.

OnFieldChange is invoked whenever there is a field that is changed in value or is clicked, eg a textbox has its text changed. This allows us to implement changes to the document/form based on changes of a field.

Step 1. Set up the new Ruleset

• Open the Ruleset Editor for a new Ruleset

https://your-formbird/form/224bc62858d73ce57a9cb85e

• Set the name of the RuleSet : Acme Rental Car - OnFieldChange

• Group can be set to acme, or your organisation name

• Save your new ruleset.

The script pane will show the following:

{
#include "JayRule Ruleset Overlay JS",

    ruleset : {
        name : 'Acme Rental Car - OnFieldChange',

        ruleInitialise : {
            ruleCondition : true,

            ruleAction : function(ntf) {
            }
        }
    }
}

• Link this ruleset to the "Rental Car" template, event "OnFieldChange", using the techniques described in Lesson 1

Step 2: Responding to the "Set to Now" button

In our template, we have a button next to the Last Rented Date field, captioned "Set to Now", named "buttonSetLRDNow". The intent of this button is to set the Last Rented Date to the current date/time.

To do this, we create a rule that runs only when that button is clicked.

• Add a new rule called "ruleSetLRDNow" to your ruleset, below "ruleInitialise".
• For the ruleCondition function, add the following:

ruleCondition : { 
    fieldChanged : 'buttonSetLRDNow'
}

ntf.context.fieldChanged contains the name of the field that triggered the OnFieldChange event.

• For the ruleAction, add the following:

ruleAction : function(ntf) { 
    ntf.document.lastRentedDate = new Date();
}

Your ruleset should look like the following:

{
#include "JayRule Ruleset Overlay JS",

    ruleset : {
        name : 'Acme Rental Car - OnFieldChange',

        ruleInitialise : {
            ruleCondition : true,

            ruleAction : function(ntf) {
            }
        },

        ruleSetLRDNow : {
            ruleCondition : { 
                fieldChanged : 'buttonSetLRDNow'
            },

            ruleAction : function(ntf) { 
                ntf.document.lastRentedDate = new Date();
            }
        }
    }
}

• Save the ruleset

Step 3. Testing

• Open a new or existing Rental Car document.
• Click the button "Set to Now".

• The field "Last Rented Date" should change to the current date/time.

Step 4. Showing the Reason Decommissioned field

In this task, we want the field "Reason Decommissioned" to be made visible when the user enters a date for "Decommissioned Date".

• Open your ruleset "Acme Rental Car - OnFieldChange"
• Add a new rule called "ruleShowReasonDecommissioned"
• Add the following for ruleCondition:

ruleCondition : { 
    fieldChanged : 'decommissionedDate'
}

• Add the following for ruleAction:

ruleAction : function(ntf) { 
    var ft3 = ntf.scope;
    // if decommissioned date is set, set flag true, else false
    var flag = !!ntf.document.decommissionedDate;

    ft3.showField('reasonDecommissioned', flag);
}

This acts both ways, to show the target field if the source field is set to a date, and to hide it if the source field is cleared of its value.

The first line of the ruleAction above makes use of javascript's ! operator.

Basically it's a quick shorthand way of coding the following:

var flag;
if (ntf.document.decommissionedDate) {
    flag = true;
}
else {
     flag = false;
}

That in itself takes advantage of Javascript's "ifness" of objects, ie if the object is not null or undefined (or empty), the "if" statement returns true, otherwise the "else" statement takes place.

Your full ruleset should look as follows:

{
#include "JayRule Ruleset Overlay JS",

    ruleset : {
        name : 'Acme Rental Car - OnFieldChange',

        ruleInitialise : {
            ruleCondition : true,

            ruleAction : function(ntf) {
            }
        },

        ruleSetLRDNow : {
            ruleCondition : { 
                fieldChanged : 'buttonSetLRDNow'
            },

            ruleAction : function(ntf) { 
                ntf.document.lastRentedDate = new Date();
            }
        },

        ruleShowReasonDecommissioned : {
            ruleCondition : {
                fieldChanged : 'decommissionedDate'
            },

            ruleAction : function(ntf) { 
                var ft3 = ntf.scope;

                // if decommissioned date is set, set flag true, else false
                var flag = !!ntf.document.decommissionedDate;

                ft3.showField('reasonDecommissioned', flag);
            }
        }
    }
}

• Save your ruleset.

Step 5. Testing

• Open a new or existing Acme Car Rental document. If already open, reload the page to refresh the ruleset in memory.
• Select a date in the "Decommissioned Date" field.

• The field "Reason Decommissioned" should be displayed.

• Clear the date in "Decommissioned Date"

• The field "Reason Decommissioned" should vanish.

If the above is true, you have successfully created and executed your OnFieldChange ruleset!

Step 6 (Optional): Execute the Ruleset Based on "triggeredOn"

You can configure your ruleset to execute only when specific fields are changed. To achieve this:

• Open your template where you linked Acme Rental Car - OnFieldChange using template editor.
• Add a triggeredOn field to related document item and set the fields. Example:

 "onFieldChangeClientRuleRel": [
        {
            "documentId": "d8bc8340-c0b7-11e6-9eea-13b66331d97f",
            "name": "Acme Rental Car - OnFieldChange",
            "triggeredOn": ["buttonSetLRDNow", "decommissionedDate"]
        }
 ]

Lesson Items covered

• Establishing an OnFieldChange ruleset
• Responding to button clicks to change form content.
• Responding to field changes to change form content visibility.
• Use of ntf.context properties.