Form rules
| Rules and examples |
|---|
|
| Warning | Work in progress! We are in the process of updating the information on this page. Subject to change. |
Form is a screen in the application that contains numerous fields which either hold or await the data. It is a tool that enables system administrators to represent the database data and collect user data in a user-friendly way. Default behavior of an entity form can be changed using form rules, which control form events and provide actions that can take place if one of the events occurs.
Form lifecycle and form events
The default behavior of an entity form can be changed using form rules, which control form events and provide actions that can take place if one of the events occurs. A form event is an action of a user or code that invokes a response action from the entity form. The main three events are:
- Load: Occurs before the form is displayed on the screen. It occurs immediately after the user chooses to open an entity record from the List view screen. On Load rule connected to a Load event is activated on Load itself.
- Change: Occurs after the form has been displayed on the screen and any change on it is recognized. On Change rule connected to a Change event is activated on Change and Load events as well.
- Save: Occurs after the form has been displayed on the screen, the user hits the save button, and the form is trying to get closed (off the screen). The On Save rule connected to a Save event is activated on Save itself.
| Note | After the form is displayed on the screen, a Change event occurs as loading data into each field on the entity form is considered a change of those fields. Therefore, On Change rules are triggered. |
Use On Load for initialization
On Load rules are the best option when it comes to handling initializations. Users must wait for the On Load rule to be fully executed before seeing the form in the desired format. By setting up only the initialization actions in the On Load rule, its execution time is minimal.
Set up in On Load rule:
- Hide/show fields
- Enable/disable fields
- Hide/show tabs
- Assign styles to fields or the entire form
- Automatically assign values to fields, e.g. date & time, location, company number, etc.
Do not set up in OnLoad rule:
- Hide/show/enable/disable fields and tabs dynamically. The actions related to changes on a form while working with it are better set up in the On Change rule.
Using the “otherwise if” part of the rule
One of the most common mistakes when setting up form rules is skipping the “otherwise if” part of the rule.
Keep in mind that the form is reused while the application is running. What does this mean? If you set a style of a field by rule, without defining the “otherwise if” part, the style of the field on the form is saved. Afterwards, when you open a new form of the same entity, it simply uses the style you saved on the last one. Without using the “otherwise if” part of the rule to change the style back, the form is simply reused.
Example: Change the color of the form field (city)
For the Load event create an OnLoad rule which checks if the field contains data. If it does, you assign “greyFieldStyle” to that field. You don’t specify any “otherwise if” part, because the rule seems straightforward.
You open the form for the first time and its background is white, because the city is not filled. So we add a value to the City field and save the form. When re-opening the form, the city field is grey because it already contains data.
Then, you add a new record and open a new form. What happens? The City field is grey even though it doesn’t contain any data.
.PNG)
That’s because there is no “otherwise if” part of the rule specified, which would change the style back to white color if the field is empty. The rule itself is not reset every time a form is closed. That is why you have to set On Load to change the City field color back to white, if it does not contain data (in this case set the style back to Normal).
On Change rule should be handled by IsLoaded and ChangedItem properties
Some of the most common questions from the users are:
- "Why are On Change rules triggered when loading the form?"
- "Why is the On Change rule triggered repeatedly?"
In most cases, this is because the IsLoaded and ChangeItem properties are not included or applied incorrectly.
To control the execution of On Change rules, we highly recommend using the IsLoaded and ChangedItem properties.
- IsLoaded property checks whether the form is fully loaded and visible on the screen with all the values assigned. (During the load event, each field on the form is populated with data. This change, even though it took place during loading, triggers the On Change rule.)
- ChangedItem property checks whether the change on the form occurs on the specified field. (If not specified which field is to be changed, any change on the form will execute the On Change rule.)
Example: ChangedItem and IsLoaded use case
We want to show a text warning to the users after they delete data from the City field and leave it empty.
Two situations occur with this rule set:
- When opening a new form: Since we didn’t use the ChangedItem property to specify which field change should the app check before showing the warning text, the warning is shown for every single field loaded on the form. So if you have 20 fields on the form and use the rule above, you will see the “City is empty!” message pop up 20 times – incorrect behavior.
- When opening an existing form with the City field filled in: The message doesn’t show up after load and after deleting the data from the City field, the message shows up as expected. However, when modifying other fields on the form, the message also shows up. This happens because we did not specify which field the rule should check for changes before showing the error message. When the application recognizes a change on the form, and the City field is empty, the message will be shown – incorrect behavior.
The correct rule would be:
We are using:
| If | IsLoaded | Equals | True |
- we want the rule to be triggered only after the form is loaded
| If | ChangedItem | Equals | address1_city |
- we want the rule to be triggered only if the City field was changed
| If | Entity.address_city | Does Not Contain Data |
- we want to check whether the city field contains data after the user changed the value of the field.
Do not load (fetch) entity in Can Execute rule (command rule), use OnChange rule instead
Entity fetch is an asynchronous operation. That means that we don’t know precisely when the result will return – the fetch. While an asynchronous operation triggered by an On Change rule runs, the user sees a loading screen in the application since the rule waits for the result of the operation. However, when calling an asynchronous operation (fetch) in the Can Execute rule, the rule itself could be executed before it gets the asynchronous operation result and could cause incorrect behavior of the command in the application.