Warning! This is a lower-level API. Lower-level APIs are not recommended for most projects, and may not be available on all plans. See our page on Public Methods
This article details methods the host page can use to interact with Questions API.
LearnosityApp
The following methods are accessed via the window.LearnosityApp object.
When the <script src="https://questions-va.learnosity.com"></script> tag is included on the page, the window.LearnosityApp object is instantiated, and ready for use.
Initializes the Questions API.
Returns an object, containing Questions API Public Methods - most other public methods are called against this object.
See initialization for more information.
| Parameters | |
|---|---|
request
|
Type:
Request
|
callbacks
|
Type:
Callbacks
|
Renders all Latex or MathML elements on the page with MathJax.
If the "mathquill" renderer is used, only Latex inside a .lrn parent will be rendered.
| Parameters | |
|---|---|
renderer
|
Type:
string
Possible values:
Default:
"mathjax"
|
This method exists on the global window.LearnosityApp object and can access any Simple Feature with a data-simplefeature-id property.
Returns an object that exposes methods to that can be called on the Simple Feature object. Only the simple features attached to the question are accessible through this method.
See simples features for more information.
| Parameters | |
|---|---|
simple_feature_id
|
Type:
string
|
This method exists on the global window.LearnosityApp object and accesses all Simple Features on the page that have a data-simplefeature-id property.
Returns the collection of all Simple Feature objects attached to the question.
See simples features for more information.
questionsApp
The following methods are accessed via the questionsApp object returned by window.LearnosityApp.init(). This object provides methods to interact with, and receive information relating to the questions placed on page.
Appends Questions or Features to the current activity. It expects an Object with Arrays containing the JSON definition for Questions and/or Features.
The corresponding HTML hooks need to be placed in the DOM prior to calling append.
Once the Questions/Features have been rendered, the readyListener is called if defined in Initialization.
| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
options
|
Type:
object
|
||||||||
var toAppend = {
questions: [
{
response_id: "toappend",
type: "shorttext",
stimulus: "What is the capital of Uruguay?",
valid_responses: [{
value: "montevideo",
score: 1
}],
max_length:10
}
],
responses: {
"toappend": {
apiVersion: "latest",
characterCount: 9,
revision: 1,
type: "string",
value: "montevideo"
}
}
};
questionsApp.append(toAppend);
Returns an array of response_ids which have been attempted in the current activity.
Disables the user's ability to enter responses for questions.
A return of true indicates that questions were disabled, and false indicates that no action was taken.
By default, all questions are enabled.
This method only works when in the "initial" or "resume" states, when not in those states, false is returned.
See question methods for more information.
Enables the user's ability to enter responses for questions.
A return of true indicates that questions were enabled, and false indicates that no action was taken.
By default, all questions are enabled.
This method only works when in the "initial" or "resume" states, when not in those states, false is returned.
See question methods for more information.
Returns an object that exposes methods to that can be called on the Feature object.
| Parameters | |
|---|---|
feature_id
|
Type:
string
|
Returns the JSON object for each Feature of the activity.
Scores a given group of questions using rules determined by scoring type: "per-question", "dichotomous", or "dependent".
If successful, returns an object with type, score, max_score, and question_scores as values. Returns false on error.
Note For more information, see the items scoring knowledge base article.
| Parameters | |||||||
|---|---|---|---|---|---|---|---|
settings
|
Type:
object
|
||||||
false | GroupScoreReturns metadata for all Questions in which it is defined.
Returns the JSON object for each Question of the activity.
Returns all responses that the user has provided.
Returns scores for all auto-scorable Questions in the activity.
Masking is a way for students to visually reduce the population of correct answers as they work through solving a given question. Therefore, it has no impact on the response object and no tie to the validation of the question.
| Parameters | |
|---|---|
state
|
Type:
boolean
|
questions
|
Type:
Array[string]
List of response_ids.
|
Given a reference for a particular question, returns a question object for that question instance.
| Parameters | |
|---|---|
response_id
|
Type:
string
The reference for the question instance (response ID). |
Allows access to a question object for each question available in the activity.
Confirms that all responses have been saved.
This includes coverage for ongoing audio recording and uploading.
Saves the user responses in the Learnosity Database.
The optional settings argument provides a way to define specific callbacks for events related to the save operation.
| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
settings
|
Type:
object
|
||||||||
Allows the setting of a context height for scrollable passages with fluid heights, e.g. 100%, 60%, etc.
By default, scrollable passages use the window's viewport height as the context for calculating fluid heights. This method is useful if you don't want the context height to be the window height; but rather, the height of another element, e.g. a wrapping div with a dynamic height.
If the string "content" is passed, the scrollable passages will stretch to the height of the content within, i.e. the scrollbars will be removed.
| Parameters | |
|---|---|
height
|
Type:
float | integer | string
|
Stop playback of all audio, video simple features as well as hide all imagetool, protractor and calculator simple features.
Saves the user responses in the Learnosity Database, and flags them for grading. This will make them available via the Reports API and Data API.
The optional settings argument provides a way to define specific callbacks for events related to the submit operation.
| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
settings
|
Type:
object
|
||||||||
Returns an array of response_ids that are unable to be saved in the current activity. Usually related to exceeding the word count in long text or plain text question types.
Causes all attempted auto-scorable Questions in the activity to render feedback for the user.
The showCorrectAnswers can be passed with an attribute that will cause correct answers to be displayed.
When feedbackAttempts set to true, this will increment feedbackAttemptCount, or do nothing if the feedbackAttemptCount limit has already been reached.
| Parameters | |||||||
|---|---|---|---|---|---|---|---|
options
|
Type:
object
|
||||||
Depending on the mode, it returns:
-
"simple": an array of the validresponse_idsin the current activity -
"detailed": an object withresponse_idsas keys and boolean as value indicating whether the question is valid or not -
"detailedWithPartials": an object withresponse_idsas keys and object as value containing:- correct: boolean indicating whether the question is valid or not
- partial: array detailing whether each individual response is valid or not is returned only if the question can have multiple responses
| Parameters | |
|---|---|
mode
|
Type:
string
Possible values:
Default:
"simple"
|
question
The following methods are accessed via the question object returned by questionsApp.questions() or questionsApp.question("response_id"). This object provides methods to interact with, and receive information for questions used.
Triggers the audio question instance to begin recording.
Check if images within the Question are loaded. The returned Promise resolves if all the images have successfully loaded and rejects as soon as one image fails loading.
.checkImages()
.then(function () {
console.log('All images are loaded');
})
.catch(function () {
console.log('An image within the question failed loading');
});Returns whether or not the question instance has valid validation.
Disables the user's ability to enter responses for the question instance.
A return of true indicates that the question instance was disabled, and false indicates that no action was taken.
By default, all questions are enabled.
This method only works when in the "initial" or "resume" states, when not in those states, false is returned.
This method can also be called on Questions API directly, affecting all questions.
Enables the user's ability to enter responses for the question instance.
A return of true indicates that the question instance was disabled, and false indicates that no action was taken.
By default, all questions are enabled.
This method only works when in the "initial" or "resume" states, when not in those states, false is returned.
This method can also be called on Questions API directly, affecting all questions.
Returns metadata for the question instance.
Note For more information, see the metadata knowledge base article.
Returns the processed options that have been rendered into the page. The processed option object contains the information about current options like label, value and the choice_label (e.g. A, B, C... or a, b, c or 1, 2, 3... based on the ui_style.choice_label value). Note that the order of the processed options can be different to the options of the original question's JSON if shuffle_options is set to true.
Note
This method is only available for mcq question type.
Returns initialization data used by the question instance.
Returns a response object containing possible responses for the question instance.
Returns scoring information for the question instance.
Returns whether or not the question instance was attempted.
Returns whether or not the question instance supports response masking.
Returns whether or not the response of the question instance passes validation.
When withPartials is false or does not pass any argument, it returns whether the response is valid or not. If the question can't be validated (e.g. if there's no response), then it returns null.
When withPartials is true, it returns a detailed object on the validity of the response. The object contains the following variables:
- correct (boolean): a true/false value indicating if the answer is correct or incorrect.
- partial (array/object/array of arrays): a map of each response to a boolean, indicating if it is correct or not.
| Parameters | |
|---|---|
withPartials
|
Type:
boolean
|
Returns metadata for the question instance mapped to responses. This should only be used on validatable questions that can have multiple response areas. The metadata being mapped should be an array within metadata. For information about using this function to display distractor rationale, view this tutorial.
If successful, returns an object literal containing arrays that are keyed by "correct", "incorrect", and "unattempted".
Each item in these arrays is an object that contains value property that holds the response value;
an index property that refers to the shared index of both the response area and the metadata value;
and metadata property that contains the metadata value.
Returns false if the all the necessary data doesn't exist, e.g. non-existent metadata, or question does not contain multiple response areas, etc.
Note For more information, see this tutorial article.
| Parameters | |
|---|---|
metadata_key
|
Type:
string
|
Changes the masked state of the question instance, with a given mask ui-style.
| Parameters | |
|---|---|
state
|
Type:
boolean
|
Removes a previously-bound callback function for an event.
When called with no arguments, all event listeners are removed.
| Parameters | |
|---|---|
eventName
|
Type:
string
Name of the event that you want to stop listening to.
See list of events at the Question level for more information. |
eventCallback
|
Type:
callback()
If no callback is provided, all event handlers for the eventName will be removed.
|
context
|
Type:
object
Execution context that will be used for
this when the callback function is triggered. If no context is provided, all event bindings for the eventName, eventCallback combination will be removed. |
questionsApp.question('01-a__56732842-dbe1-47a6-ae48-5a126f2b13ba').off("changed");
//Removes event listeners for the 'changed' event.
questionsApp.question('my_response_id').off("changed");
//Removes event listeners for all events.Set up an event listener.
| Parameters | |
|---|---|
eventName
|
Type:
string
Name of the event that you want to listen to.
See list of events at the Question level for more information. |
eventCallback
|
Type:
callback()
Callback function that will be triggered whenever the event is fired.
|
context
|
Type:
object
Execution context that will be used for
this when the callback function is triggered. |
questionsApp.question('01-a__56732842-dbe1-47a6-ae48-5a126f2b13ba').on("changed", function {
console.log("The preview data was changed.");
}); // Sets up a recurring event listener for the 'changed' event with this Question.Set up a one-time event listener. Will fire once and then stop listening.
| Parameters | |
|---|---|
eventName
|
Type:
string
Name of the event that you want to listen to, once.
See list of events at the Question level for more information. |
eventCallback
|
Type:
callback()
Callback function that will be triggered once, when the event is fired.
|
context
|
Type:
object
Execution context that will be used for
this when the callback function is triggered. |
questionsApp.question('01-a__56732842-dbe1-47a6-ae48-5a126f2b13ba').once("validated");
//Sets up a one-time listener for the 'validated' event with this Question.
Pauses the audio question instance from recording.
| Properties: | |
|---|---|
pause
|
Type:
function()
Important Audio question only. Pause recording the user's response. |
retryUpload
|
Type:
function()
Important Audio question only. Attempts to retry uploading the user's audio response. |
start
|
Type:
function()
Important Audio question only. Begin recording the user's response. |
stop
|
Type:
function()
Important Audio question only. Stop the recording of the user's response. |
var audioQuestion = myLearnosityApp.question('60001');
audioQuestion.recording.start();
audioQuestion.recording.pause();
audioQuestion.recording.retryUpload();
audioQuestion.recording.stop();Reset the question's validation UI style to the original.
| Properties: | |
|---|---|
audioQualityCheck
|
Type:
function(settings)
Important Audio question only.
Returns an The method accepts an optional qualityParameters object that allows the client to override the default parameters used to assess the audio quality. Returns:
false | AudioQuality |
getMetadata
|
Type:
function()
Gets the response metadata set for this question. Returns:
undefined | Metadata |
pause
|
Type:
function()
Important Audio question only. Pause the user's response. |
play
|
Type:
function()
Important Audio question only. Play the user's response. |
resume
|
Type:
function()
Important Audio question only. Resume the user's response. |
seek
|
Type:
function(percentage)
Important Audio question only. Go to a point in the user's response. Takes the position in Percentage of the audio duration |
setMetadata
|
Type:
function(metadata)
Sets the given response metadata for this question. The metadata passed into this method may be anything that should be stored with the response object. A response must already exist before this method is called; if not, the metadata will not be set and an error will be logged.
Returns Returns: boolean
|
stop
|
Type:
function()
Important Audio question only. Stop playing the user's response. |
volume
|
Type:
object
|
var audioQuestion = myLearnosityApp.question('60001');
audioQuestion.response.getMetadata();
audioQuestion.response.setMetadata({ /* Insert response metadata here */ });
audioQuestion.response.play();
audioQuestion.response.pause();
audioQuestion.response.resume();
audioQuestion.response.seek(50);
audioQuestion.response.stop();
audioQuestion.response.audioQualityCheck();
audioQuestion.response.volume.get();
audioQuestion.response.volume.set(0.5);Important Audio question only.
Returns an object stating the quality of the recording or false if there was no response recorded in the current session.
The method accepts an optional qualityParameters object that allows the client to override the default parameters used to assess the audio quality.
| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
settings
|
Type:
object
|
||||||||
false | AudioQualityImportant Audio question only.
Go to a point in the user's response. Takes the position in Percentage of the audio duration
| Parameters | |
|---|---|
percentage
|
Type:
integer
|
Sets the given response metadata for this question.
The metadata passed into this method may be anything that should be stored with the response object. A response must already exist before this method is called; if not, the metadata will not be set and an error will be logged.
Returns true if the given metadata was able to be set for this question's response; otherwise false.
| Parameters | |
|---|---|
metadata
|
Type:
Metadata
Note For more information, see the metadata article. |
question - responsevolume
object| Properties: | |
|---|---|
get
|
Type:
function()
Important Audio question only.
Returns an integer stating volume of the recording. The returned values are between Returns: float
|
set
|
Type:
function(volume)
Important Audio question only.
Set the volume of an audio file (including recording) that is or will be played by an audio question. The valid values are between |
Important Audio question only.
Set the volume of an audio file (including recording) that is or will be played by an audio question. The valid values are between 0 (0%) and 1 (100%).
| Parameters | |
|---|---|
volume
|
Type:
float
|
Retries loading images contained in a question.
Returns an object that exposes methods to that can be called on the Simple Feature object. For a list of methods refer to feature methods. Only the simple features attached to the question are accessible through this method.
See simple features for more information.
| Parameters | |
|---|---|
simple_feature_id
|
Type:
string
|
Returns the collection of all SimpleFeature objects attached to the question.
See simple features for more information.
Stops the audio question instance from recording and captures the current response.
Validate the current response for the question instance.
The showCorrectAnswers can be passed with an attribute that will cause correct answers to be displayed.
When feedbackAttempts set to true, this will increment feedbackAttemptCount, or do nothing if the feedbackAttemptCount limit has already been reached.
| Parameters | |||||||
|---|---|---|---|---|---|---|---|
options
|
Type:
object
|
||||||
Load the next dynamic content value from the array.
This method will load the very first dynamic content if it has reached the last index.
Load the previous dynamic content value from the array.
This method will load the very last dynamic content if it has reached the beginning (index 0).
Return the current position in the array, or the index of dynamic content value.
Return the total number of dynamic content values in the current question instance.
feature
The following methods are accessed via the feature object returned by questionsApp.features() or questionsApp.feature("feature_reference"). This object provides methods to interact with, and receive information for any features used.
Important Audio Player type only.
| Properties: | |
|---|---|
pause
|
Type:
function()
Pause playback. |
play
|
Type:
function()
Play the asset. |
resume
|
Type:
function()
Resume paused playback. |
seek
|
Type:
function(percentage)
Go to a specific point in the asset.
Takes the position in Percentage of the audio duration (e.g: |
stop
|
Type:
function()
Stop playing the asset. |
volume
|
Type:
object
|
var audioFeature = myLearnosityApp.feature('60001');
audioFeature.audio.play();
audioFeature.audio.pause();
audioFeature.audio.resume();
audioFeature.audio.seek(50);
audioFeature.audio.stop();
audioFeature.audio.volume.get();
audioFeature.audio.volume.set(0.5);
Go to a specific point in the asset.
Takes the position in Percentage of the audio duration (e.g: 80).
| Parameters | |
|---|---|
percentage
|
Type:
integer
|
feature - audiovolume
object| Properties: | |
|---|---|
get
|
Type:
function()
Returns an integer stating volume of the audio file.
The returned values are between Returns: float
|
set
|
Type:
function(volume)
Set the volume of an audio file that is or will be played by an audio feature.
The valid values are between |
Set the volume of an audio file that is or will be played by an audio feature.
The valid values are between 0 (0%) and 1 (100%).
| Parameters | |
|---|---|
volume
|
Type:
float
|
Starts the Feature.
Check if images within the Question are loaded. The returned Promise resolves if all the images have successfully loaded and rejects as soon as one image fails loading.
.checkImages()
.then(function () {
console.log('All images are loaded');
})
.catch(function () {
console.log('An image within the question failed loading');
});Destroy current feature instance. The feature_id of the destroyed instance now can be reused.
Important ImageTool type only.
| Properties: | |
|---|---|
position
|
Type:
function(coordinates)
Position the Image Tool. Centers the Image Tool to the current viewport.
An object with |
const imagetoolFeature = myLearnosityApp.feature('60001');
// center image tool to current viewport
imagetoolFeature.imageTool.position();
// position image tool 100px from the top and 200px from the left of its container
imagetoolFeature.imageTool.position({
top: 100,
left: 200
});
Position the Image Tool. Centers the Image Tool to the current viewport.
An object with top and left values can be optionally provided as a parameter to override the position relative to its container.
| Parameters | |||||||
|---|---|---|---|---|---|---|---|
coordinates
|
Type:
object
|
||||||
Removes a previously-bound callback function for an event.
When called with no arguments, all event listeners are removed.
If no eventCallback is provided, all event handlers for the eventName will be removed.
If no context is provided, all event bindings for the eventName, callback combination will be removed.
| Parameters | |
|---|---|
eventName
|
Type:
string
Name of the event that you want to stop listening to
See Feature level supported events list for more information. |
eventCallback
|
Type:
callback()
If no callback is provided, all event handlers for the eventName will be removed.
|
context
|
Type:
object
If no context is provided, all event bindings for the eventName, eventCallback combination will be removed
|
Binds a callback function that will be invoked whenever the eventName is triggered.
To supply a context to execute the callback on, pass the optional third argument.
| Parameters | |
|---|---|
eventName
|
Type:
string
Name of the event that you want to stop listening to
See Feature level supported events list for more information. |
eventCallback
|
Type:
callback()
If no callback is provided, all event handlers for the eventName will be removed.
|
context
|
Type:
object
If no context is provided, all event bindings for the eventName, eventCallback combination will be removed
|
Just like on, but causes the bound callback to only fire once before being moved. Handy for saying "the next time that X happens, do this".
| Parameters | |
|---|---|
eventName
|
Type:
string
Name of the event that you want to stop listening to
See Feature level supported events list for more information. |
eventCallback
|
Type:
callback()
If no callback is provided, all event handlers for the eventName will be removed.
|
context
|
Type:
object
If no context is provided, all event bindings for the eventName, eventCallback combination will be removed
|
Pauses the Feature.
Retries loading images contained in a question.
Returns an object that exposes methods to that can be called on the Simple Feature object. For a list of methods refer to feature methods. Only the simple features attached to the question are accessible through this method.
See simple features for more information.
| Parameters | |
|---|---|
simple_feature_id
|
Type:
string
|
Returns the collection of all Simple Feature objects attached to the question.
See simple features for more information.
Stops the Feature.
Toggle visibility of calculator, imagetool (ruler, protractor).
| Parameters | |
|---|---|
show
|
Type:
boolean
If true, show the feature. If false, hide it. If this parameter is not set, then the feature’s visibility will be toggled on or off when called. |
Important Video Player type only.
| Properties: | |
|---|---|
pause
|
Type:
function()
Pause playback. |
play
|
Type:
function()
Play the asset. |
resume
|
Type:
function()
Resume paused playback. |
seek
|
Type:
function(percentage)
Go to a specific point in the asset. Takes the position in Percentage of the video duration (e.g: |
stop
|
Type:
function()
Stop playing the asset. |
var videoFeature = myLearnosityApp.feature('60001');
videoFeature.video.play();
videoFeature.video.pause();
videoFeature.video.resume();
videoFeature.video.seek(50);
videoFeature.video.stop();
Go to a specific point in the asset. Takes the position in Percentage of the video duration (e.g: 80).
| Parameters | |
|---|---|
percentage
|
Type:
integer
|
Object Definitions
In the Initialization and Callback sections above, there are some object definitions which are complex enough to document separately. These are listed below, and linked from the relevant documentation above.
| Properties: | |
|---|---|
[simple_feature_id]
|
Type:
SimpleFeature
|
List of response_ids.
Questions
Array[Question]List of Questions.
| Properties: | |
|---|---|
max_score
|
Type:
integer
|
question_scores
|
Type:
Array[QuestionScore]
|
score
|
Type:
integer
|
type
|
Type:
string
|
| Properties: | |
|---|---|
max_score
|
Type:
integer
|
score
|
Type:
integer
|
| Properties: | |
|---|---|
[response_id]
|
Type:
object
|
| Properties: | |
|---|---|
[feature_id]
|
Type:
FeatureJson
|
| Properties: | |
|---|---|
[question_id]
|
Type:
QuestionJson
|
| Properties: | |
|---|---|
[response_id]
|
Type:
object
|
| Properties: | |
|---|---|
[response_id]
|
Type:
object
|
| Parameters | |
|---|---|
response_ids
|
Type:
Array[string]
|
| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
error
|
Type:
object
|
||||||||
| Parameters | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
progress
|
Type:
object
|
||||||||||
response_ids.
| Properties: | |
|---|---|
apiVersion
|
Type:
string
|
responses
|
Type:
array[*]
|
type
|
Type:
string
|
value
|
Type:
string
|
| Properties: | |
|---|---|
max_score
|
Type:
integer
|
score
|
Type:
integer
|
Note For more information, see the metadata article.
| Properties: | |
|---|---|
correct
|
Type:
ValidationMetadata
|
incorrect
|
Type:
ValidationMetadata
|
unattempted
|
Type:
ValidationMetadata
|
| Types | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| object |
|
||||||||
| Properties: | |
|---|---|
has_validation
|
Type:
boolean
|
| Properties: | |
|---|---|
catch
|
Type:
function()
|
then
|
Type:
function()
|
| Properties: | |
|---|---|
[simple_feature_id]
|
Type:
SimpleFeature
|
| Properties: | |
|---|---|
code
|
Type:
integer
Possible values:
|
message
|
Type:
string
Possible values:
|
| Properties: | |
|---|---|
[simple_feature_id]
|
Type:
SimpleFeature
|
| Properties: | |
|---|---|
catch
|
Type:
function()
|
then
|
Type:
function()
|