Warning 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 recommended deployment patterns for more information.

Public Methods

This article details methods the host page can use to interact with Questions API.

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
Returns: QuestionsApp

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:
  • "mathjax"
  • "mathquill"
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
Returns: SimpleFeature

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.

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
Properties:
features
Type: Array[FeatureJson]
questions
Type: Array[QuestionJson]
var toAppend = {
    questions: [
        {
            response_id: "toappend",
            type: "shorttext",
            stimulus: "What is the capital of Uruguay?",
            valid_responses: [{
                value: "montevideo",
                score: 1
            }],
            max_length:10
        }
    ]
};

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.

Returns: boolean

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: boolean

Returns an object that exposes methods to that can be called on the Feature object.

Parameters
feature_id
Type: string
Returns: Feature

Allows access to a feature object for each feature available in the activity.

Returns: Features

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
Properties:
response_ids
Type: Array[string]
type
Type: string
Possible values:
  • "per-question"
  • "dichotomous"
  • "dependent"
Returns: false | GroupScore

Returns metadata for all Questions in which it is defined.

Returns: MetadataList

Returns the JSON object for each Question of the activity.

Returns all responses that the user has provided.

Returns: ResponsesList

Returns scores for all auto-scorable Questions in the activity.

Returns: ScoresList

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).

Returns: question

Allows access to a question object for each question available in the activity.

Returns: QuestionsList

Confirms that all responses have been saved.

This includes coverage for ongoing audio recording and uploading.

Returns: boolean

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
Properties:
error
progress
success

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
Properties:
error
progress
success

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.

An optional argument can be passed with an attribute that will cause correct answers to be displayed.

Parameters
options
Type: object
Properties:
showCorrectAnswers
Type: boolean
Default: false

Depending on the mode, it returns:

  • "simple": an array of the valid response_ids in the current activity
  • "detailed": an object with response_ids as keys and boolean as value indicating whether the quesiton is valid or not
  • "detailedWithPartials": an object with response_ids as 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:
  • "simple"
  • "detailed"
  • "detailedWithPartials"
Default: "simple"

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.

Returns: Promise
.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.

Returns: 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.

Returns: boolean

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: boolean

Returns metadata for the question instance.

Note For more information, see the metadata knowledge base article.

Returns: Metadata

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: array

Returns initialization data used by the question instance.

Returns: QuestionJson

Returns a response object containing possible responses for the question instance.

Returns scoring information for the question instance.

Returns: Score

Returns whether or not the question instance was attempted.

Returns: boolean

Returns whether or not the question instance supports response masking.

Returns: boolean

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 or null (unattempted), indicating if it is correct, incorrect or unattempted.
Parameters
withPartials
Type: boolean
Returns: boolean / object / null

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.

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 Questions 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 Questions 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 Question 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 audio question instance from recording.

object
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();
object
Properties:
audioQualityCheck

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.

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

Important Audio question only.

Go to a point in the user's response. Takes the position in Percentage of the audio duration

setMetadata

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.

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
Properties:
backgroundNoiseThreshold
Type: float

Value (between 0 and 1) to compare the minimum energy computed on the recording, if it is higher than this value, it is considered the recording has "background noise".

Default: 0.025
numberOfClippingSamples
Type: integer

Number of clipping samples that are tolerated before considering the recording "Too loud".

Default: 40
tooQuietThreshold
Type: float

Value (between 0 and 1) to compare the computed loudness on the recording, if it is lower than this value, it is considered the person was "Too quiet".

Default: 0.08
Returns: false | AudioQuality

Important 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.

Returns: boolean
object
Properties:
get
Type: function()

Important Audio question only.

Returns an integer stating volume of the recording. The returned values are between 0 (0%) and 1 (100%).

Returns: float
set

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%).

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: SimpleFeature

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.

Parameters
options
Type: object
Properties:
showCorrectAnswers
Type: boolean
Default: false

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.

object

Important Audio Player type only.

Properties:
pause
Type: function()

Pause playback.

play
Type: function()

Play the asset.

resume
Type: function()

Resume paused playback.

seek

Go to a specific point in the asset. Takes the position in Percentage of the audio duration (e.g: 80).

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
object
Properties:
get
Type: function()

Returns an integer stating volume of the audio file. The returned values are between 0 (0%) and 1 (100%).

Returns: float
set

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%).

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.

Returns: Promise
.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.

object

Important ImageTool type only.

Properties:
position

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.

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
Properties:
left
Type: integer
top
Type: integer

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: SimpleFeature

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.

object

Important Video Player type only.

Properties:
pause
Type: function()

Pause playback.

play
Type: function()

Play the asset.

resume
Type: function()

Resume paused playback.

seek

Go to a specific point in the asset. Takes the position in Percentage of the video duration (e.g: 80).

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

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.

object
Properties:
[simple_feature_id]
Array[string]

List of response_ids.

Array[Question]

List of Questions.

object
Properties:
max_score
Type: integer
question_scores
Type: Array[QuestionScore]
score
Type: integer
type
Type: string
object
Properties:
max_score
Type: integer
score
Type: integer
object
Properties:
[response_id]
Type: object
object
Properties:
[feature_id]
object
Properties:
[question_id]
object
Properties:
[response_id]
Type: object
object
Properties:
[response_id]
Type: object
Parameters
response_ids
Type: Array[string]
Parameters
error
Type: object
Properties:
code
Type: integer
detail
Type: string
msg
Type: string
Parameters
progress
Type: object
Properties:
bytesTotal
Type: integer
bytesUploaded
Type: integer
percentage
Type: integer
state
Type: string
Array[string]
List of response_ids.
object

An object containing each question object available in the activity, keyed by their references.

Properties:
[question_reference]
Type: question
object
Properties:
apiVersion
Type: string
responses
Type: array[*]
type
Type: string
value
Type: string
object
Properties:
max_score
Type: integer
score
Type: integer
object

Note For more information, see the metadata article.

object
Properties:
correct
incorrect
unattempted
Array[object]
Types
object
Properties:
index
Type: integer
metadata
Type: string
value
Type: *
object
Properties:
has_validation
Type: boolean
object
Properties:
catch
Type: function()
then
Type: function()
object
Properties:
[simple_feature_id]
object
Properties:
code
Type: integer
Possible values:
  • 0
  • 1
  • 2
  • 3
message
Type: string
Possible values:
  • "Acceptable"
  • "background noise"
  • "Too quiet"
  • "Too loud"
object
Properties:
[simple_feature_id]
object
Properties:
catch
Type: function()
then
Type: function()