Scripting functions for survey elements

The following functions allow you to interact with the different elements programmed into a survey, such as questions. These functions can help with:

Piping responses from previous questions into the question text of a follow-up question.
Referencing question settings (such as how many selections a respondent must make) in error messages.

Referencing question settings through script ensures that what respondents see is always in sync with what is programmed into the survey.

Remember that functions that require parameters (such as the question name) can be used outside of the question whose name you are passing into the function. Some functions that don’t take in a question name as a parameter can only be used inside of the question they reference.

Some functions may work with multiple question types, but they may return different information based on the type of question being referenced. Pay careful attention that the function you use will return the desired result.

Below is a list of the survey elements and the functions that are available to use for each.

Element type	Applicable functions
Single-select	getLabel getValue
Multi-select	getValue rangeMax rangeMin
Open-end	getValue
Single-select grid	getLabel getValue
Multi-select grid	getValue rangeMax rangeMin
Numeric grid	getValue
Bipolar grid	getValue
Constant sum	getValue constantSumTotal
Numeric	getValue rangeMax rangeMin decimalLimit
Ranking	getValue getListItemLabelOfRank getListItemNumberOfRank
MaxDiff	getMDBestLabel getMDWorstLabel getMDItemLabelOfRank getMDItemNumberOfRank
Quota	getLabel getValue

This function can only be used to reference the question the script is used in.

Available for: constant sum

Function: constantSumTotal():number

Return: The number entered in the Total field.

This function can only be used to reference the question the script is used in.

Available for: numeric

Function: decimalLimit():number

Return: The number entered in the Max decimal places field.

This function returns the label of the respondent’s answer to a given question. The term “label” is used to describe the text of an item in the list of items. For example, “Red” was the text of the item selected by the respondent; therefore, the returned label is “Red”.

If the question has not been seen by the respondent, the function will return null.

Function: getLabel(questionName: string): string | null

Example: {{getLabel("Q1")}}

Return: The text of the selected item. Returns an empty string, or "", if the respondent did not provide an answer, and null if the respondent has not seen the question.

Function: getLabel(questionName: string, rowNumber: number): string

Example: {{getLabel("Q1", 1)}}

Return: The text of the selected column for a given row in a grid question. Returns an empty string, or "", if the respondent did not provide an answer, and null if the respondent has not seen the question.

Function: getLabel(quotaName: string): string | null

Example: {{getLabel("Quota1")}}

Return: The name of the quota group the respondent was assigned to. Returns an empty string, or "", if the respondent was not assigned a group, and null if the respondent was skipped over the question.

This function returns the value of the respondent's answer to a given question. The term “value” will change in meaning depending on the survey element it is used in. Value can be used to describe:

The text entered by a respondent in an open-end question.
- Ex: My name is Skyler.
The number of an item in a question's list (used when a respondent can only select one item).
- Ex: Red is number 3 in my list, the respondent selected red, the return value is 3.
A Boolean value (true or false), which tells whether an item was selected or not (used when a respondent can select multiple items).
- Ex: The respondent selected red and blue, so the values for those would be true.
null, which means the value you are asking for does not exist. In the context of this function, it means the respondent did not see the question.

Function: getValue(questionName: string): number | null

Example: {{getValue("Q1")}}

Return: The number of the item selected. Returns 0 if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(questionName: string, itemNumber: number): boolean | null

Example: {{getValue("Q1", 1)}}

Return: Whether a specified item was selected or not, true if the item was selected, false if it was not.

Function: getValue(questionName: string): string | null

Example: {{getValue("Q1")}}

Return: The text entered by the respondent. Returns an empty string, or “”, if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(questionName: string, rowNumber: number): number | null

Example: {{getValue("Q1", 1)}}

Return: The number of the selected column. Returns 0 if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(questionName: string, rowNumber: number, columnNumber: number): boolean | null

Example: {{getValue("Q1", 1, 1)}}

Return: Whether a column in a specified row was selected or not (true or false). Returns false if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(questionName: string, rowNumber: number, columnNumber: number): number | null

Example: {{getValue("Q1", 1, 1)}}

Return: The number a respondent entered in the specified cell. Returns 0 if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(questionName: string, rowNumber: number): number | null

Example: {{getValue("Q1", 1)}}

Return: The number of the selected column. Returns 0 if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(questionName: string, itemNumber: number): number | null

Example: {{getValue("Q1", 1)}}

Return: The number the respondent entered for a specified item. Returns 0 if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(questionName: string): number | null

Example: {{getValue("Q1")}}

Return: The number entered by the respondent. Returns 0 if the respondent did not answer the question and null if the respondent has not seen the question.

Function: getValue(quotaName: string): number | null

Example: {{getValue("Quota1")}}

Return: The index of the quota group the respondent was put into. Returns 0 if the respondent was not assigned a group and null if the respondent was skipped over the quota.

Function: getValue(questionName: string, itemNumber: number): number | null

Example: {{getValue("Q1", 1)}}

Return: The rank number of the list item. Returns empty if the respondent did not answer the question and null if the respondent has not seen the question.

Available for: ranking

Function: getListItemLabelOfRank(questionName: string, Rank: number): string

Example: {{getListItemLabelOfRank("Priority Question", 1)}}

Return: The label of the item ranked in the defined position. The example to the left will return the item ranked in first place by the respondent.

Available for: ranking

Function: getListItemNumberOfRank(questionName: string, Rank: number): number

Example: {{getListItemNumberOfRank("Priority Question", 1)}}

Return: The list item number of the item ranked in the defined position. The example to the left will return the item ranked in first place by the respondent.

This function returns the text in the "Best" Label field in the MaxDiff exercise settings. This function will return the "Best" label for the particular MaxDiff question in which the function appears; it will only work on a task page of a MaxDiff.

This function returns the text in the "Worst" label field in the MaxDiff exercise settings. This function will return the "Worst" label for the particular MaxDiff question in which the function appears; it will only work on a task page of a MaxDiff.

Available for: MaxDiff

Function: getMDItemLabelOfRank(exerciseName: string, rankNumber: number): string

Example: {{getMDItemLabelOfRank("Cookie MaxDiff", 1)}}

Return: The MaxDiff item label of the specified rank based on the respondents' responses in the given MaxDiff exercise. The maximum rank number is the highest item number in the list used for the exercise.

Available for: MaxDiff

Function: getMDItemNumberOfRank(exerciseName: string, rankNumber: number): number

Example: {{getMDItemNumberOfRank("Cookie MaxDiff", 1)}}

Return: The MaxDiff item number that has the specified rank based on the respondents' responses in the given MaxDiff exercise. The maximum rank number is the highest item number in the list used for the exercise.

Returns the value of the maximum number for range or character settings in a question. This function can only return values for the question the respondent is viewing.

Function: rangeMax(): number

Return: The number entered in the Max number of selections field.

Return: The number entered in the Max number of selections field. Note that the max is the maximum number of selections in each row.

Return: The number entered in the Max characters field. Returns null if the Max characters field is not set.

Return: The number entered in the Max number field.

Returns the value of the minimum number of selections or characters required. This function can only return values for the question the respondent is viewing.

Function: rangeMin(): number

Return: The number entered in the Min number of selections field.

Function: rangeMin(): number

Return: Returns the number entered in the Min number of selections field.

Function: rangeMin(): number | null

Return: Returns the number entered in the Min characters field.

Function: rangeMin(): number

Return: The number entered in the Min number field.

Discover Help Guide

Scripting functions for survey elements

Introduction

Applicable functions

constantSumTotal

decimalLimit

getLabel

Single-select

Single-select grid

Quota

getValue

Single-select

Multi-select

Open-end (single or multi-line)

Single-select grid

Multi-select grid

Numeric grid

Bipolar grid

Constant sum

Numeric

Quota

Ranking

getListItemLabelOfRank

getListItemNumberOfRank

getMDBestLabel

getMDWorstLabel

getMDItemLabelOfRank

getMDItemNumberOfRank

rangeMax

Multi-select

Multi-select grid

Open-end (single and multi-line)

Numeric

rangeMin

Multi-select

Multi-select grid

Open-end (single and multi-line)

Numeric