Methods

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

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 #learnosity_assess by default.

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.

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

Add new items to the current activity.
Parameters
options
Type: object
Properties:
items
Type: array[string|object]
An array of item references (or item objects).

See Items API's initOptions items for more information.

removePreviousItems
Type: boolean
If true, this will remove all items before adding the new ones.
Default: true

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.

Returns: assessApp
Obtains a list of Item references that have been attempted in the current activity.
Returns: array[string]
Obtains a list of Question references that have been attempted in the current activity.
Returns: array[string]
Allows access to a list of dialogs available in the player, if using rendering_type: assess.
Returns: DialogsList

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.

Returns: eventsApp
Obtains an object to interact with a specific feature.
Parameters
featureReference
Type: string
Reference of the feature that you want to interact with.
Returns: feature
Allows access to a FeatureObject for each feature instance available in the activity.
Returns: FeaturesList
Obtains the full object used to initialize Items API, including the template specified by activity_template_id, if defined.
Returns: object 
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.

Returns: ItemJson
Obtains the JSON object for each Feature of the activity.
Returns: featuresJson

Obtains an object containing scores for all items in the activity using rules determined by the item scoring type:

  • per-question
  • dichotomous
  • dependent

See item scoring for more information.

Returns: Object
Obtains the JSON object for each Item of the activity, keyed by each unique item reference.
Returns: object 
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: []
    }
}
Obtains JSON map of the items and their metadata.
Returns: ItemsMetadata
Returns metadata for all questions and features in which metadata is defined.
Obtains the JSON object for each Question of the activity, keyed by each unique question reference.
Returns: object 
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"
            ]
        }
    }
}
Obtains an object containing responses for each Question that has been attempted.
Returns: object 
var responses = itemsApp.getResponses();
console.log(responses);

{
    1fcc9839e559d98af05bcf9a3d863960: {
        apiVersion: "v2.109.2",
        revision: 1,
        type: "array",
        value: [0,1,2,3,4]
    }
}
Obtains an object containing scores for all auto-scorable Questions in the activity, keyed by each unique question reference.
Returns: object 
var scores = itemsApp.getScores();
console.log(scores);

{
    10000: {
        max_score: 1,
        score: null  // not attempted
    }
}

Retrieves all tags for Items in the current activity. Passing true for the format returns the (deprecated) TagsV0 structure.

Note getTags requires retrieve_tags to be set to true.

Parameters
format
Type: boolean
Passing true for the format returns the (deprecated) TagsV0 structure.
Returns: object

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
Properties:
currentSection
Type: boolean
Passing true to get the elapsed time of the current active section.
Returns: integer
Returns an item object with public methods specific to that item or false if the requested item is not found.
Parameters
itemReference
Type: string
Reference of the item you want to access
Returns: object | false
Returns an object with methods to navigate between items if using rendering_type: assess.
Returns: ItemsObject

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);
Returns a facade object with methods, for a specific question.
Parameters
response_id
Type: string
The reference for the question instance (response ID).
Returns: object
Obtains an object of all questions in the activity, keyed by each unique question reference.
Returns: object
Obtains the application instance for the underlying Questions API.
Removes all rendered Items from DOM, returning it to its previous state.

Confirms that all responses have been saved.

This includes coverage for ongoing audio recording and uploading.

Returns: boolean

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);
Obtains the list of Questions that can not be saved in the current activity. Usually related to exceeding the word count in long text or plain text question types.
Parameters
responseCallback
Type: callback()
Containing the response_ids that can not be saved.
Returns: array - (via callback) of 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:

  • 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 response
Default: detailed
Returns: object - (via callback)

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
Properties:
showCorrectAnswers
Type: boolean
Default: false

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
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"
        }
    }
]);
Append additional questions/features to the desired DOM element. The appended feature and question instances can then be stored and interacted with through feature instance public methods and question instance public methods respectively.
Parameters
options
Type: object
Properties:
element
Type: object
A DOM element into which additional questions/features should be rendered. If no DOM element is provided, the created questions/features will be appended to the end of Assess API's container.
features
Type: Array[FeatureJson]
An array of feature configuration objects.
questions
Type: Array[QuestionJson]
An array of question configuration objects.
Returns: AppendPromise
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;
});
Allows access to the global Assess API audio player. This can be used to play audio files programmatically.
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.

Returns: eventsApp
Obtains the position (zero based index) of a given item.
Parameters
itemReference
Type: string
The item reference.
Returns: integer or -1 if the requested item reference is not found.
Obtains an object containing responses for each question that has been attempted, grouped by item reference.
Returns: ItemResponses
The progress of the student through the activity, e.g. a student will have a progress of 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.
Returns: float

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.

Returns: string
Checks whether the test has started. If an 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
Properties:
fontSize
Type: string

Available options:

  • 'small'
  • 'normal'
  • 'large'
  • 'xlarge'
  • 'xxlarge'
contrast
Type: string

Available options:

  • 'black-on-white'
  • 'rose-on-green'
  • 'yellow-on-blue'
  • 'black-on-rose'
  • 'light-gray-on-dark-gray'
  • 'white-on-black'
 
// 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.
Launch the test when it is ready, used if an intro_item has been configured to programmatically "Start" the activity.

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

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

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

Returns: Features

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

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.

Note This method can only be used in Local Device Assessment

Check if there is any unsynced local device assessment responses storing inside current device's indexedDB

Parameters
settings
Type: object
Properties:
security
Type: object

The security object of the request

See Security and authentication for more information.

success
Type: function()

The success callback of the request
error
Type: function()

The error callback of the request

 
questionsApp.needsPushing({
    security: {
        consumer_key: '[CONSUMER KEY]',
        domain: '[DOMAIN]',
        signature: '[SIGNED REQUEST]',
        timestamp: '[CURRENT TIMESTAMP]',
        user_id: '[USER ID]'
    },
    success: function () {
        console.log('Successfully sync 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.

Returns: QuestionsList

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

Sync all unsynced local device assessment responses storing inside current device's indexedDB

Parameters
settings
Type: object
Properties:
security
Type: object

The security object of the request

See Security and authentication for more information.

success
Type: function()

The success callback of the request
error
Type: function()

The error callback of the request

 
questionsApp.push({
    security: {
        consumer_key: '[CONSUMER KEY]',
        domain: '[DOMAIN]',
        signature: '[SIGNED REQUEST]',
        timestamp: '[CURRENT TIMESTAMP]',
        user_id: '[USER ID]'
    },
    success: function () {
        console.log('Successfully sync all stored responses');
    },
    error: function (e) {
        console.log('Error', e);
    }
});

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();

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.

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 an object that contains question attempt status according to the response.

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, 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: QuestionJson

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: 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 question instance has been rendered.

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, indicating if it is correct or not.
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.

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.

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();

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.

Returns: boolean

Reset the question's validation UI style to the original.

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.

Returns: SimpleFeaturesList

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
When true, correct answers will be displayed with the validation UI.
Default: false
showDistractorRationale

Determines whether distractor rationale are displayed with the validation UI.

When omitted, the show_distractor_rationale configuration from the Initialization object will be used in its place.

feedbackAttempts
Type: boolean
When true, this will increment feedbackAttemptCount or do nothing if the feedbackAttemptCount limit has already been reached.
Default: false

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.

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.

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

Returns whether or not the feature instance has been rendered.

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

Returns: boolean

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.

Returns: SimpleFeaturesList

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.

Objects

object
An object containing public methods for an instance of a dialog in the player.
Properties:
hide
Type: function()
Hides the dialog.
show
Type: function()
Shows the dialog.
object
Properties:
accessibility
An object containing public methods for an instance of a dialog in the player.
assetUploadError
An object containing public methods for an instance of a dialog in the player.
configuration
An object containing public methods for an instance of a dialog in the player.
custom
An object containing public methods for an instance of a dialog in the player.

See custom dialogs knowledge base article for more information.

error
An object containing public methods for an instance of a dialog in the player.
idleTimeout
An object containing public methods for an instance of a dialog in the player.
menu
An object containing public methods for an instance of a dialog in the player.
pause
An object containing public methods for an instance of a dialog in the player.
reviewScreen
An object containing public methods for an instance of a dialog in the player.
object
The JSON configuration for a feature.

See Questions API feature configuration options for more information.

object
An object containing JSON for each feature.
Properties:
[featureReference]
The JSON configuration for a feature.
object
An object containing each FeatureObject available in the activity, keyed by their references.
Properties:
[featureReference]
Type: feature
object
The JSON representation of an item.
object
Metadata for each item keyed by item reference.
Properties:
[itemReference]
Type: ItemMetadata
object
An object with methods for navigating across items. Each method returns a 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
object
The metadata for a question or feature.
Properties:
sheet_reference
Type: string
widget_reference
Type: string
object
The metadata for each question and feature, keyed by their references.
Properties:
[widgetReference]
The metadata for a question or feature.
object
Properties:
colors
name
Type: string
A name that describes the palette.
object
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.
Type: string
Hex or RGB color code.
Type: string
Hex or RGB color code.
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.
promise
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.
object
An object containing question and feature objects that allow access to methods of each newly appended question and feature instance.
Properties:
features
An object containing feature objects. Each FeatureObject will be prefixed with "[feature type]-[index of feature]", e.g. appendData.features['calculator-0'].
questions
Each QuestionJson object will be prefixed with "[question type]-[index of question]", e.g. appendData.questions['shorttext-0'].
object
An object containing feature objects. Each FeatureObject will be prefixed with "[feature type]-[index of feature]", e.g. appendData.features['calculator-0'].
Properties:
[featureKey]
object
Each QuestionJson object will be prefixed with "[question type]-[index of question]", e.g. appendData.questions['shorttext-0'].
Properties:
[questionKey]
promise
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.
object
An object containing public methods for an instance of a modal dialog in the Assess player.
Properties:
hide
Type: function()
Hides the dialog.
show
Type: function()
Shows the dialog.
object

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
An object containing public methods for an instance of a modal dialog in the Assess player.
assetUploadError
An object containing public methods for an instance of a modal dialog in the Assess player.
configuration
An object containing public methods for an instance of a modal dialog in the Assess player.
custom
An object containing public methods for an instance of a modal dialog in the Assess player.

See custom dialogs knowledge base article for more information.

error
An object containing public methods for an instance of a modal dialog in the Assess player.
idleTimeout
An object containing public methods for an instance of a modal dialog in the Assess player.
menu
An object containing public methods for an instance of a modal dialog in the Assess player.
pause
An object containing public methods for an instance of a modal dialog in the Assess player.
reviewScreen
An object containing public methods for an instance of a modal dialog in the Assess player.
object
An object containing JSON for each feature.
Properties:
[featureReference]
object
An object containing each feature object available in the activity, keyed by their references.
Properties:
[featureReference]
object
Configuration options for an item.

See items initialization options for more information.

object
The JSON representation of an item.
object
The metadata for an item and its widgets.
Properties:
metadata
Type: object
The item's metadata.
[widgetReference]
The metadata for a question or feature.
object
An object containing methods for an item.
Properties:
checkImages
Type: function()
flag
Type: function()
Sets an item as flagged (marked) or not.
retryLoadImages
Type: function()
object
An object containing responses for each question that has been attempted, grouped by item reference.
Properties:
[itemReference]
An object containing the current student's responses, keyed by question reference (response ID).
object
JSON object, keyed by item reference, for each item of the activity.
Properties:
[itemReference]
Type: ItemJson
The JSON representation of an item.
object
Metadata for each item keyed by item reference.
Properties:
[itemReference]
The metadata for an item and its widgets.
object
An object with methods for navigating across items. Each method returns a 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
object
An object containing the current student's responses, keyed by question reference (response ID).
Properties:
[questionReference]
Type: CurrentResponse
object
An object containing scores for auto-scorable questions, keyed by question reference (response ID).
Properties:
[questionReference]
Type: Score
object
An object containing JSON for each question.
Properties:
[questionReference]
object
An object containing each QuestionObject available in the activity, keyed by their references.
Properties:
[questionReference]
Type: Question
object
The metadata for a question or feature.
Properties:
sheet_reference
Type: string
widget_reference
Type: string
object
The metadata for each question and feature, keyed by their references.
Properties:
[widgetReference]
The metadata for a question or feature.
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
type
Type: string
value
Type: string | array[*]
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:
code
Type: integer
Possible values:
  • 0
  • 1
  • 2
  • 3
message
Type: string
Possible values:
  • "Acceptable"
  • "background noise"
  • "Too quiet"
  • "Too loud"
object
Properties:
perQuestion
Type: string

Determines whether question-level distractor rationale are displayed. Question-level distractor rationale content is defined for each question in metadata.distractor_rationale.

Possible values:
  • "always" will display question-level distractor rationale for any response.
  • "never" will never display question-level distractor rationale.
  • "correct" will only display question-level distractor rationale if the response is correct.
  • "incorrect" will only display question-level distractor rationale if the response is incorrect.
Default: "incorrect"
perResponse
Type: string

Determines whether response-level distractor rationale are displayed. Response-level distractor rationale content is defined for each question in metadata.distractor_rationale_response_level.

Note This only applies to Question types that support the metadata.distractor_rationale_response_level property. See Question Types for futher information.

Possible values:
  • "always" will display distractor rationale for every checked response or non-empty response container.
  • "never" will never display response-level distractor rationale.
Default: "always"
object
Properties:
hasReachedMinLimit
Type: boolean / null

If the Question has min_selection applied, it will return a boolean value according to the Question response.

If the Question does not have min_selection applied, it will return null.