Warning Warning! This is a lower-level API. Lower-level APIs are not recommended for most projects, and may not be available on all plans. See our page on recommended deployment patterns for more information.

Public Methods

This article details the public methods you can use to interact with the Question Editor API. It also covers how to deal with page unload events.

The following methods are accessed via the window.LearnosityQuestionEditor object.

When the <script src="https://questioneditor.learnosity.com"></script> tag is included on the page, the window.LearnosityQuestionEditor object is instantiated, and ready for use.

A method called on window.LearnosityQuestionEditor to instantiate an instance of the Question Editor. Once called, and finished initializing (see callbacks for more info on when the API is considered in 'ready' state), you can use the returned application instance (called questionEditorApp in this documentation) to access its public methods.

This function must be called before any other functionality can be used.

Parameters
initOptions
Type: object

Object containing Question Editor config parameters.

See initOptions for more information.

selector
Type: string

DOM element where Question Editor should be rendered into.

For example, if you pass .my-question-editor as the second argument, you should change the div class value from learnosity-question-editor to my-question-editor.

Default: '.learnosity-question-editor'
callbacks
Type: object

Visit the Question Editor API callback object for detailed documentation on callbacks and its parameters.

The following methods are accessed via the questionEditorApp instance returned by window.LearnosityQuestionEditor.init().

Allows you to modify a specified input based on an attribute path.

For example, if you wanted to set the stimulus but didn't want to change anything else, it would be better to use the attribute method rather than setWidget.

Parameters
attribute_path
Type: string
questionEditorApp.attribute("stimulus");

/* example output - returns object with available functions
{
    {getValue: f, setValue: f, remove: f}
}
*/

To check whether question being edited has valid validation

Returns: ValidationStatusObject
var stimulusAttribute = questionEditorApp.checkValidation(); // { has_validation: true }

Destroy current instance of the Question Editor API app.

This method will also restore the HTML hook which was used to first initialize the app. Remember to delete references to the instance as well. You need to make sure that you don't destroy while Question Editor is still initializing, as this may lead to unexpected results. You should only use destroy() after readyListener is called.

function destroy () {
    questionEditorApp.destroy();
}

returns the JSON currently available in the Editor.

Returns: QuestionJson

returns the metadata JSON of the current widget.

Currently metadata has key template_reference which specifies the template with which the current question is displayed. If a question is displayed within a custom template, the metadata should be saved as part of the question. On editing the question, setWidget should be called with the metadata as second argument, so that the question is displayed as it was at creation time.

Returns: metadataJson

Removes a previously-bound callback function for an event.

When called with no parameters, callbacks for all events are removed.

Parameters
event_name
Type: string

Name of the event that you want to stop listening to.

See events list for more information.

event_callback
Type: function()

If no callback is provided, all callbacks for the event_name will be removed.

context
Type: object

If no context is provided, all callbacks for the event_name, event_callback combination will be removed.

questionEditorApp.off("preview:changed"); //Removes callbacks for the 'preview:changed' event.
questionEditorApp.off(); //Removes callbacks for all events. 

Set up an event listener.

Parameters
event_name
Type: string

Name of the event that you want to listen to.

See events list for more information.

event_callback
Type: function()

Callback function that will be invoked whenever the event is triggered.

context
Type: object

Execution context that will be used for this when the callback function is invoked.

questionEditorApp.on("preview:changed", function() {
    console.log("The preview data was changed.");
}); // Sets up a recurring event listener for the 'preview:changed' event.

Set up an one time event listener. Will fire once and then stop listening.

Parameters
event_name
Type: string

Name of the event that you want to listen to.

See events list for more information.

event_callback
Type: function()

Callback function that will be invoked whenever the event is triggered.

context
Type: object

Execution context that will be used for this when the callback function is invoked.

questionEditorApp.once("editor:ready", function() {
    console.log("The editor has fully loaded.");
}); // Sets up a one-time event listener for the 'editor:ready' event.

Revert Question Editor state to a newer captured state.

Conditions that may prevent operation to be performed:

  • A previous Undo/Redo operation is still running.
  • There are no previous snapshots to revert to.
  • A snapshot is currently being saved.
  • The page has not yet completely loaded.

To know when the undo operation has completed, listen to the revisionHistoryState:change (refer to event types) and watch for when either canUndo or canRedo is true.

Note User must have called undo method before being able to call redo method.

Note If undo method is called and then a change is made to the question, then the redo operation can not be called, as the newer states will have been removed to capture the latest change.

Returns:
Return value types:
boolean
If the operation can not be performed, then false is returned
null
If the operation can be performed, then null is returned
// event to listen - after undo
questionEditorApp.on("revisionHistoryState:change", function (data) {
    console.log(data); //{canUndo: false, canRedo: true}
});

questionEditorApp.redo(); //{canUndo: true, canRedo: false}

To reset data of rendered views and empty the json of given question/feature. For default global layout, the method will set the view back to the widget selection screen. It can optionally pass a widget_type to change between feature and response types in a single instance.

You need to make sure that you don't reset while Question Editor is still initializing, as this may lead to unexpected results. You should only use reset() after readyListener was called.

Parameters
widget_type
Type: string

See widget_type for more information.

document.getElementById('reset').onclick = function () {
    questionEditorApp.reset('feature');
};

Called to determine if the user has made any changes and if it is safe to unload/navigate away from the Questions Editor. It will return true, if content has not been modified after question/feature has been rendered

External code can manually mark the Questions Editor as safe to unload by passing "true" as the first argument to this method.

Parameters
isSafe
Type: boolean

Mark the editor as safe to unload

Returns: boolean

Used to set the metadata of a widget. It only has an effect if called before setWidget. Instead of calling setMetadata and then setWidget, call setWidget with the widget's json and metadata as arguments.

Parameters
metadata

metadata object

Sets JSON to edit in the Question Editor API. The Question Editor API will open the specified question/feature type and pre-populate attributes from the supplied JSON.

The responseJson argument is the JSON Object to set in the editor for editing.

setWidget accepts an object specifying a template_reference key for the template as a second argument. If this is set, the widget is displayed within the template specified by the argument. Use that approach if you have custom template (with hidden sections, fields, etc.) set up as reference of QuestionType inside question_types.

Important: This method should only be called once the Question Editor API is fully loaded. It is provided to allow setting JSON at later stages if needed. If you have not loaded the Question Editor API and want to initialise the API with a specific question/feature type and pre-filled data, you should use the widget_json init option rather than setWidget.

Note User must have called undo method before being able to call redo method.

Parameters
widget_json
Type: object

The widget JSON to be set

widget_template
Type: object

The widget template to be used to render JSON. Template of same question/feature type is supported that is determined by widget_json, otherwise default template is used

Properties:
template_reference
Type: string

The reference of the widget template to be used. Refer to the template reference knowledge base article for more details

Default: First template available for question/feature type
// on clicking the setWidget button, provide the new Response object with a changed picture.
    var responseJson = {
        "type": "highlight",
        "description": "The student needs to mark one of the flower's anthers in the image.",
        "img_src": "http://upload.wikimedia.org/wikipedia/commons/thumb/c/c7/Mono_Lake_Old_Marina_August_2013_012.jpg/320px-Mono_Lake_Old_Marina_August_2013_012.jpg",
        "line_color": "rgb(255, 20, 0)",
        "line_width": "4"
    };

    document.getElementById('setWidget').onclick = function (){
        questionEditorApp.setWidget(
            responseJson,
            {
                "template_reference": "908de244-5c71-4c09-b094-7fb49554f2f9"
            }
        );
    };

Ask preview view (if available) to update the editing question. Should be called when preview view is changed from invisible state to visible state

Revert Question Editor state to a previously captured state.

Conditions that may prevent operation to be performed:

  • A previous Undo/Redo operation is still running.
  • There are no previous snapshots to revert to.
  • A snapshot is currently being saved.
  • The page has not yet completely loaded.

To know when the undo operation has completed, listen to the revisionHistoryState:change (refer to event types) and watch for when either canUndo or canRedo is true.

Returns:
Return value types:
boolean
If the operation can not be performed, then false is returned
null
If the operation can be performed, then null is returned
// event to listen - after modifying any input field
questionEditorApp.on("revisionHistoryState:change", function (data) {
    console.log(data); //{canUndo: true, canRedo: false}
});

questionEditorApp.undo(); //{canUndo: false, canRedo: true}

In the Methods sections above, there are some object definitions which are complex enough to document separately. These are listed below, and linked from the relevant documentation above.

object

A returned instance of attribute e.g. stimulus

Properties:
addArrayItem

To add a new item to array collection type attribute
e.g. options, stems, response_containers

getValue
Type: function()

Get current value of given attribute

Returns: string
remove
Type: function()

To remove given array item, available for node of array collection only
e.g. options[1], stems[0]

setValue

Set value of given attribute

var stimulusAttribute = questionEditorApp.attribute("stimulus");
stimulusAttribute.getValue(); // "[This is stem.]"
stimulusAttribute.setValue("This is new stem!");

var optionsAttribute = questionEditorApp.attribute("options"); // Options is array node like "options": ["choice A", "choice B"]
optionsAttribute.addArrayItem("choice C"); // Create new array item with value "choice C"

var firstOptionAttribute = questionEditorApp.attribute("options[0]");
firstOptionAttribute.remove(); // Remove first array item options[0] ("choice A") from "options" array collection

To add a new item to array collection type attribute
e.g. options, stems, response_containers

Parameters
array_item
Type: string

New array item

Set value of given attribute

Parameters
value
Type: string

Value of attribute object

object

A return object of getMetadata that contains template name and template_reference data

Properties:
name
Type: string

Template name of given question/feature

template_reference
Type: string

Template reference of given question/feature

object

A return object of checkValidation that contains has_validation property which indicates presence of validation

Properties:
has_validation
Type: boolean

Returns false if a widget is not being edited
e.g. item list, item edit or question editor tile views