Overview

This page contains information about how to use the formula builder within the Calculated control and conditional display areas of nFORM.

1 Overview
2 Formula Essentials
- 2.1 Operators
3 Formula Building Techniques
- 3.1 Performing Null Checks
- 3.2 Using the select() Function to Select Values Based on Cases
- 3.3 Utilizing the LOOKUP() Function
- 3.4 Optimization Strategies
  - 3.4.1 Rounding Numbers
  - 3.4.2 Contact Phone Property Access
  - 3.4.3 Formatting Dates
  - 3.4.4 Date Comparison
  - 3.4.5 Extracting Substrings
  - 3.4.6 Data Type Conversion
  - 3.4.7 Time/Date Duration Calculation
- 3.5 Simple Conditional Formula Examples
- 3.6 Advance Conditional Formula Examples
- 3.7 Additional Resources

Formula Essentials

Introduction to Formulas

Formulas are powerful tools within Windsor applications that enable you to automate tasks, perform calculations, and manipulate data. They are essential for creating dynamic and interactive forms that adapt to user input and provide meaningful insights.

Formula Syntax

Formula syntax is the structure and rules that govern how formulas are written and interpreted. It consists of elements such as operators, operands, and functions.

Operators

Operators are symbols that perform operations on operands. Common operators include:

(Click an operator to be taken to an example) (ANCHOR)

Addition (+)
Subtraction (-)
Multiplication (*)
Division (/)
Equality (==)
Inequality (!=)
Less than (<)
Greater than (>)
Less than or equal to (<=)
Greater than or equal to (>=)
Logical AND (&&)
Logical OR (||) (jump to example)
Logical NOT (!)
Ternary Operator ( ? )

Formula Building Techniques

Performing Null Checks

Null checks ensure that formulas handle missing or empty values appropriately. Common functions for null checks include:

ISNULL(): Checks if a value is null.
ISBLANK(): Checks if a value is null or an empty string.
COALESCE(): Replaces a null value with a specified alternative value.

Using the select() Function to Select Values Based on Cases

Select() Function Syntax

The select() function is used to select a value from a set of possible values based on a given case. It takes three arguments:

str(VARIABLE): The variable that holds the value to be evaluated.
case1: An object containing a case identifier and a corresponding value.
case2: An object containing a case identifier and a corresponding value.
(Optional) caseN: Additional case objects can be added to the function for more possible values.

Example:

select(str(`FEE_CATEGORY`),
  {case: "1", value: "PETROL BULK STORAGE REG 1,101=<2K GAL"},
  {case: "2", value: "PETROL BULK STORAGE REG 2,001=<4,999 GAL"},
  {case: "3", value: "PETROL BULK STORAGE REG 5K=< 399,999 GAL"})

Explanation:

The select() function evaluates the value of the variable FEE_CATEGORY.
If the value of FEE_CATEGORY matches the case identifier in any of the case objects, the corresponding value from that case object is returned.
If the value of FEE_CATEGORY does not match any of the case identifiers, the function returns an empty string.

Utilizing the LOOKUP() Function

The LOOKUP() function retrieves a value from a specified table based on a given identifier. It's commonly used for data lookup and retrieval.

Optimization Strategies

Optimizing formulas enhances their performance and efficiency. Here are some optimization strategies:

Use CONTAINS() instead of multiple TAG checks: The CONTAINS() function checks if a value exists within a list, while multiple TAG checks involve checking each tag individually. CONTAINS() is generally more efficient.

Rounding Numbers

Rounding involves adjusting numbers to a desired precision. Common rounding functions include:

ROUND(): Rounds a number to the nearest specified number of decimal places.
ROUNDUP(): Rounds a number up to the nearest specified number of decimal places.
ROUNDDOWN(): Rounds a number down to the nearest specified number of decimal places.

Contact Phone Property Access

Access contact phone-related properties using the new array properties: phoneNumber, phoneType, and phoneExtension. You can now access these properties directly without using array notation.

For example, instead of CONTACT.phoneNumber[0], you can use CONTACT.phoneNumber or first(CONTACT.phoneNumber).

To display a "home" phone number, use the following formula:

lookup(`CONTACT`.phoneType=='Home', `CONTACT`.phoneNumber)

The phones property is deprecated. Replace any references to phones with phoneNumber, phoneType, or phoneExtension in your formulas.

Formatting Dates

Date formats control how dates are displayed. The FORMAT() function enables formatting dates according to various styles.

Date Comparison

Date comparison involves evaluating relationships between dates. Common functions for date comparison include:

DATEDIFF(): Calculates the difference between two dates. (jump to example)
DATE(): Extracts the date component from a value.
TODAY(): Returns the current date.

Extracting Substrings

Extracting substrings involves retrieving specific portions of text strings. The LEFT() and RIGHT() functions extract substrings from the left and right ends of a string, respectively.

Data Type Conversion

Data type conversion involves changing the data type of a value. The NUMS() and DATES() functions convert values to numbers and dates, respectively.

This guide provides a foundational understanding of formulas in Windsor applications. For more in-depth explanations and advanced topics, please consult additional resources or seek guidance from experienced Windsor users.

Time/Date Duration Calculation

For Days:

// Days
floor(dateDiff(date(formatDate(`ANTICIP_STRT_DT`,'ddd MMM DD YYYY') + ' ' + formatDate(date(`ANTICP_STRT_TM`, true),'HH:mm:ss [GMT]ZZ'), true),date(formatDate(`ANTICIP_END_DT`,'ddd MMM DD YYYY') + ' ' + formatDate(date(`ANTICP_END_TM`, true),'HH:mm:ss [GMT]ZZ'), true),'hours')/24) + ' day(s)' + ' '

For Hours:

For Minutes:

Simple Conditional Formula Examples

Conditional formulas are powerful tools in Windsor applications that allow you to display different content based on certain conditions. They are like decision-making statements that evaluate whether a particular condition is true or false, and based on the outcome, they determine what information or action should, or should not, be displayed.

Question	Formula
Display when answer = Blue (The text selection is case sensitive)
Display when answer > 10 (num function converts the value to a number)
Display when answer = Yes
Display when answer = A Or D
Display when Question 1 = M OR Question 2 = X
Display when sum of Question 1 and Question 2 > 100 (num function converts the value to a number)
Display when the count of items >= 3
Display when the text contains the word “show” (toLowerCase converts the text to all lower case and then in this example compares to the lower case value “show”)
Display when checkbox is checked
Display when checkbox is not checked

Advance Conditional Formula Examples

Select Control Selection (Displayed Description) Exact Comparison Example

The following formula evaluates to True if the selected (and displayed) value in the SelectMenu field (Single or Multiple Select Control) is equal to "Yes". Note the ".description" selection to signify that the comparison will be performed on the displayed description, versus the hidden ID. If the hidden ID value needs to be referenced, ".id" can be specified.

`SelectMenu`.description == "Yes"

Select Control Selection (Displayed Description) If/Then Comparison Example

The following formula evaluates to True if the selected (and displayed) Pending Violations Select Control value is equal to "Yes", otherwise returns False.

iff(`PendingViolations`.description == "Yes", true, false)

Select Control Selection (Hidden ID) Exact Comparison Example

The following formula evaluates to True if the ID for the selected value in the SelectMenu field (Single or Multiple Select Control) is equal to "2".

`LinkedValue`.id == "2"

Select Control Selection (Displayed Description) Contains Comparison Example

The following formula evaluates to True if the selected (and displayed) value in the County (Single or Multiple Select Control) contains the text "Multnomah", "'Clackamas" or "Washington".

contains(`County`.description, 'Multnomah','Clackamas','Washington')

Simple Math (Multiplication) Example

The following formula multiplies BoxLength by BoxWidth to calculate area.

`BoxLength`*`BoxWidth`

Aggregation Function (Summarize) Across Repeating Sections Example

The following formula sums all the Tons values across all Repeaters in a Repeating Section.

sum(`RepeatingSection:Tons`)

Aggregation Function (Average) Across Repeating Sections Example

The following formula averages the Tons values across all Repeaters in a Repeating Section.

avg(`RepeatingSection:Tons`)

Return Cell Value from Advanced Table Based on Value in Another Cell

The following formula returns an [Emissions Value] value from a cell in an Advanced Table where another cell, on the same row, has a matching value [VOC name of Formaldehyde].

first(lookup(`Emissions_Table_Section:Emissions_Table`.AT_VOC_NAME == "Formaldehyde",`Emissions_Table_Section:Emissions_Table`.AT_Emissions_Value))

Return Cell Value from Repeater Based on Value in Another Field within Repeater

The following formula returns an [Emissions Value] value from a field in a Repeater where another field, on the same repeater, has a matching value [VOC name of Formaldehyde].

first(lookup(`Emissions_Repeater:VOC_NAME' == "Formaldehyde",`Emissions_Repeater:EMISSION_VALUE'))

Count Values Exceeding Limit in an Advanced Table

The following formula counts the number of rows in an Advanced Table where a [Emissions Value] value exceeds a limit (e.g., 10).

count(lookup(val(`Emissions_Table_Section:Emissions_Table`.AT_Emissions_Value) >

10,`Emissions_Table_Section:Emissions_Table`.AT_Emissions_Value))

Count Values Exceeding Limit in a Repeater

The following formula counts the number of records in a Repeater where a [Emissions Value] value exceeds a limit (e.g., 10).

count(lookup(val(`Emissions_Repeater_Section:RS_EMISSION_VALUE`) > 10, `Emissions_Repeater_Section:RS_EMISSION_VALUE`))

Calculating a Date Offset

If the current date is 5/25/2023, the formula below will return -3.

dateDiff(now(), '05/22/2023', "d")

Require a Specific Length for Zip Code or Number Control

The following example looks for a number 5 characters in length utilizing numbers 0-9.

^[0-9]{5}$

Additional Resources

nFORM Conditional Formula Examples

The form definition file for the form above is provided below (nFORM v4.17 format). It can be downloaded and deployed to a client environment using the nFORM Import Form option.

	File	Modified
Labels No labels Preview View	File nFORM Conditional Formulas Examples.export	Dec 18, 2023 by Logan Korn

Windsor Support

Syntax for Calculations and Conditional Display