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.

Example:

Method Deprecated

The addEmbeddedData() method is deprecated and is unavailable on the New Survey Taking Experience. Use the setJSEmbeddedData() method instead.

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

Qualtrics.SurveyEngine.QuestionData.getInstance(questionId string)

Accesses question information for any question on the current page.

Parameters:

questionId (String)

Returns:

Question (Object)

Example:

Qualtrics.SurveyEngine.addOnReady(function()
{
	var q2 = Qualtrics.SurveyEngine.QuestionData.getInstance("QID2");
	q2.getQuestionContainer();
	console.log(q2.getQuestionContainer());
});

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

Bypass buttons with clickNextButton () and clickPreviousButton ()

On the New Survey Taking Experience, these functions will bypass hidden and/or disabled next and previous buttons.

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

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:

choiceId (String)
answerId (String)
subId (String)

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:

choiceId (String)
answerId (String)
subId (String)

Returns: Boolean:

true if displayed

getChoiceRecodeValue ( choiceId )

Gets the choice's recode value

Parameters:

choiceId (String)

getChoices () Array

Gets the choices

Returns: Array:

getChoicesFromRecodeValue ( recodeVal ) (Array)

Gets the choice ids that have matching recode values

Parameters:

recodeVal (String)

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:

choiceId (String)

getJSEmbeddedData(key)

Gets embedded data from the page. The key value will be prefixed with __js_ when searching for the embedded data field on the page.

Usages

Embedded data fields on the page that are not prefixed with __js_ will not be accessible. If you want to access a flow element embedded data field make sure the name starts with __js_ in the embedded data block.

Parameters

key (string)

Example:

Qualtrics.SurveyEngine.setJSEmbeddedData(‘myData’) // sets embedded data field ‘__js_myData' on the page

Qualtrics.SurveyEngine.getJSEmbeddedData(‘myData’) // returns the embedded data field ‘__js_myData’ that is on the page (returns ‘test’)

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:

choiceId (Object)

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

hideChoices ()

Hides the choice container

hideNextButton ()

Hides the Next Button

hidePreviousButton ()

Hides the Previous Button

setChoiceAnswerValue ( choiceId answerId value )

Sets the choice answer's value

Parameters:

choiceId (String)
answerId (String)
value (String)

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

Method Deprecated

The setEmbeddedData() method is deprecated and is unavailable on the New Survey Taking Experience. Use the setJSEmbeddedData() method instead.

setJSEmbeddedData(key, value)

Sets embedded data on the page. The key value will be stored on the page with a prefix of __js_. If you want to use this embedded data field in the survey flow or in pipe text it should be referenced by the name __js_ + key.

Usages

If key = myData

To use the embedded data field in piped text use ${e://Field/__js_myData}
To include this embedded data field in survey responses make sure your embedded data flow block includes a field by the name __js_myData

Parameters

key (String)
value (String)

this.setJSEmbeddedData("myData", "test") // sets embedded data field '__js_myData' on the page

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:

event (Event): The click event
element (HTMLElement): The element that was clicked

questionContainer (HTMLElement) The question container

questionId (String) The question ID

Method Deprecated​

Bypass buttons with clickNextButton () and clickPreviousButton ()​

Method Deprecated​

Properties​

Method Deprecated

Bypass buttons with `clickNextButton ()` and `clickPreviousButton ()`

Method Deprecated

Properties