You can configure a Field to calculate its value automatically. For certain Fields, this approach is preferable to a user manually typing a value, as it eliminates the chance for human error and does less work for the user.
For example, let’s say that an app contains the following two Fields: contract_expiration_date and days_until_contract_expiration. When a user manually enters a value into the first Field, a Field Calculation could automatically determine and populate the second Field. In this example, the Field Calculation performs basic math to determine the difference in days between the current date (i.e., today) and the date entered into contract_expiration_date.
Before We Start ...
This tutorial will assume you understand the following concepts:
Let's Get Started!
In this tutorial, we’ll create a Field Calculation that outputs a total cost based on the quantity of an item a requester provides. We’ll assume the item has a fixed price.
1. Create Your Fields
Navigate to the Fields section of the Wizard.
Let’s create two Fields:
- A Field named quantity that has a Type of Integer.
- A Field named total that has a Type of Currency. Set this Field to only display on the View Page by changing the Display in property to View.
Since Fields aren’t calculated until a transaction is created or updated, it is best practice to set calculated Fields to only display on the View Page.
2. Open the Advanced Field Options
To calculate a Field, we'll need to add some Liquid to the Field whose value will be calculated, in this example, our total Field.
To do this, select your Field and open its Advanced Properties tab.
3. Configure the Calculation
Select the Calculated checkbox, then select Liquid from the Calculation Type dropdown.
Under Script, provide a Liquid expression to calculate your value. In this example, we’ll use the following Liquid, where 100 is the cost of the item:
{{ quantity | times:100 }} The Liquid shown above essentially says, “Take the quantity of the item provided by the requester and multiply that number by the price of the item.”
New to Liquid? Check out our Crash Course on Liquid tutorial. Focus on how to write an expression that provides an output.
Update your app to save your work.
Check Out Your Work
Congrats! You’ve created your first Field Calculation! Create a Record to test it out. With this example configured, the total Field on a Record’s View Page should calculate a value based on the value entered in the quantity Field at launch.
Fields Calculations can be used in Onit to enhance an App in many different ways. Below are a few more use-case examples to get you thinking about what else you can do with a Field Calculation:
- Create unique identifiers for Records by coupling Field values together.
- Pull out information from Records that would otherwise not be accessible for filtering on the Dashboard. (E.g., participants with a specific Role, a part of a Field’s value such as just the year in a Date Field, etc.)
- Store values from a parent App in a child App.
Pretty cool stuff!
Gotchas
- Field Calculations are only run when a transaction is created or updated or a Business Rule fires them. For this reason, it is recommended that Field Calculations are only displayed on an app’s View Page and are hidden on the Launch Page. If you need a Field to calculate a value in real time, we recommend using a UI Action.
- Avoid creating a Field Calculation that depends on the value produced by a separate Field Calculation, as you cannot ensure the value will be calculated in time for the dependent Field Calculation to utilize.