Scripting functions for lists

These functions return a specified list to the page. These could be used for testing, or to display items to a respondent.

Function: printListItemLabelsArray(listName: string): string

Example: {{printListItemLabelsArray ("Q1List")}}

Return: The item text of all the items in the specified list, separated by commas and spaces.

Function: printListItemNumbersArray(listName: string): string

Example: {{printListItemNumbersArray("Q1List")}}

Return: The item values of all the items in the specified list, separated by commas and spaces.

These functions return a specified list to the page. These could be used for testing, or to display items to a respondent.

Function: getListItemLabelsArray(listName: string): string[]

Example: {{getListItemLabelsArray("Q1List")}}

Return: The item text of all the items in the specified list, separated by commas.

Function: getListItemNumbersArray(listName: string): string[]

Example: {{getListItemNumbersArray("Q1List")}}

Return: The item values of all the items in the specified list, separated by commas.

Used to add items to the dynamic list from another list. When items are added, they are always added to the end of the dynamic list being created.

Function: add(listName: string): void

Example: add("My source list");

Result: All of the items from My source list will be added to the end of the dynamic list.

Function: add(listName: string, itemNumber: number): void

Example: add("My source list", 2);

Result: Item number 2 from My source list will be added to the dynamic list.

Function: add(listName: string, startItemNumber: number, endItemNumber: number): void

Example: add("My source list", 4, 6);

Result: Items 4, 5, and 6 from My source list will be added to the end of the dynamic list.

Used to add items to a specific position in a dynamic list. If the item being added already exists in the list, that item will be moved to the position specified. If the insert position specified is greater than the number of items in the list, the item or items will be added to the end of the list.

Function: addAtPosition(listName: string, insertPosition: number): void

Example: addAtPosition("My source list", 3)

Result: All of the items in My source list will be added to the dynamic list beginning at position 3 in the dynamic list.

Function: addAtPosition(listName: string, itemNumber: number, insertPosition: number): void

Example: addAtPosition("My source list", 2, 3)

Result: Item number 2 in My source list will be added at position 3 in the dynamic list.

Function: addAtPosition(listName: string, startItemNumber: number, endItemNumber: number, insertPosition: number): void

Example: addAtPosition("My source list", 4, 6, 3)

Result: Items 4, 5, and 6 in My source list will be added to the dynamic list beginning at position 3 in the dynamic list.

Used to pull items that have been selected or not selected by a respondent in a question into the dynamic list. The specified question must use the dynamic list’s source list or another dynamic list that shares the same source list as the list under construction.

Function: carryForward(questionName: string): void

Example: carryForward("Familiar brands");

Result: Items that were selected in the question Familiar brands will be added to the bottom of the dynamic list.      

Function: carryForward(questionName: string, isSelected: boolean): void

Example: carryForward("Familiar brands", false);

Result: Items that were not selected in the question Familiar brands will be added to the bottom of the dynamic list.

Used to add items to a dynamic list from a specified question where the values of those items meet a comparison criterion. This function will only work for ranking and constant sum question types.

Function: carryForwardCompareValues(questionName: string, comparisonOperator: string, value: number): void

Example: carryForwardCompareValues("Ranking question", "<=". 3);

Result: Will add all the items from Ranking question where the value of the item is less than or equal to 3. In other words, the top three items from Ranking question will be added to the dynamic list. Valid comparison operators are < for less than, <= for less than or equal to, > for greater than, >= for greater than or equal to, = for equal to, and != for not equal to.

Function: carryForwardCompareValues(questionName: string, compareFn: (value: number) => boolean): void

Example: carryForwardCompareValues("Ranking question", x => x >=3 && x <=6);

Result: Applies a provided comparison function to the items in Ranking question as the parameter x and if the function returns true, the item is added to the dynamic list. In this case, it will add all items to the dynamic list that have values between 3 and 6 including 3 and 6. This example uses an arrow function syntax to define the comparison function. You can find out more about the arrow function syntax in this article.

Used to add items to a dynamic list from the row list in a grid question when the column selections for that row match a certain condition. This function only works for single or multi-select grids. The grid row list must be the source list of the dynamic list being built or another dynamic list that uses the same source list as the dynamic list being built.

Function: carryForwardGridRows(gridQuestionName: string, isSelected: boolean, columnNumber: number): void

Example: carryForwardGridRows("My grid question", true, 3);

Result: All items in the row list for the grid question named My grid question who have column 3 selected will be added to the bottom the constructed list being built.

Function: carryForwardGridRows(gridQuestionName: string, isSelected: boolean, columnNumberArray: number[]): void

Example: carryForwardGridRows("My grid question", false, [1,3,5]);

Result: All items in the row list of the grid question named My grid question will be added to the end of the list being constructed so long as columns 1, 3, 5 are not selected in those rows.

Used to randomize the items of the dynamic list.

Function: randomize()

Example: randomize();

Result: All the items that have been previously added to the dynamic list will now appear in random order.

Function: randomize(startPosition: number, endPosition: number): void

Example: randomize(2, 4);

Result: items 2, 3, and 4 will now appear randomly in positions 2, 3, and 4 in the new list.

Used to remove items from the list being built.

Function: remove(listName: string): void

Example: remove("Dynamic list with shared source list");

Result: All items that are in the list named Dynamic list with shared source list will be removed from the dynamic list being built.

Function: remove(listName: string, itemNumber: number): void

Example: remove("Source list", 4);

Result: Item 4 from the list named Source list will be removed from the dynamic list being built.

Function: remove(listName: string, startItemNumber: number, endItemNumber: number): void

Example: remove("Source list", 2, 5);

Result: items 2, 3, 4, and 5 from the list named Source list will be removed from the dynamic list that is being built.

Used to set a maximum length for the dynamic list. The specified number of items will remain in the dynamic list and all other items will be removed from the dynamic list. If there are fewer items than the number specified, then nothing will happen.

Function: listMax(listLength: number): void

Example: listMax(4);

Result: The first four items will be kept in the list and the rest will be removed.

Used to set a minimum length for the dynamic list. Items from the source list will be added at random until there are at least as many items as specified in the dynamic list. If the number of items in the new list is greater than or equal to the number of items specified, nothing happens.

Function: listMin(listLength: number): void

Example: listMin(7);

Result: Items will be chosen at random from the source list and added to the bottom of the dynamic list being built until there are 7 items in the dynamic list.

Used to specify the exact length you want the dynamic list to be. If there are fewer than the number of items specified, items are added at random from the source list until the length of the dynamic list is equal to the number specified. If there are more than the specified number, then those coming after the number of items specified will be removed.

Function: setListLength(listLength: number): void

Example: setListLength(4);

Result: After removing an item after item 4 or adding items at random from the source list, the dynamic list will have 4 items in it.

If statements allow you to conditionally execute code based on a custom condition. Let's say that I have a question called Gender and I want to change the content of my dynamic list based on the gender of the respondent. For males, I want to add items 1-4 of my source list to the dynamic list, and for females, I want to add items 5-8. Both genders should see items 9 and 10, and those who choose not to specify their gender should not see the question.

In this case, let's say that the value of Gender for males is 1, for females is 2, and for those who choose not to specify, the value is 3. The name of my source list for this dynamic list is Color list.

The first thing this script does is save the value of our Gender question to a variable called Gender. Then, we see there is an if statement that uses that variable to check if the value is equal to 1. If the value of Gender for this respondent is equal to 1, the script inside the curly braces will execute, and items 1-4 will be added to the dynamic list.  

The next portion of the script is an else if statement. This condition will only be checked if the condition in the previous if statement was false. In this example, if the respondent has a value of 1 for gender, then the condition in the else if statement will not even be checked. If the respondent has a value of 2 or 3 for gender, this condition will check if the value is 2. If it is, the code inside the curly braces will be executed, and items 5-8 will be added to the dynamic list.

The final section of the code is another if statement. If the respondent has a value for Gender that is not equal to 3, meaning they selected male or female, then items 9 and 10 will be added to the dynamic list.

The result of our script for a respondent who has the value 1 for Gender will be a list that contains items 1, 2, 3, 4, 9, and 10. A respondent who has a value of 2 for Gender will have a list that contains items 5, 6, 7, 8, 9, and 10. A respondent with a value of 3 for Gender will end up with an empty list because all the conditions that get checked will return false. Because the list is empty, the question will be skipped.

For more information on JavaScript if statements, this tutorial may be useful.