Page manipulation in scripting

Use the page object to manipulate the page at the last stage of the responding engine. At this point, survey logic, piping, localization, and randomization and rotation have all already occurred.

Note:
  • The page is a separate root object passed to the onLoad function and can only occur onLoad. Accessing the page object from onComplete will cause an error.
  • You cannot hide elements that do not have names. Currently Divider elements do not support names, so they are not scriptable.
  • Page customization is visual only. Hiding the question does not skip the question. Instead, it marks the question as not required if the question was set to required.
  • The page is still rendered for survey respondents even if all elements in it are removed or hidden.
  • Hidden elements (for example, masked answer options or survey elements hidden through survey logic) cannot be accessed through scripting.

Page elements

Here, "page elements" refer to named survey components on survey pages that are visible on the responding side. This includes:

  • Questions
  • Text and Image, Media Player, and Embedded Content elements
  • End Survey and Profile actions
Function or property Description
page.getElement("elementName"); Returns an element within the page by name.
element.name Read-only property. The name of the element within the page.
element.hide(); Hides a question or element within the page.
Note: If all questions on a page are hidden, the entire page will be skipped. Respondents will proceed directly to the subsequent page.
Example

In this function example, the question named City is hidden. 

let city = page.getElement('city');
city.hide();

Child elements

Here, "child elements" refer to the elements within page elements, such as answers, Grid question statements, and Allocation and Rank Order items. The following question types have child elements:

  • Single Choice
  • Multiple Choice
  • Single Choice Grid
  • Multiple Choice Grid
  • Allocation
  • Rank Order

You can access child elements through the elements property (visual order) or by using the getElementByAuthoredIndex method. Accessing child elements in anything other than the question types listed above will result in a runtime error.

Function or property Description
element.elements The list of child elements within the page element.
element.getElementByAuthoredIndex(index) Returns a child element by authored index. Zero-based.
Note: This method will return undefined if the index value is incorrect, or if an answer is hidden in any of the following ways:
  • The answer was hidden by a masking rule.
  • An answer that was carried forward was hidden.
  • An answer that was carried forward was hidden by a Carry Forward Answers rule (for example, by showing selected or unselected answers).
grid.elements[0] Applies to Grid questions. References the answers. Zero-based.
grid.elements[1] Applies to Grid questions. References the statements. Zero-based.
Note:
  • If all answers in a question are hidden, the entire question will be hidden.
  • In Grid questions, if all rows or all columns are hidden, the entire question will be hidden.
Example

In this function example, the first authored choice for the Single Choice question City is hidden. 

let city = page.getElement('city');
city.getElementByAuthoredIndex(0).hide();
Example

In this function example, the first rendered choice for the Single Choice question City is hidden. 

let city = page.getElement('city');
city.elements[0].hide();
Example

In this function example, the first authored answer option is hidden for all statements in the Grid question favoriteMovieGrid. 

let favMovie = page.getElement('favoriteMovieGrid');
favMovie.elements[0].getElementByAuthoredIndex(0).hide();
Example

In this function example, the second rendered statement is hidden in the Grid question favoriteMovieGrid. 

let favMovie = page.getElement('favoriteMovieGrid');
favMovie.elements[1].elements[1].hide();