How To: Use Expressions

As your survey becomes more advanced, you may want to use expressions to calculate a default value or create logic. The expression feature is similar to a mathematical expression or a formula in Excel. For example, you can use them to calculate a sum, BMI, or add today's date to a survey. Expressions must follow a particular order and structure, such as:

{question1} + {question2}, ({price}*{quantity}) * (100 - {discount})

You can also use functions such as: iif(), today(), age(), min(), max(), count(), avg() and others.

Built-in Functions

Below is a list of the functions built into the Ripple Survey Creator. Content pulled from Survey JS documentation.

Iif

iif(condition: expression, valueIfTrue: any, valueIfFalse: any): any

Explanation: 

Returns the value specified by valueIfTrue if the given condition is true and the value specified by valueIfFalse if the condition is false. The condition is an expression that can contain typical operands/operators and references to question values (as question names in curly brackets).

Example:

expression: "iif({question1} + {question2} > 20, 'high', 'low')"

isContainerReady

isContainerReady(nameOfPanelOrPage: string): Boolean

Explanation: 

Returns true, if all questions in the specified container (panel or page) are answered correctly (a respondent provided a valid input). This function recursively validates all questions in the container. If there is an error, the function returns false, otherwise true. In case a question's value is empty and neither validators no required status are defined for the editor, validation would pass successfully.

Example:

expression: "isContainerReady('page1')"

isDisplayMode

isDisplayMode(): Boolean

Explanation: 

Returns true if a survey is in display mode.

Example:

expression: "isDisplayMode()"

age

age(birthDate: any): number

Explanation: 

Returns the age according to the date of birth passed. The passed date value (which is typically taken from the referenced question) should be defined as a valid JavaScript Date.

Example:

expression: "age({birthdate})"

currentDate

currentDate(): Date

Explanation: 

Returns the current date.

Example:

expression: "currentDate()"

today

today(daysToAdd?: number): Date

Explanation: 

Returns the current date or a date calculated using an optional parameter. The parameter specifies the number of days to be added to the current date. For example, "today()" returns the current date 0 hours, 0 minutes, "today(-1) returns yesterday's date, "today(1)" returns tomorrow's date, "today(2) returns day after tomorrow date, and so on.

Examples:

expression: "today()"

expression: "today(2)"

userDate

userDate(): Date

Explanation: 

Returns the respondent's current date

Example:

expression: "userDate()"

userDateTime

userDateTime(): Date and time

Explanation: 

Returns the respondent's current date and time

Example:

expression: "userDateTime()"

getDate

getDate(): Date, time, and timezone

Explanation: 

Returns the respondent's current week day, month, date, year, time, and timezone

Example:

expression: "getDate()"

userTimeZone

userTimeZone(): number

Explanation: 

Returns the number of minutes between the user's timezone and GMT. This number can be divided by 60 to get the number of hours between the respondent's timezone and GMT.

Example:

expression: "userTimeZone()"

now

now(): number

Explanation: 

Returns the number of milliseconds between the respondent's current timezone and January 1, 1970. This can be used to track the respondent's timestamp down to the millisecond.

Example:

expression: "now()"

diffDays

diffDays(dateFrom: any, dateTo: any): number

Explanation: 

Returns the number of days between two dates. Dates are typically specified by expressions that correspond to questions (by their names in curly brackets) containing date values.

Example:

expression: "diffDays({startDate}, {endDate})"

sum

sum(par1: number, par2: number, ...): number

Explanation: 

Returns the sum of the passed arguments.

Example:

expression: "sum({total1}, {total2})"

max

max(par1: number, par2: number, ...): number

Explanation: 

Returns the largest value from a list of the passed arguments. 

Example:

expression: "max({total1}, {total2})"

min

min(par1: number, par2: number, ...): number_

Explanation: 

Returns the smallest value from a list of the passed arguments. 

Example:

expression: "min({total1}, {total2})"

avg

avg(par1: number, par2: number, ...): number

Explanation: 

Returns the average value of the passed arguments.

Example:

expression: "avg({total1}, {total2}, {total3})"

 

Example - Populating Today’s Date by Default

In this example we have a consent form that requires a participant signature and we want the current date to populate into a date field automatically.

1. Using the Toolbox, add an "Expression (read-only)" question
2. Navigate to the "Properties" panel on the right
3. Under the "General" section, navigate to the "Expression(?)" field
4. Type in "today()" into the field
5. Change the "Display style" dropdown to "date"
6. Click the "Save Survey" button

When the survey is opened the date field will now automatically populate with the current date.