Qualtrics JavaScript Question API Class
The
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.
Item Index
Methods
- addEmbeddedData
- addOnClick
- addOnload
- addOnReady
- addOnPageSubmit
- addOnUnload
- clickNextButton
- clickPreviousButton
- disableNextButton
- disablePreviousButton
- displayErrorMessage
- enableNextButton
- enablePreviousButton
- getAnswers
- getChoiceAnswerValue
- getChoiceContainer
- getChoiceDisplayed
- getChoiceRecodeValue
- getChoices
- getChoicesFromQuestionInfo
- getChoicesFromRecodeValue
- getChoicesFromVariableName
- getChoiceValue
- getChoiceVariableName
- getInput
- getInstance
- getInstance
- getPostTag
- getQuestionContainer
- getQuestionDisplayed
- getQuestionInfo
- getQuestionTextContainer
- getSelectedAnswers
- getSelectedAnswerValue
- getSelectedChoices
- getTextValue
- globalKeyDownHandler
- globalKeyUpHandler
- hideChoices
- hideNextButton
- hidePreviousButton
- inputClickHelper
- navClick
- navEnter
- OnEndOfSurvey
- onPageLoad
- openPageInPDF
- savePageBeforeUnload
- setAccessibleSkin
- setChoiceAnswerValue
- setChoiceValue
- setChoiceValueByRecodeValue
- setChoiceValueByVariableName
- setEmbeddedData
- showNextButton
- showPreviousButton
Methods
addEmbeddedData
-
key
-
value
Adds embedded data to the page
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);
}
}
});
addOnPageSubmit
-
f
Parameters:
-
f
Function- the function to execute when page is submitted.
f
accepts an optionaltype
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"); } });
- the function to execute when page is submitted.
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.
getChoiceContainer
()
Gets the div of the choices
Example:
$$('.ChoiceStructure')
getChoiceDisplayed
-
choiceId
-
answerId
-
subId
Determines if the choice is displayed or hidden
Returns:
true if displayed
getChoicesFromQuestionInfo
-
type
-
val
Gets the choices from the question info
getChoicesFromRecodeValue
-
recodeVal
Gets the choice ids that have matching recode values
Parameters:
-
recodeVal
String
Returns:
choice ids with matching recode value
getChoicesFromVariableName
-
varName
Gets the choice ids that have matching variable names
Parameters:
-
varName
String- The variable name to search for
Returns:
choice ids with matching variable name
getChoiceValue
-
choiceId
-
[subId]
Gets the actual value of a choice in the question. If a matrix-style question, also specify the subId (answerId).
Parameters:
Returns:
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
getInput
-
choiceId
-
answerId
-
[opt_returnArray]
Gets the input element according to the choiceId and answerId
Parameters:
Returns:
the Input Element, or if opt_returnArray is true, an array of elements (ie matrix single answer questions)
getInstance
-
questionId
-
[opt_createNewInstance]
Finds the data for the specified question
getQuestionContainer
()
Returns the div of the question (.QuestionOuter)
getQuestionDisplayed
()
Boolean
Determines if the question is displayed or hidden
Returns:
true if displayed
getQuestionInfo
()
Object | null
Returns an object containing information about the question. See Qualtrics.SurveyEngine.QuestionInfo
getQuestionTextContainer
()
Gets the div of the question text
Example:
$$('.QuestionText')
getSelectedAnswers
()
Gets the selected answers
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
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
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).
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.
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.
setEmbeddedData
-
key
-
value
Sets embedded data to the page, or adds it if the ED key is not on the page already
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