The expression editor allows you to create logical rules (known as "expressions") out of variables, operators, and "hard coded" values that you write-in yourself.
The purpose of the expression editor changes depending on where you find it throughout the app builder, and you will find it in many different places.
Example 1: The expression editor is used to conditionally display a page block to the end-user:
Example 2: The expression editor is used to conditionally insert a text variable onto a document template (in this case, a Word template made with our Word add-in):
Basic structure of an expression
An expression includes variables, operators, and "hard-coded" values you write-in yourself.
Simple vs. complex expressions
You do not need to use every dropdown in the expression editor. For some variables, you may notice that we provide "shortcuts" that combine all the required elements of an expression:
You can also write complex, multi-line expressions:
...but you do not need to fill in every dropdown in an expression. This is perfectly valid:
Note: Complex, multi-line expressions are not available in every expression editor. For example, the expression editor for adding conditional logic to a question can only accommodate one expression line.
What operators can you use?
What operators are available to you depends on the datatype of the variable(s) you're working with.
Continue reading for a breakdown of each operator...
The equals operator evaluates whether two values are identical to each other:
If the two values are identical, the expression resolves to True; if not, the expression resolves to False.
Similarly, the does not equal operator evaluates whether two value are not identical.
These operators (is defined and is undefined) evaluate whether a variable has a known value.
A variable represents an unknown value. For example, a boolean variable can be either True or False; a text variable can be any combination of letters. A variable is "defined" if it has a known value.
Example: If a variable is created by a question, it is defined if that question is answered, regardless of how the question is answered. That variable is "undefined" if the question is skipped.
More generic operators
- coalesce: work in progress
These operators (case-insensitively includes and case-sensitively includes) evaluate whether a plaintext variable or value includes another plaintext variable or value.
An expression with this operator resolves to True or False depending on whether the condition is met.
The case-insensitively includes operator evaluates two pieces of text without concern for difference in letter case (e.g. uppercase, lowercase, etc...). Whereas the case-sensitively includes operator does consider letter case differences.
Use-case: You can use this operator to evaluate whether an email includes specific domains.
Join with(out) a space
These operators (join with a space and join without a space) create a new plaintext variable by combining two other plaintext variables, with or without a space between the two pieces of text.
Example: You use this operator to join a first name with a last name to create a full name:
As a number / date
These are two different operators with similar functions:
- as a number: This converts a plaintext variable into a number-type variable.
- as a date, given it's formatted like 06/26/1986: This converts a plaintext variable into a date. As the name of this operator explains, the plaintext variable must have a specific format for this operator to work.
This operator creates a plaintext variable that is equal to a character from another plaintext variable. You specify which character with a number, where "2" equals the 2nd character, "3" equals the 3rd character, and so on.
Example: This expression creates a plaintext variable that is equal to the 2nd character in the variable user_first_name:
Use-case: You can use this operator to break up text into individual characters for populating a PDF that requires it (e.g. government forms frequently require a social security number be broken out character by character).
More plaintext operators
- character length: Creates a number-type variable that is equal to the number of characters in a plaintext variable. Use this operator to determine if a piece of text is too long to fit into a PDF field.
- to lowercase: Creates a plaintext variable that is equal to another plaintext variable, formatted to all lowercase.
- to title case: Creates a plaintext variable that is equal to another plaintext variable, formatted to title case (i.e. This Is Title Case).
- to uppercase: Creates a plaintext variable that is equal to another plaintext variable, formatted to all uppercase.
- to all caps: Creates a plaintext variable that is equal to another plaintext variable, formatted to all caps (i.e. THIS IS ALL CAPS).
There are many math operators (e.g. +, -, /, x, <, >, and so on), each creates a new number-type variable that is the result of the operator's unique function.
Example: This expression creates a number-type variable that is the result of multi-line mathmatical expression:
There are several operators that allow you to convert a number-type variable into plaintext, formatted in a certain way:
- formatted as text with commas to two decimal points: 10000 becomes 10,000.00.
- formatted as text with commas with no decimals: 10000 becomes 10,000
- formatted as text with commas separating thousands: 10000 becomes 10,000.0
- formatted as text to this many decimal places: Allows you to determine how many decimal places should be included; for example, this expression creates a plaintext variable that is formatted to 5 decimal places:
Use-case: Use this variable to format a number to look like currency, e.g. formatting 5000 into $5,000.00.
Days before / after
These operators create a datetime variable by manipulating an existing datetime with a number-type variable.
- Minutes before / after
- Hours before / after
- Days before / after
- Weeks before / after
- Months before / after
- Years before / after
Example: This expression creates a datetime variable that is 20 days after Today:
More number operators
- ceiling: work-in-progress
- floor: work-in-progress
- as its ordinal: work-in-progress
- switching commas and periods: Creates a number-type variable that is equal to another number-type variable, except the commas and periods are switched.
- absolute value: work-in-progress
These operators subtract the number of years, months, or days between two dates. The result of an expression with this operator is a number-type variable.
Example: This expression counts the number of years between Today and the end-user's date of birth:
You could expand this ^ expression to then evaluate whether the end-user is greater than or equal to a threshold age (e.g. 18).
Pro tip: Use the earlier date on the lefthand side of your expression, otherwise you will end up with negative numbers that likely don't make sense. For example, 2022 minus 1986 equals 36 which makes sense if my goal is to determine someone's age.
These operators format a datetime variable by converting it into a plaintext variable.
- Formatted like September
- Formatted like Thursday, September 9, 2021
- Formatted like dd/mm/yyyy
- Formatted like yyyy/mm/dd
- Formatted like mm/dd/yyyy
- Formatted like dd
- Formatted like 2021
- Formatted like 9th day of September
- Formatted like mm (09)
- Formatted like September 9, 2021
Example: This expression formats Today into a format that's appropriate for a formal document:
Is later / earlier than
These operators determine whether a datetime variable is later or earlier than another datetime variable. An expression with this operator evaluates to either True or False.
Example: This expression is True is the end user's date of birth is earlier than a qualifying date:
More datetime operators
- to seconds since epoch: work-in-progress
Is false / true
These operators determine whether a boolean-type variable is either True of False.
Pro tip: Beware negating yourself with expressions that combine "is true" with "is false":