Lesson 1. Our First Ruleset
Updated pdexter 2022-12-19
In this lesson, we create a template, and a ruleset to be run for its OnLoad event.
Step 1. Preparation
To prepare, we are going to create an "Car Rental application" consisting of a single template. For the purposes of this exercise, the organisation we are making the application for is called "Acme", though you can substitute any other organisation name.
If you are doing this along with other people, or someone else has done this on your system, you may want to create a different organisation name based on your name, eg "SmithCorp", instead of "Acme", so as not to clash with those pre-existing templates.
An understanding of Template creation is necessary here. For more details see 1. Getting Started/Templates
- Create a template for "Rental Car" (see below for ready made script)
- Set its appTags to ["acme", "rentalCar"] so we can isolate it later.
- Add text fields "carMake", "carModel", "registration", "createdByUser"
- Add number fields "odometer"
- Add date fields "openedDate", "lastRentedDate", "decommissionedDate"
- Add text field "reasonDecommissioned"
- Add a button component beside the lastRentedDate and should have a caption Set to Now.
NB: do not set any fields as mandatory:true or enabled:false; we want to exercise doing it by ruleset.
You can copy and paste this template script (below the ellipsis .....) to your own template editor to create your template; remember to change organisation name where required.
{
...
"systemHeader": {
"templateId": "74746c80-8378-11e6-99b1-71ee944cf59f",
"systemType": "template"
}
"formColor": "AliceBlue",
"appTags": [
"acme",
"rentalCar"
],
"components": [
{
"name": "appTags",
"componentName": "sc-static-value",
"value": [
"acme",
"rentalCar"
],
"visible": false
},
{
"componentName": "sc-static-html",
"fullWidth": true,
"html": "<h3>Acme Rental Car</h3><hr/>"
},
{
"name": "carMake",
"componentName": "sc-text-box",
"label": "Make"
},
{
"name": "carModel",
"componentName": "sc-text-box",
"label": "Model"
},
{
"componentName": "sc-text-box",
"label": "Registration",
"name": "registration"
},
{
"componentName": "sc-text-box",
"label": "Created By",
"name": "createdByUser"
},
{
"componentName": "sc-static-html",
"fullWidth": true,
"html": "<hr/>"
},
{
"componentName": "sc-numeric",
"label": "Odometer Reading",
"name": "odometer"
},
{
"componentName": "sc-static-html",
"html": "<hr/>",
"fullWidth": true
},
{
"name": "openedDate",
"componentName": "sc-date-time",
"label": "Opened"
},
{
"name": "lastRentedDate",
"componentName": "sc-date-time",
"label": "Last Rented"
},
{
"componentName": "sc-button",
"caption": "Set to Now",
"name": "buttonSetLRDNow"
},
{
"componentName": "sc-static-html",
"html": "<hr/>",
"fullWidth": true
},
{
"name": "decommissionedDate",
"componentName": "sc-date-time",
"label": "Decommissioned"
},
{
"name": "reasonDecommissioned",
"componentName": "sc-text-box",
"label": "Reason Decommissioned"
}
],
"name": "Acme Rental Car",
"summaryNameRule": "Acme Rental Car - {{carMake}} {{carModel}} {{registration}}"
}
Step 2. Create the Ruleset for OnLoad
-
Open the Ruleset Editor for a new Ruleset
https://your-formbird/form/224bc62858d73ce57a9cb85e
-
Set the name of the RuleSet : Acme Rental Car - OnLoad
-
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 - OnLoad',
ruleInitialise : {
ruleCondition : true,
ruleAction : function(ntf) {
}
}
}
}
The new ruleset page comes with a ready made ruleset scripted, including the one rule "ruleInitialise" as above.
This rule doesn't do anything for the moment, it is provided to contain any initialisation logic required for the ruleset as a whole. We may need to set some of our own logic there in future, so leave as is for now.
Now to add some rules
- Add a rule called "ruleSetMainFieldStates", as written below, below the existing rule "ruleInitialise" (NB : You will need to add a comma after the ruleInitialise block).
ruleSetMainFieldStates : {
ruleCondition : true,
ruleAction : function(ntf) {
}
}
A rule is a JSON object within our ruleset object, defined with two function properties, a ruleCondition and a ruleAction. The ruleCondition defines whether the rule runs, and the ruleAction contains the action to perform if ruleCondition is met.
All rule objects must be named with the prefix "rule".
- Set carMake and carModel to mandatory by adding this snippet inside the ruleAction function block:
ft3.mandateField(‘carMake’, true);
ft3.mandateField(‘carModel’, true);
ft3 is a global object which contains functions used within rulesets to manipulate fields and documents.
It should be initialised at the top of any function block as:
var ft3 = ntf.scope;
- Disable the createdByUser field to make it read-only by adding this snippet:
ft3.enableField(‘createdByUser’, false);
- Hide the reasonDecommissioned field by adding this snippet:
ft3.showField(‘reasonDecommissioned’, false);
The entire ruleset script should look like:
{
#include "JayRule Ruleset Overlay JS",
ruleset : {
name : 'Acme Rental Car - OnLoad',
ruleInitialise : {
ruleCondition : true,
ruleAction : function(ntf) {
}
},
ruleSetMainFieldStates : {
ruleCondition : true,
ruleAction : function(ntf) {
var ft3 = ntf.scope;
ft3.mandateField('carMake', true);
ft3.mandateField('carModel', true);
ft3.enableField('createdByUser', false);
ft3.showField('reasonDecommissioned', false);
}
}
}
}
Right now, your ruleset won't do anything, because it is not linked to the template. We'll link to the template in the next section.
Step 3. Link your ruleset to the template
In order for a ruleset to run, it needs to be attached to a template as a particular event handler.
For this example, the template must hold a reference to this ruleset for its OnLoad event, for it to take effect.
For detail, see 5.Rulesets/Relationship between Rulesets & Templates
There are a couple of ways to do this.
Method 1 - Link from the Ruleset
- Open the ruleset you created in Step 2.
- Click the "Link to Templates" button (or similar checkbox on some older versions of the editor).
- The "Link to Templates" section should be revealed.
- In the "Templates" field, type "acme rental" and select your template "Acme Rental Car" (or similar).
- In the "Event" field, select "OnLoad"
- Click the button "Link Templates"
- Reload the ruleset document.
- The display field "Templates linked to this ruleset" now displays the "Acme Rental Car" template name.
- Check that the template opens with fields set as in the Check Results section below.
Method 2. Link from the Template
- Open a new document of your template in a browser window.
- Append the following to its url in the address bar /abb10be0-b9dc-11e7-8013-1f0b88022708
- This will display the Ruleset Linker overlay on the Template, showing the linkages.
- In the field "OnLoad (client)", type "acme rental". The name "Acme Rental Car - OnLoad" should appear. Select it.
- Save the template.
- Check that the template opens with fields set as in the Check Results section below.
Method 3. Edit the Template
If the above methods for some reason do not work, this is the bare bones means of implementing the link.
- Copy the documentId of your ruleset "Acme Rental Car - OnLoad"
- Open your template with the Template Editor
- Edit or add the following property to the template script (replacing the documentId with your own for the ruleset):
"onLoadClientRuleRel": [
{
"documentId": "0a812c40-706b-11e9-9600-45edbd28214b",
"name": "Acme Rental Car - OnLoad"
}
]
- Check that the template opens with fields set as in the Check Results section below.
Check Results
- Open a new Car Rental document (navigate to the template url).
-
The fields Make and Model are mandatory (coloured red)
-
The field Created By is disabled.
-
The field Reason Decommissioned does not appear.
If the above is true, you have successfully created and implemented your first ruleset!
Lesson Items covered
- Creating a new ruleset
- Writing a new rule
- Setting of fields with showField, enableField, mandateField
- Attaching the ruleset to a template event