API Docs for: 2.0
Show:

Qualtrics JavaScript Question API Class

The Qualtrics Question API allows users to interact with a question in a survey using JavaScript. Note that interaction with questions is not limited to the functions available in the API. The API simply abstracts the most used functionality to a set of methods called on the question object.

All functions using the API must be wrapped in a Qualtrics.SurveyEngine.addOnload function. The addOnload function automatically instantiates the Question Data class and binds the instantiated object to allow its functions and properties to be accessed using the this keyword directly.

Constructor

Qualtrics JavaScript Question API

(
  • [opt_questionId]
)

Parameters:

  • [opt_questionId] String optional
    • the id of the desired question

Example:

<script>
//create Qualtrics.SurveyEngine.QuestionData object
Qualtrics.SurveyEngine.addOnload(function ()
{
    //disables the next button on the page
    this.disableNextButton();
    //question click is a simple onclick handler
    //attached to the question's container div
    this.questionclick = function(event,element)
    {
        //by default you get the click event as the first parameter and the clicked element as the second parameter
        console.log(event, element);
        if (element.type == 'radio')
        {
            var choiceNum = element.id.split('~')[2];
            alert('You clicked on choice '+choiceNum);
            if (choiceNum == 2)
            {
                //enables the next button - Note that the QuestionData object is bound to this to make it easier to use
                this.enableNextButton();
            }
            else
            {
                //disables the next button
                this.disableNextButton();
            }
        }
    }
});
</script>

Below is a list of predefined functions and properties that can be used on the Qualtrics.SurveyEngine.QuestionData class. Note that the addOnload function on the Qualtrics.SurveyEngine object automatically instantiates the QuestionData class and binds the instantiated object to allow these functions to be called using this directly.

Methods

addEmbeddedData

(
  • key
  • value
)

Adds embedded data to the page

Parameters:

  • key String
    • the embedded data key
  • value String
    • the value of the embedded data

addOnClick

()

Adds an observer/listener to the click event on the question. Rather than calling addOnClick directly, this method will be called automatically by the addOnLoad method. You only need to assign a function to the questionclick property and the Survey Engine will take care of it for you.

Example:

Qualtrics.SurveyEngine.addOnload(function ()
{
    this.questionclick = function(event,element){
        //for a single answer multiple choice question, the element type will be radio
        if (element.type == 'radio')
        {
            var choiceNum = element.id.split('~')[2];
            alert('You clicked on choice '+choiceNum);
        }
    }
});

addOnload

(
  • f
)

Parameters:

  • f Function
    • the function to execute on load

addOnReady

(
  • f
)

Parameters:

  • f Function
    • the function to execute when page is loaded and ready

addOnPageSubmit

(
  • f
)

Parameters:

  • f Function
    • the function to execute when page is submitted. f accepts an optional type parameter that will be one of "jump", "next", or "prev" depending on how the page was submitted.

    Example:

    //Sets "ED1" to "foo" when the page is submitted by advancing to the next page
Qualtrics.SurveyEngine.addOnPageSubmit(function(type)
{
	if(type == "next")
	{
		Qualtrics.SurveyEngine.setEmbeddedData("ED1", "foo");
	}
});

addOnUnload

(
  • f
)

Parameters:

  • f Function
    • the function to execute when page is unloaded

clickNextButton

()

Emulates a click on the Next Button to submit the page

Example:

//Hides the next button and displays the question
//for 5 seconds before moving to the next page
this.hideNextButton();
var that = this;
(function(){that.clickNextButton();}).delay(5);

clickPreviousButton

()

Emulates a click on the Previous Button to submit the page

disableNextButton

()

Sets the disabled attribute to true on the Next Button to disable it

disablePreviousButton

()

Sets the disabled attribute to true on the Previous Button to disable it

displayErrorMessage

(
  • msg
)

Displays an error message

Parameters:

  • msg String
    • the message to be displayed

enableNextButton

()

Sets the disabled attribute to false on the Next Button to enable it

enablePreviousButton

()

Sets the disabled attribute to false on the Previous Button to enable it.

getAnswers

() Array

Gets the answer ids for the question.

Returns:

Array:

getChoiceAnswerValue

(
  • choiceId
  • answerId
  • subId
)
String

Parameters:

Returns:

String:

value of the choice answer

getChoiceContainer

()

Gets the div of the choices

Example:

$$('.ChoiceStructure')

getChoiceDisplayed

(
  • choiceId
  • answerId
  • subId
)
Boolean

Determines if the choice is displayed or hidden

Parameters:

Returns:

Boolean:

true if displayed

getChoiceRecodeValue

(
  • choiceId
)

Gets the choice's recode value

Parameters:

getChoices

() Array

Gets the choices

Returns:

Array:

getChoicesFromQuestionInfo

(
  • type
  • val
)
private

Gets the choices from the question info

Parameters:

getChoicesFromRecodeValue

(
  • recodeVal
)
Array

Gets the choice ids that have matching recode values

Parameters:

Returns:

Array:

choice ids with matching recode value

getChoicesFromVariableName

(
  • varName
)
Array

Gets the choice ids that have matching variable names

Parameters:

  • varName String
    • The variable name to search for

Returns:

Array:

choice ids with matching variable name

getChoiceValue

(
  • choiceId
  • [subId]
)
String

Gets the actual value of a choice in the question. If a matrix-style question, also specify the subId (answerId).

Parameters:

  • choiceId String
    • The ID of the choice
  • [subId] String optional
    • The ID of the Column Answer, etc.

Returns:

String:

the value of the choice

Example:

this.getChoiceValue(3); //returns the value of choice 3
this.getChoiceValue(3,2); //returns the value of row choice 3 answer col 2

getChoiceVariableName

(
  • choiceId
)

Gets the choice's variable name

Parameters:

getInput

(
  • choiceId
  • answerId
  • [opt_returnArray]
)
InputElement | Array private

Gets the input element according to the choiceId and answerId

Parameters:

  • choiceId String
    • the id of the desired input's choice
  • answerId String
    • the id of the desired input's answer
  • [opt_returnArray] Boolean optional
    • set to true if the caller can handle an array return value

Returns:

InputElement | Array:

the Input Element, or if opt_returnArray is true, an array of elements (ie matrix single answer questions)

getInstance

(
  • questionId
  • [opt_createNewInstance]
)
private

Finds the data for the specified question

Parameters:

  • questionId String
    • the id of the question whose data is being requested. If the registry does not contain a question with this id, a new instance of QuestionData will be created.
  • [opt_createNewInstance] Boolean optional
    • (currently unused) if true will return a new instance of the class

getInstance

(
  • id
)
private

Parameters:

getPostTag

() String | null

Gets the post tag from the current question's QuestionInfo object

Returns:

String | null:

getQuestionContainer

()

Returns the div of the question (.QuestionOuter)

getQuestionDisplayed

() Boolean

Determines if the question is displayed or hidden

Returns:

Boolean:

true if displayed

getQuestionInfo

() Object | null

Returns an object containing information about the question. See Qualtrics.SurveyEngine.QuestionInfo

Returns:

Object | null:

QuestionInfo

getQuestionTextContainer

()

Gets the div of the question text

Example:

$$('.QuestionText')

getSelectedAnswers

()

Gets the selected answers

getSelectedAnswerValue

(
  • choiceId
)

Gets the selected answer's value

Parameters:

getSelectedChoices

()

Gets the selected choices

getTextValue

(
  • [opt_choiceId]
)

Gets the value of the input text

Parameters:

  • [opt_choiceId] String optional

Returns:

value of the current choice's input

globalKeyDownHandler

() private

The top level keydown event handler

globalKeyUpHandler

() private

The top level keyup event handler

hideChoices

()

Hides the choice container

hideNextButton

()

Hides the Next Button

hidePreviousButton

()

Hides the Previous Button

inputClickHelper

(
  • e
)
private

Parameters:

navClick

(
  • el
  • [opt_buttonName]
  • [opt_confirmValidation]
  • [jumpIndex]
)
private

Qualtrics.SurveyEngine.navClick This is responsible for submitting the form which advances them through the survey

Parameters:

  • el HTMLElement
  • [opt_buttonName] String optional
  • [opt_confirmValidation] Boolean optional
    • this is true if they have seen the validation message and wish to continue without answering
  • [jumpIndex] Integer optional

navEnter

(
  • e
  • el
  • [opt_buttonName]
  • [opt_confirmValidation]
  • [jumpIndex]
)
private

Qualtrics.SurveyEngine.navEnter This is responsible for submitting the form which advances them through the survey. This only should be called onkeypress for the nav buttons. It simply checks that the key was enter then calls Qualtrics.SurveyEngine.navClick

Parameters:

  • e Event
  • el HTMLElement
  • [opt_buttonName] String optional
  • [opt_confirmValidation] Boolean optional
    • this is true if they have seen the validation message and wish to continue without answering
  • [jumpIndex] Integer optional

OnEndOfSurvey

() private

End of Survey Trigger define a qualtricsEndOfSurvey in window.parent, and it will execute on survey complete.

onPageLoad

() private

Use this if you have an embedded survey. You can define a qualtricsPageLoad in window.parent, and it will execute on page load.

openPageInPDF

() private

Print the page in PDF

savePageBeforeUnload

() private

setAccessibleSkin

() private

Changes the Skin of the Survey to one that is Accessible

setChoiceAnswerValue

(
  • choiceId
  • answerId
  • value
)

Sets the choice answer's value

Parameters:

Returns:

true if success, false if failure

setChoiceValue

(
  • choiceId
  • [subId]
  • value
)

Sets the actual value of a choice in the question. If a matrix-style question, also specify the subId (answerId).

Parameters:

  • choiceId String
    • The ID of the choice being set
  • [subId] String optional
    • The ID of the Column Answer, etc.
  • value String
    • The value being set

setChoiceValueByRecodeValue

(
  • recodeValue
  • [subId]
  • value
)

Sets the value of the choice(s) specified by a recode value. Multiple choices in a question may have the same recode value. An attempt will be made to set each choice that is found. For single answer questions this may result in only the last matching choice being set.

Parameters:

  • recodeValue String
    • The recode value of the choice(s) being set
  • [subId] String optional
    • The ID of the Column Answer, etc.
  • value String
    • The value being set

setChoiceValueByVariableName

(
  • variableName
  • [subId]
  • value
)

Sets the value of the choice(s) specified by a variable name. Multiple choices in a question may have the same variable name. An attempt will be made to set each choice that is found. For single answer questions this may result in only the last matching choice being set.

Parameters:

  • variableName String
    • The variable name of the choice(s) being set
  • [subId] String optional
    • The ID of the Column Answer, etc.
  • value String
    • The value being set

setEmbeddedData

(
  • key
  • value
)

Sets embedded data to the page, or adds it if the ED key is not on the page already

Parameters:

  • key String
    • the embedded data key
  • value String
    • the new value of the embedded data

showNextButton

()

Shows the Next Button

showPreviousButton

()

Shows the Previous Button

Properties

Qualtrics.SurveyEngine.QuestionInfo

Object

An object containing all the questions on the page. Each question is indexd by its questionID

Example:

{
    QuestionID: (string) The question id
    QuestionText: (string) The question text
    QuestionType: (string) The question type code
    Choices: (object) Key is the choice id, value is information about the choice
    {
        RecodeValue: (string)
        VariableName: (string)
        Text: (string)
        Exclusive: (boolean)
    }
}

questionclick

Function

Can be set to a callback function to perform a custom function when any element of the question is clicked. The function will be passed the following parameters:

Example:

this.questionclick = function(event,element){
    //for a single answer multiple choice question, the element type will be radio
    if (element.type == 'radio')
    {
        var choiceNum = element.id.split('~')[2];
        alert('You clicked on choice '+choiceNum);
    }
}

Sub-properties:

questionContainer

HTMLElement

The question container

questionId

String

The question ID

registry

Object private