The MVC Rules Manager was introduced to The Portal Connector in version 4.1 to replace the existing WebForms version. The main advantage to the MVC Rules Manager over the old one is that you can create multiple rules in a single widget instance instead of requiring multiple widgets as the WebForms version did. This results in faster form load times due to fewer widgets being loaded. Additionally, the preview of your rules in the designer is much easier to read and understand in the MVC version.
The TPC Rules manager widget allows you to add additional logical functionality to your form. It is able to detect when a specific action has occurred, for example; this widget is able to trigger when the user changes the value of a field. Some of the events and actions that the widget allow to trigger are listed below.
- Is Equal To
- Is Not Equal To
- Contains Data
- Does NOT Contain Data
- Window Loaded
- Document Ready
- Set Value
- Show Field
- Hide Field
- Toggle Field
- Enable Field
- Disable Field
- Make Required
- Make Optional
- Show Section
- Hide Section
- Toggle Section
- Run Script
With the above events and actions, you can create rules to perform common requirements. We will show how to implement the following requirements:
- Set default values
- Conditionally set fields to be required/optional
- Show/hide specific fields
- Show/hide any HTML element
In all examples, you start by building a form with all the fields needed and then adding a rules manager widget to the form. It is important that the Rules Manager widget is dropped inside the Form Layout widget (inside the blue box) otherwise it will not be able to identify fields in the form. The following will assume there is a form configured.
Set default values
The first common requirement is to fill in a default value in a field when a form first loads. This is common when a field is required and the value rarely changes from a default value. Pre-setting it reduces the number of fields the user needs to fill in speeding up data entry.
This example checks a field (numberofchildren) to see if it contains data, if not, it sets a default value of “0”
Conditionally set fields to be required/optional
Setting a field to be required or optional based on another field is another common requirement that can be satisfied by the Rules Manager.
This example shows how to set a field (childrensnames) to be optional when another field (numberofchildren) has a specific value (0).
Note: For the Rules Manager to set a field to be optional/required the “Client-Side Required” checkbox must be checked.
Show/hide specific fields or any HTML element
In the last example we set a field to be optional when a field is set to 0 and required when it is not. The rules manager can also hide the field so it isn’t available to be filled in. This additional requirement is common when you have an “other” option in a picklist or lookup widget.
In this example we will expand on the last example and show/hide the childrensnames field based on the numberofchildren field. Fields can also be toggled to their opposite state as well: hide when currently showing and show when currently hiding.
Show/Hide any HTML element
The last example makes sense if you need to hide a field or 2, but what if you want to hide more than 1 or something else on the page, such as instructional text?
In this example, a boolean field has been added to the form and 2 rules created to show/hide a block of text. This text block was given an id of instruction_text so the rule needs to address it like you would in CSS/jQuery. As with fields, elements can also be toggled to their opposite state as well: hide when currently showing and show when currently hiding.
This post only scratched the surface of what can be done with the rules manager. In addition to the above examples, you can also enable and disable fields in the form as well as run scripts. The ability to run scripts when triggered by a specific condition opens up all sorts of possibilities that are simply not possible out-of-the-box.
View the Documentation for the MVC Rules Manager
If you have any questions when configuring the MVC Rules Manager, feel free to email our Support Team at firstname.lastname@example.org or register for a Daily Q&A Session and we will be happy to assist.