Advanced Form Builder: Using Expressions

General

There are several attributes on form objects within the Advanced Form Builder (AFB) that support adding expressions. These expressions can control when to show or hide objects, when to display error messages, etc.

The major attributes that can utilize expressions are:

• Visible
• Ignored
• Enabled
• Required
• Custom Validations 
• Expression field

All of these attributes support manually entering expressions. Attributes like Visible, Ignored, Enabled, and Required also have the ability to use the Expression Builder dialog built into the AFB to assist with the syntax of the expression. To access this dialog, go to the desired attribute.

If the attribute is in the boolean mode (checkbox displayed), select the lightning icon to switch to the expression mode (will demonstrate for the Visible attribute).

This causes the field to be displayed where an expression can be manually input. It also results in the “hamburger” icon being displayed on the right side under the lightning icon. Selecting that hamburger icon opens the expression builder dialog.

There are multiple ways to construct the desired expression within this dialog. The first is to use the built in elements.

Building out Expression with the components in the dialog

Bringing focus to the field with the “Select variable…” placeholder opens a dropdown with the list of form objects all displayed by their Value attribute. As characters are typed into the field, available objects matching the characters are displayed.

Select the desired option from the list, or manually type in the desired Value attribute. Next select the desired operator for the expression from the dropdown that is displayed.

Next, enter the desired answer value into the field that is displayed.

The Expression text field populates with the proper syntax for the expression created from the three fields. 

If this is the complete desired expression, the Ok button can be selected, and this expression will be populated in the attribute from which this dialog was invoked.

If more is needed in the expression, the Add condition, Add expression, or Add group buttons can be used as applicable. 

Add Condition: 

Adds another line where a form object, operator, and answer can be defined. 

When multiple lines are added, the Match dropdown is also displayed, which can be used to specify whether All, Any, or None of the conditions should be matched. Changing this dropdown’s value impacts the operator used between each form object in the output Expression text field. Notice in the image above, when the Match dropdown is set to All, the two objects have an “&&” (AND) operator between them. This would require both conditions to be true for the overall expression to be evaluated as true. If the Match dropdown was changed to Any, the Expression text is updated to show the “||” (OR) operator, meaning only one condition would need to be true for the overall expression to be evaluated as true.

Then if the Match dropdown is changed to None, the Expression text field updates to add the “!” (NOT) character for the entire expression, meaning this expression will evaluate to true when ALL of the conditions are false.

Add Expression:

Adds another line where one or many conditions can be entered in manually. Also enables nested conditions as the entire expression line is wrapped with parenthesis. The operator within the expression line is added manually, but then the operators added based on the Match dropdown still apply between the conditions.

Add Group:

Adds another line that can have additional conditions and/or expressions added that are grouped together. There is a separate Match dropdown for all groups. This is another way to organize the overall expression to establish the desired nested conditions or hierarchical logic.

After using all of these components to build out the expression, the Edit Expression button can be selected if manual corrections are needed. This makes the Expression text field enabled so the changes can be made directly to the expression.

Building out Expression with the Create Simple Expression button

An alternative within this dialog is to select the Create Simple Expression button. This opens a dialog similar to that used in the Rule Builder. 

This dialog allows selecting the form object and defining an answer by first selecting the Form Section the desired object is on in the left column. 

Then select the desired form object in the middle Questions column. If the > symbol is displayed in the Questions column, that means an answer can be specified for that form object. This applies to object types that have static answers (drop downs, radio buttons, finder objects, etc). If no > symbol is displayed (this applies to objects with no set answers like text fields, numbers, dates, etc), selecting that item will complete the expression. 

If an answer is needed, then select an answer in the right Options column. 

Once all selections are made, the corresponding expression is populated in the Expression text field.

If this process is repeated, it adds the subsequent selected condition to the existing one, which results in the Expression text field updating like:

There are two condition types that can be created from this workflow: a condition where a form object equals a specific answer and a condition where a form object is answered in general. The former is represented by the first condition in the image above. The latter is represented by the second condition in the image above. This syntax means if there is any answer in the selected field, that condition will evaluate to true. 

Which Method to Use

The Create Simple Expression option provides a simpler user experience for those that aren’t comfortable either manually typing the expression syntax or using the components within the dialog, but this option is much more limited. There are only the two condition options described above, instead of all of the different operator options that can be selected in the previous method. And each condition added via this method is ANDed with the rest, there is no way to change that within the dialog. This method should be used for straightforward expressions where all conditions need to be true. 

Either manually editing or using the components within the Expression dialog offers much more flexibility, but requires a little more effort to set up. This method can be used for any expression by those comfortable with the structure, but should especially be used when trying to establish more complicated expressions using a mixture of && and || operators or hierarchical groups.

Expression Syntax Examples

The AFB offers so much flexibility in creating expressions for the applicable attributes. Below are some potential use cases and the syntax needed to achieve the desired results. The examples include the use of a range of different object types to demonstrate how to include more complicated objects like the funding program, the data table, etc.

Note: when <formObjectValue> is referenced in the examples below, this means the content that is in the desired form object’s Value attribute in the form builder. 

Exact Answer

If you want to set up an expression that requires a form object to have an exact answer, use the Equals syntax below. This means if the answer is anything else, the expression will evaluate to false. This is best for object types that can only have one answer.

General Syntax: {{ <formObjectValue> == ‘<desiredAnswer>’ }}

Examples:

• Simple object (i.e. drop down) with Value = proposalType and available answer ‘New’
  • {{ proposalType == 'New' }}
• Finder object (i.e. unit finder) with Value = adminUnit and a unit from the Admin module that has a GUID = 73bdc65a-e243-48b5-80eb-e73d4dcb2cdd
  • {{ adminUnit == '73bdc65a-e243-48b5-80eb-e73d4dcb2cdd' }}
  • Note: the expression must use the GUID of the finder object answer, the name cannot be used.
• AU/NZ Classification Codes object with Value = fORCode and desired code value 330101
  • {{ flw.mapAttr(fORCode, 'code') == '330101' }}
  • Note: See Special Syntax Cases section for more details
• Funding program object with Value = fundingProgram and a funding program in the Admin module with a GUID = 54f0eac2-eec9-4deb-888e-3e10bfa5dd4f 
  • {{ flw.mapAttr(fundingProgram, 'id') == '54f0eac2-eec9-4deb-888e-3e10bfa5dd4f' }}
  • Notes: 
    • See Special Syntax Cases section for more details
    • This object requires the GUID like the finder objects for the desired funding program or funding round

Includes an Answer

If you want to set up an expression that requires an object to have a specific answer present, but that may not be the only answer for that object, use the Includes syntax below. This is especially useful for object types like finders or drop downs that can be set up to allow multiple answers. 

General Syntax: {{ <formObjectValue>.includes(‘<desiredAnswer>’) }}

Examples:

• Simple object (i.e. drop down) with Value = proposalType and available answer ‘New’
  • {{ proposalType.includes('New') }}
• Finder object (i.e. unit finder) with Value = adminUnit and a unit from the Admin module that has a GUID = 73bdc65a-e243-48b5-80eb-e73d4dcb2cdd
  • {{ adminUnit.includes('73bdc65a-e243-48b5-80eb-e73d4dcb2cdd') }}
  • Note: the expression must use the GUID of the finder object answer, the name cannot be used.
• AU/NZ Classification Codes object with Value = fORCode and desired code value 330101
  • {{ flw.mapAttr(fORCode, 'code').includes('330101') }}
  • Note: See Special Syntax Cases section for more details
• Funding program object with Value = fundingProgram and a funding program in the Admin module with a GUID = 54f0eac2-eec9-4deb-888e-3e10bfa5dd4f
  • {{ flw.mapAttr(fundingProgram, 'id').includes('54f0eac2-eec9-4deb-888e-3e10bfa5dd4f') }}
  • Notes: 
    • See Special Syntax Cases section for more details
    • This object requires the GUID like the finder objects for the desired funding program or funding round

Any Answer

If you want to set up an expression that requires an object to simply be answered (not empty), use the Any answer syntax below.

General Syntax: {{ <formObjectValue>.length > 0 }}

Examples:

• Simple object (i.e. drop down) with Value = proposalType
  • {{ proposalType.length > 0 }}
• Finder object (i.e. unit finder) with Value = adminUnit
  • {{ adminUnit.length > 0 }}
• AU/NZ Classification Codes object with Value = fORCode
  • {{ flw.remove.nulls(flw.mapAttr(fORCode, 'code')).length > 0 }}
  • Note: the addition of the flw.remove.nulls() function helps to make sure objects whose answer defaults to ‘null’ when empty are not mistaken for being answered.
• Funding program object with Value = fundingProgram
  • {{ flw.remove.nulls(flw.mapAttr(fundingProgram, 'id')).length > 0 }}

Special Syntax Cases

The previous section already demonstrated that some object types, like Funding Program and AU/NZ Classification Codes require special syntax in order to achieve the desired results. Below are some additional examples of object types or scenarios that require unique syntax.

Objects with multiple fields

Since these objects have multiple attributes, the following syntax needs to be used to properly identify the correct attribute in the expression:

flw.mapAttr(<formObjectValue>, 'attribute'), 

Where the valid ‘attributes’ are based on the specific object. See the table below for the applicable object types and their valid attributes:

Other objects in this category that are not yet supported:

• Research Team
• Summary Budget Importer

Examples of how to use this syntax for the relevant object types are provided in the sections above. 

Data Table

To reference a data column table, use the following syntax:

<formObjectValue>["Column Name"]

Where <formObjectValue> is the table object’s value attribute and the Column Name is the label for that desired column.

Examples:

For all cases below, let’s assume the following:

• There is a table object with value = budgetTable
• This table includes the following column names and object types:
  • Period Start Date - date
  • Period End Date - date
  • Period Direct Costs - number
  • Period Indirect Costs - number
  • Period Sponsor Costs - expression field
• There is a number field outside of the table called Total Sponsor Costs

1. Custom validation message in the table
   1. Display an error message under the Period End Date field if its value is before the Period Start Date.
   2. Expression: {{budgetTable["Period Start Date"] < budgetTable["Period End Date"] }} 
2. Expression Field object within the table
   1. Want Period Sponsor Costs to be a sum of the direct and indirect cost columns
   2. Expression: {{budgetTable["Period Direct Costs"] + budgetTable["Period Indirect Costs"]}}
3. Expression Field object outside the table
   1. Want Total Sponsor Costs to populate with the sum of all Period Sponsor Costs rows in the table object
   2. Expression: {{ flw.sum(budgetTable["Period Sponsor Costs"]) }}

Date

If a custom validation expression refers to a date object and references a specific date, that date needs to be formatted as “YYYY-MM-DD”. 

Example: if there is a date object with value = date1 where a custom validation expression is needed to display a warning if a specific date (i.e. December 31, 2026) is selected, the syntax would be:

{{ date1 != “2026-12-31” }}

AFB Known Issues with fields that support expressions

1. A blank, non-null expression is erroneously being created in the Ignore, Visible and Enable attributes when the user accesses the AFB expression builder via the hamburger icon and

• clicks OK without entering any data
• clicks OK after clearing an expression via the Reset Expression function (without entering a new expression)

The user may not notice the issue until they attempt to publish the form. At that time, the user will see an error which directs them to the Section and Question that has the error along with the message “<Ignore, Visible, Enable> attribute contains a blank, non-null value”

To fix the issue, the user must select the lightning bolt next to the attribute to reset it and ensure the attribute’s checkbox is set as desired

2. With the Create Simple Expression function, users can append multiple conditions within the same expression by using the Create Simple Expression function multiple times before clicking OK. With this ability, it is important to note the following scenarios and best practices:

• Expression exists in expression text field
• Another expression is created using the Create Simple Expression function

Result: Expressions will be appended

• User deletes all text from the expression text field
• Another expression is created using the Create Simple Expression function

Result: Deleted expression will be restored and the new expression appended to it

Best Practices

• Ensure only the desired expression remains before clicking OK
• Delete the existing expression, click OK and then re-edit to add the new expression