Methods
This article details methods the host page can use to interact with Items API.
LearnosityItems
The following methods are accessed via the window.LearnosityItems object.
When the <script src="https://items-va.learnosity.com"></script> tag is included on the page, the window.LearnosityItems object is instantiated, and ready for use.
init is a special method called off LearnosityItems once per instantiation
of the Items API.
From there, you can use the returned application instance to access all API public methods.
In Assess mode, it injects the assessment UI (player) in
place of the
#learnosity_assess DOM hook element.
In Inline mode, it injects single items in place of each DOM hook (see Quick Start for examples).
| Parameters | |
|---|---|
initOptions |
Type:
object See Items API initOptions for more information. |
domSelector |
Type:
string Specifies the DOM hook element used by Items API. This argument is optional and can be omitted, and Items API will use Note This argument only applies to assessments in Assess mode. See HTML Element Selector for more information. |
eventOptions |
Type:
object See Items API callbacks for more information. |
itemsApp
The following methods are accessed via the itemsApp object returned by window.LearnosityItems.init(). This object provides methods to interact with, and receive information from the particular instance of the Items API.
Most of these methods are not available until the readyListener callback (see initialization & callbacks for more info) - unless otherwise noted.
| Parameters | |||||||
|---|---|---|---|---|---|---|---|
options |
Type:
object
|
||||||
Obtains the application instance for the Assess API, if using rendering_type: assess.
From there you can call public methods to interact with the player.
rendering_type: assess.Obtains the application instance for the Events API, if using rendering_type: assess and events: true.
Note Events API must be enabled on your consumer for this to work.
| Parameters | |
|---|---|
featureReference |
Type:
string Reference of the feature that you want to interact with. |
activity_template_id, if defined.var activity = itemsApp.getActivity();
console.log(activity);
{
activity_id: "itemsassessdemo",
config : {
title: "Demo activity - showcasing question types and assess options",
subtitle: "Walter White",
regions: {…},
navigation: {…},
time: {…}
},
events: true,
format: "json",
items: [...],
name: "Items API demo - assess activity",
organisation_id: 6,
rendering_type: "assess",
retrieve_tags: true,
session_id: "98287363-ea5b-48fa-9ed7-5b58f7683854",
type: "submit_practice",
user_id: "aeee19fb-4e7b-435c-92f9-d93a1099988b"
}Obtains an object related to the current active item, if using the Assess API player.
Includes content, state as well as metadata.
Obtains an object containing scores for all items in the activity using rules determined by the item scoring type:
per-questiondichotomousdependent
See item scoring for more information.
var items = itemsApp.getItems();
console.log(items);
// Example for rendering_type: "assess"
{
ccore_002_ReorderText: {
active: false,
attempt_status: true,
content: "Foo bar",
feature_ids: [],
metadata: {
scoring_type: "per-question"
},
response_ids: [
"ccore_widget21"
],
source: {
organisation_id: 1,
reference: "ccore_002_ReorderText"
},
time: 317
user_flagged: false,
viewed: true
}
}
// Example for rendering_type: "inline"
{
ccore_002_ReorderText: {
content: "Foo bar",
feature_ids: [],
metadata: {
scoring_type: "per-question"
},
reference: "ccore_002_ReorderText",
response_ids: [
"ccore_widget21"
],
source: {
organisation_id: 1,
reference: "ccore_002_ReorderText"
},
workflow: []
}
}var questions = itemsApp.getQuestions();
console.log(questions);
{
10000: {
is_math: false,
metadata: {
valid_response_count: 1,
sheet_reference: "Demo4",
widget_reference: "00000000-0000-4000-0000-000000129905",
source: {
organisation_id: 6
}
},
options: [
{
label: "Pennsylvania to New England.",
value: "0"
},
{
label: "Georgia to New England.",
value: "1"
},
{
label: "Pennsylvania to New York.",
value: "2"
},
{
label: "Pennsylvania to Georgia.",
value: "3"
}
],
response_id: "10000"
stimulus: "<p>The Great Wagon Road ran from</p>",
type: "mcq",
validation: {
scoring_type: "exactMatch",
valid_response: {
score: 1,
value: [
"3"
]
}
}
}var responses = itemsApp.getResponses();
console.log(responses);
{
1fcc9839e559d98af05bcf9a3d863960: {
apiVersion: "v2.109.2",
revision: 1,
type: "array",
value: [0,1,2,3,4]
}
}var scores = itemsApp.getScores();
console.log(scores);
{
10000: {
max_score: 1,
score: null // not attempted
}
}Returns the current elapsed time, in seconds, for the activity if using rendering_type: assess.
When using sections configured with different time, the returned value is the total elapsed time of all sections.
| Parameters | |||||
|---|---|---|---|---|---|
options |
Type:
object
|
||||
| Parameters | |
|---|---|
itemReference |
Type:
string Reference of the item you want to access |
rendering_type: assess.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 Assessment player 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. |
//Removes event listeners for the 'focused' event.
itemsApp.off("focused");
//Removes event listeners for all events.
itemsApp.off();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.
It supports defining events with the event map syntax as an alternative to positional arguments.
For more information refer to the on method of the BackboneJS Event object.
| Parameters | |
|---|---|
eventName |
Type:
string Name of the event that you want to listen to. See Assessment player supported events list 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. |
// Sets up a recurring event listener for the 'focused' event.
itemsApp.on('focused', focusHandler);Set up a one-time event listener. Will fire once and then stop listening.
For more information refer to the on method of the BackboneJS Event object.
| Parameters | |
|---|---|
eventName |
Type:
string Name of the event that you want to listen to, once. See Assessment player supported events list 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. |
//Sets up a one-time listener for the 'focused' event.
itemsApp.once('focused', focusHandler);| Parameters | |
|---|---|
response_id |
Type:
string The reference for the question instance (response ID). |
Confirms that all responses have been saved.
This includes coverage for ongoing audio recording and uploading.
Saves the user session responses into the Learnosity database.
The settings argument provides a way to define specific callbacks for events related to the save operation. You should always use these to ensure that your save operation completes successfully or at least throws an error:
-
success(function)- Function called on a successful save.
-
error(function)- Function called when an error occurs while saving.
-
progress(function)- Function called when the save method is called.
var saveSettings = {
success: function (response_ids) {
// Receives a list of the saved session responses as [response_id]
console.log("save has been successful", response_ids);
},
error: function (e) {
// Receives the event object defined in the Event section
console.log("save has failed",e);
},
progress: function (e) {
// Client custom progress event handler
// e: uses the progress object defined bellow
// See the Progress Event section for more information on this
console.log("progress",e);
}
};
itemsApp.save(saveSettings);Saves the user session responses into the Learnosity database, and flags them for grading.
This will make them available via the Reports API and Data API.
The settings argument provides a way to define specific callbacks for events related to the submit operation. You should always use these to ensure that your submit operation completes successfully or at least throws an error:
-
success(function)- Function called on a successful submission.
-
error(function)- Function called when an error occurs while submitting.
-
progress(function)- Function called when the submit method is called.
-
show_submit_confirmation(boolean)- A boolean indicating whether a prompt should be shown to the user for confirming whether they want to submit the activity.
-
show_submit_ui(boolean)- A boolean indicating whether the user should be shown a panel indicating successful submission of the activity. If true, they will no longer be able to work on the activity. If false, the activity will be submitted silently in the background.
var submitSettings = {
success: function (response_ids) {
// Receives a list of the submitted session responses as [response_id]
console.log("submit has been successful", response_ids);
},
error: function (e) {
// Receives the event object defined in the Event section
console.log("submit has failed",e);
},
progress: function (e) {
// Client custom progress event handler
// e: uses the progress object defined bellow
// See the Progress Event section for more information on this
console.log("progress",e);
},
show_submit_confirmation: true,
show_submit_ui: true
};
itemsApp.submit(submitSettings);| Parameters | |
|---|---|
responseCallback |
Type:
callback() Containing the response_ids that can not be saved. |
callback is called with an object having item references as keys and a value which depends on the specified mode:
detailed(default)- 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 | |
|---|---|
callback |
Type:
callback() Containing an object having item references as keys and a value. |
mode |
Type:
string
Possible values:
Default: detailed |
Causes all 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.
| Parameters | |||||
|---|---|---|---|---|---|
options |
Type:
object
|
||||
assessApp
The following methods are accessed via the assessApp object returned by itemsApp.assessApp(). This object provides methods to interact with, and receive information from, the assessment wrapper.
Add a custom color scheme to the accessibility panel color scheme list.
Requires show_accessibility with show_colourscheme to be set in the Assess API initialization object.
Requires test:ready status before being used. This can be accomplished by either listening to the test:ready event using the on() public method, or using the app readyListener.
At least one valid color replacement needs to be included to be a valid color scheme.
See the accessibility panel knowledge base article for more information.
| Parameters | |
|---|---|
palettes |
Type:
Array[AccessibilityPalette] An array of objects containing accessibility color palette data. |
assessApp.addAccessibilityPalettes([
{
"name": "Blue Paper",
"colors": {
"content-background'": "rgb(123, 123, 123)",
"content-color": "#371B33",
"content-color-hover'": "#52284C",
"button-background-hover": "#BCDCD8",
"button-background": "#52284C",
"button-background-highlight": "#7B3D72",
"buttonbackground-highlight-hover": "#A45198",
"button-color": "#E4F1EF",
"button-color-highlight": "#F2F8F7",
"content-color-subheading": "#52284C",
"progress-color": "#52284C",
"content-border": "#52284C",
"widget-background": "#AFD5D0",
"widget-background-toolbar": "#AFD5D0"
}
}
]);| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
options |
Type:
object
|
||||||||
assessApp.append({
// optional - if not set, additional questions/features will be appended
// to the end of assess app's container
"element": document.querySelector('.additional-widget-wrapper'),
"features": [{
"type": "calculator",
"mode": "basic"
}],
"questions": [{
"type": "plaintext"
}]
}).then(function (data) {
// suffixed with 0, 1, ...n if there are many features with the same "type"
var newCalculatorInstance = data.features['calculator-0'];
// suffixed with 0, 1, ...n if there are many questions with the same "type"
var newPlaintextInstance = data.questions['plaintext-0'];
// User now can interact with appended widgets through their public methods
// Toggle visibility of current calculator instance
newCalculatorInstance.toggle();
}).catch(function (error) {
throw error;
});assessApp.audioPlayer()
.then(function (player) {
player.volume.set(0.5);
player.play('MP3_file.mp3');
})
.catch(function () {
console.log('Cannot get assess audio player');
});Obtains the application instance for the Events API.
Note Events API must be enabled on your consumer for this to work.
| Parameters | |
|---|---|
itemReference |
Type:
string The item reference. |
0.25 if they're on the second item of an eight item activity; 0.625 if they're on the fifth item; and 0.125 if they go back to the first item.Obtains a base64 encoded string containing current responses data.
This data can also be obtain in a failed submission event as outlined on our knowledge base.
intro_item has been set, this method will return false until the "Start" button has been clicked.Sets accessibility properties. It is obligatory to define show_accessibility (with both show_colourscheme and show_fontsize) in Assess API JSON to use this method.
Requires test:ready status before being used. This can be accomplished by either listening to the test:ready event using the on public method, or using the app readyListener.
| Parameters | |||||||
|---|---|---|---|---|---|---|---|
options |
Type:
object
|
||||||
// Via test:ready event
assessApp.on('test:ready', function () {
assessApp.setAccessibility({
"fontSize": 'xxlarge',
"contrast": 'white-on-black'
});
assessApp.setAccessibility({
"fontSize": 'small',
"contrast": '1'
});
});
// Via readyListener
assessApp = LearnosityAssess.init(initOptions, 'learnosity_assess', {
readyListener: function () {
LearnosityAssess.addAccessibilityPalettes([{
"name": 'Example Palette',
"colors": {
// ...
}
}]);
assessApp.setAccessibility({
"fontSize": 'small',
"contrast": 'Example Palette'
});
}
});Sets the height of Assess container.
Requires test:ready status before being used. This can be accomplished by either listening to the test:ready event using the on public method, or using the app readyListener.
If used with regions configuration that has the right region enabled, the minimum height possible will match the height of the right region.
| Parameters | |
|---|---|
height |
Type:
integer The height in pixels. |
intro_item has been configured to programmatically "Start" the activity.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 quesiton 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: |
questionsApp
The following methods are accessed via the questionsApp object returned by itemsApp.questionsApp(). This object provides methods to interact with, and receive information relating to questions used within the assessment.
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.
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 | GroupScoreMasking 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.
|
Note
This method can only be used in Local Device Assessment.
Check if there is any unsynchronized local device assessment responses stored inside the current device's indexedDB.
| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
settings |
Type:
object
|
||||||||
questionsApp.needsPushing({
security: {
consumer_key: '[CONSUMER KEY]',
domain: '[DOMAIN]',
signature: '[SIGNED REQUEST]',
timestamp: '[CURRENT TIMESTAMP]',
user_id: '[USER ID]'
},
success: function () {
console.log('Successfully synchronized all stored responses');
},
error: function (e) {
console.log('Error', e);
}
});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. |
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.off("beforeReady");
//Removes event listeners for the 'changed' event.Set up an event listener.
| Parameters | |
|---|---|
eventName |
Type:
string Name of the event that you want to listen to. |
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.on("beforeReady", function() {
console.log("The preview data was changed.");
}); // Sets up a recurring event listener for the 'beforeReady' 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. |
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.once("beforeReady");
//Sets up a one-time listener for the 'beforeReady' event with this Question app instance.Allows access to a question object for each question available in the activity.
Render all Math content on the page manually.
Empty the Questions API instance's all stored internal references.
Note that calling reset will not remove the rendered questions on the page.
Recapture the initialized question
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.
Note
This method can only be used in Local Device Assessment.
Synchronize all unsynchronized local device assessment responses stored inside the current device's indexedDB.
| Parameters | |||||||||
|---|---|---|---|---|---|---|---|---|---|
settings |
Type:
object
|
||||||||
questionsApp.push({
security: {
consumer_key: '[CONSUMER KEY]',
domain: '[DOMAIN]',
signature: '[SIGNED REQUEST]',
timestamp: '[CURRENT TIMESTAMP]',
user_id: '[USER ID]'
},
success: function () {
console.log('Successfully synchronized all stored responses');
},
error: function (e) {
console.log('Error', e);
}
});item
The following methods are accessed via the item object returned by itemsApp.items() or itemsApp.item("item_reference"). This object provides methods to push events specifically related to an Item, for later reporting purposes.
Publishes an event for the item to Events API. In order to use this function "events" must be set to true in the request object.
Note Events API must be enabled on your consumer for this to work.
itemsApp.item('item1A').publishEvent('progressed');Load the next attempt data row.
This method will load the very first dynamic content if it has reached the last index.
itemsApp.item('item1A').nextAttempt();Load the previous attempt data row.
This method will load the very last dynamic content if it has reached the beginning (index 0).
itemsApp.item('item1A').previousAttempt();Returns the index of the current attempt.
itemsApp.item('item1A').currentAttemptIndex();Count the total number of attempts so far.
itemsApp.item('item1A').totalAttempts();question
The following methods are accessed via the question object returned by itemsApp.questions() or itemsApp.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 an object that contains question attempt status according to the response.
Version added: v2020.2.LTS
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, for the mcq Question type only. 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 the mcq Question type.
Returns initialization data used by the question instance.
Returns a response object containing the current student's input response for the question instance. If the student didn't attempt the question, returns null.
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 question instance has been rendered.
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();
Manually renders a question instance if it has not already been rendered, e.g. if the activity has been configured to defer rendering. Returns true if the rendering happens successfully, and false if it hasn't, e.g. if the question was already rendered.
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.
| 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 itemsApp.features() or itemsApp.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
|
||||||
Returns whether or not the feature instance has been rendered.
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.
Manually renders a feature instance if it has not already been rendered, e.g. if the activity has been configured to defer rendering. Returns true if the rendering happens successfully, and false if it hasn't, e.g. if the feature was already rendered.
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.
Objects
| Properties: | |
|---|---|
hide |
Type:
function() Hides the dialog. |
show |
Type:
function() Shows the dialog. |
See Questions API feature configuration options for more information.
A list of modal dialogs used in the Assess player. Methods on each DialogObject can be used to show or hide the corresponding modal dialog.
| Properties: | |
|---|---|
accessibility |
Type:
DialogObject Allows selection of an accessible color scheme, adjustment of font size, and provides instructions on how to adjust zoom. |
assetUploadError |
Type:
DialogObject Displays an error when there has been an issue uploading a media asset as a response. |
configuration |
Type:
DialogObject Also known as the Administration Panel, this dialog allows an administrator to save and quit a session; exit and discard a session; and extend session time. See administration panel knowledge base article for more information. |
custom |
Type:
DialogObject Custom dialogs can be used to display messages to users during their assessment. See custom dialogs knowledge base article for more information. |
error |
Type:
DialogObject Displays messages for errors that may occur during a session. |
idleTimeout |
Type:
DialogObject When enabled, this dialog will be shown after a number of seconds of inactivity. Once shown, the user has limited time to close the dialog to continue with the activity. Failing to close the dialog in time, the current progress will be saved and the activity will be discarded. See idle_timeout configuration for more information. |
menu |
Type:
DialogObject At smaller widths, such as on phone screens, this dialog represents the "hamburger" style menu and contains the various navigation elements that have been configured. See navigation configuration for more information. |
moduleLoadError |
Type:
DialogObject Displays an error when parts of the Learnosity app have failed to load due to connectivity issues, and provides an option for the user to reload the page to try again. |
pause |
Type:
DialogObject Displays a message when the activity is paused and allows the user to resume an activity / unpause. |
reviewScreen |
Type:
DialogObject The review screen that is usually presented at the of an activity. Allows filtered display of unattempted, partially attempted, and/or flagged items; and navigation to these items. Also allows save and submit of an activity. |
| Properties: | |
|---|---|
[featureReference] |
Type:
FeatureJson The JSON configuration for a feature. |
| Properties: | |
|---|---|
[featureReference] |
Type:
feature |
| Properties: | |
|---|---|
[itemReference] |
Type:
ItemMetadata |
Promise that is resolved when navigation completes, or rejected if navigation was interrupted (e.g. the student may cancel navigation via the warning_on_change dialog).| Properties: | |
|---|---|
goto |
Type:
function() Navigates to the specified item, given an item reference or zero-based index as an argument. Returns: Promise |
next |
Type:
function() Navigates to the next item in the activity. Returns: Promise |
previous |
Type:
function() Navigates to the previous item in the activity. Returns: Promise |
| Properties: | |
|---|---|
sheet_reference |
Type:
string |
widget_reference |
Type:
string |
| Properties: | |
|---|---|
[widgetReference] |
Type:
WidgetMetadata The metadata for a question or feature. |
| Properties: | |
|---|---|
colors |
|
name |
Type:
string A name that describes the palette. |
| Properties: | |
|---|---|
button-background |
Type:
string Hex or RGB color code. |
button-background-highlight |
Type:
string Hex or RGB color code. |
button-background-highlight-hover |
Type:
string Hex or RGB color code. |
button-background-hover |
Type:
string Hex or RGB color code. |
button-color |
Type:
string Hex or RGB color code. |
button-color-highlight |
Type:
string Hex or RGB color code. |
content-background |
Type:
string Hex or RGB color code. |
content-background-correct |
Type:
string Hex or RGB color code. |
content-background-highlight |
Type:
string Hex or RGB color code. |
content-background-highlight-hover |
Type:
string Hex or RGB color code. |
content-background-incorrect |
Type:
string Hex or RGB color code. |
content-background-selected |
Type:
string Hex or RGB color code. |
content-border |
Type:
string Hex or RGB color code. |
content-border-correct |
Type:
string Hex or RGB color code. |
content-border-focus |
Type:
string Hex or RGB color code. |
content-border-incorrect |
Type:
string Hex or RGB color code. |
content-color |
Type:
string Hex or RGB color code. |
content-color-active |
Type:
string Hex or RGB color code. |
content-color-hover |
Type:
string Hex or RGB color code. |
content-color-link |
Type:
string Hex or RGB color code. |
content-color-link-hover |
Type:
string Hex or RGB color code. |
content-color-link-visited |
Type:
string Hex or RGB color code. |
content-color-neutral |
Type:
string Hex or RGB color code. |
content-color-subheading |
Type:
string Hex or RGB color code. |
content-color-toolbar |
Type:
string Hex or RGB color code. |
content-color-widget |
Type:
string Hex or RGB color code. |
progress-background |
Type:
string Hex or RGB color code. |
progress-color |
Type:
string Hex or RGB color code. |
well-background |
Type:
string Hex or RGB color code. |
well-background-toolbar |
Type:
string Hex or RGB color code. |
well-background-grayed |
Type:
string Hex or RGB color code. |
well-background-highlight |
Type:
string Hex or RGB color code. |
well-background-warning |
Type:
string Hex or RGB color code. |
well-color |
Type:
string Hex or RGB color code. |
well-color-grayed |
Type:
string Hex or RGB color code. |
well-color-highlight |
Type:
string Hex or RGB color code. |
well-color-toolbar |
Type:
string Hex or RGB color code. |
well-color-warning |
Type:
string Hex or RGB color code. |
widget-background |
Type:
string Hex or RGB color code. |
widget-background-active |
Type:
string Hex or RGB color code. |
widget-background-hover |
Type:
string Hex or RGB color code. |
widget-background-toolbar |
Type:
string Hex or RGB color code. |
| Properties: | |
|---|---|
then |
Type:
function() Takes a success callback function that resolves the promise with an AppendData object as its parameter. |
catch |
Type:
function() Takes a rejection callback function that rejects the promise with an error as its parameter. |
| Properties: | |
|---|---|
features |
Type:
AppendDataFeatures An object containing feature objects. Each FeatureObject will be prefixed with "[feature type]-[index of feature]", e.g. appendData.features['calculator-0']. |
questions |
Type:
AppendDataQuestions Each QuestionJson object will be prefixed with "[question type]-[index of question]", e.g. appendData.questions['shorttext-0']. |
appendData.features['calculator-0'].| Properties: | |
|---|---|
[featureKey] |
Type:
FeatureJson |
appendData.questions['shorttext-0'].| Properties: | |
|---|---|
[questionKey] |
Type:
QuestionJson |
| Properties: | |
|---|---|
then |
Type:
function() Takes a success callback function that resolves the promise with the Assess API audio player as its parameter. |
catch |
Type:
function() Takes a rejection callback function that rejects the promise with an error as its parameter. |
| Properties: | |
|---|---|
hide |
Type:
function() Hides the dialog. |
show |
Type:
function() Shows the dialog. |
A list of modal dialogs used in the Assess player. Methods on each DialogObject can be used to show or hide the corresponding modal dialog.
| Properties: | |
|---|---|
accessibility |
Type:
DialogObject Allows selection of an accessible color scheme, adjustment of font size, and provides instructions on how to adjust zoom. |
assetUploadError |
Type:
DialogObject Displays an error when there has been an issue uploading a media asset as a response. |
configuration |
Type:
DialogObject Also known as the Administration Panel, this dialog allows an administrator to save and quit a session; exit and discard a session; and extend session time. See administration panel knowledge base article for more information. |
custom |
Type:
DialogObject Custom dialogs can be used to display messages to users during their assessment. See custom dialogs knowledge base article for more information. |
error |
Type:
DialogObject Displays messages for errors that may occur during a session. |
idleTimeout |
Type:
DialogObject When enabled, this dialog will be shown after a number of seconds of inactivity. Once shown, the user has limited time to close the dialog to continue with the activity. Failing to close the dialog in time, the current progress will be saved and the activity will be discarded. See idle_timeout configuration for more information. |
menu |
Type:
DialogObject At smaller widths, such as on phone screens, this dialog represents the "hamburger" style menu and contains the various navigation elements that have been configured. See navigation configuration for more information. |
moduleLoadError |
Type:
DialogObject Displays an error when parts of the Learnosity app have failed to load due to connectivity issues, and provides an option for the user to reload the page to try again. |
pause |
Type:
DialogObject Displays a message when the activity is paused and allows the user to resume an activity / unpause. |
reviewScreen |
Type:
DialogObject The review screen that is usually presented at the of an activity. Allows filtered display of unattempted, partially attempted, and/or flagged items; and navigation to these items. Also allows save and submit of an activity. |
| Properties: | |
|---|---|
[featureReference] |
Type:
FeatureJson |
See items initialization options for more information.
| Properties: | |
|---|---|
metadata |
Type:
object The item's metadata. |
[widgetReference] |
Type:
WidgetMetadata The metadata for a question or feature. |
"assess" as the rendering_type.| Properties: | |
|---|---|
checkImages |
Type:
function() |
flag |
Type:
function() Sets an item as flagged (marked) or not. |
retryLoadImages |
Type:
function() |
| Properties: | |
|---|---|
[itemReference] |
Type:
QuestionsResponses An object containing the current student's responses, keyed by question reference (response ID). |
| Properties: | |
|---|---|
[itemReference] |
Type:
ItemJson The JSON representation of an item. |
| Properties: | |
|---|---|
[itemReference] |
Type:
ItemMetadata The metadata for an item and its widgets. |
Promise that is resolved when navigation completes, or rejected if navigation was interrupted (e.g. the student may cancel navigation via the warning_on_change dialog).| Properties: | |
|---|---|
goto |
Type:
function() Navigates to the specified item, given an item reference or zero-based index as an argument. Returns: Promise |
next |
Type:
function() Navigates to the next item in the activity. Returns: Promise |
previous |
Type:
function() Navigates to the previous item in the activity. Returns: Promise |
| Properties: | |
|---|---|
[questionReference] |
Type:
CurrentResponse |
| Properties: | |
|---|---|
[questionReference] |
Type:
Score |
| Properties: | |
|---|---|
[questionReference] |
Type:
QuestionJson |
| Properties: | |
|---|---|
[questionReference] |
Type:
Question |
| Properties: | |
|---|---|
sheet_reference |
Type:
string |
widget_reference |
Type:
string |
| Properties: | |
|---|---|
[widgetReference] |
Type:
WidgetMetadata The metadata for a question or feature. |
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 |
type |
Type:
string |
value |
Type:
string | array[*] |
| 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: | |
|---|---|
code |
Type:
integer
Possible values:
|
message |
Type:
string
Possible values:
|
| Properties: | |
|---|---|
perQuestion |
Type:
string
Determines whether question-level distractor rationale are displayed. Question-level distractor rationale content is defined for each question in
Possible values:
Default: |
perResponse |
Type:
string
Determines whether response-level distractor rationale are displayed. Response-level distractor rationale content is defined for each question in
Note
This only applies to Question types that support the
Possible values:
Default: |
| Properties: | |
|---|---|
hasReachedMinLimit |
Type:
boolean / null If the Question has If the Question does not have |