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.

Question Editor API Initialization

This article details the properties that are passed as parameters to the window.LearnosityQuestionEditor.init() method to initialize Question Editor API.

This method is the starting point to initializing and rendering Question Editor API, and as you can see in the example below, takes three key parameters:

The Initialization object is mandatory.

var initOptions = {
    "assetRequest": function(mediaRequested, returnType, callback, attributes) {
        // Do something.
    },
    "configuration" : {
        "consumer_key": "ts34Rdc45SWE34f"
    },
    "label_bundle": {
        // question attributes
        "stimulus": "Compose question",
        "options": "Options",
        "validation.alt_responses.score": "Points",
    },
    "question_type_templates": {
        "mcq": [{
            "name": "MCQ - Custom Style",
            "reference": "customMCQ",
            "group_reference": "mcq",
            "description": "Multiple Choice question with block style and predefined options.",
            "defaults": {
                "options": [{
                    "label": "Dublin",
                    "value": "1"
                }, {
                    "label": "Bristol",
                    "value": "2"
                }, {
                    "label": "Liverpool",
                    "value": "3"
                }, {
                    "label": "London",
                    "value": "4"
                }],
                // A newly added option will have the default label "New Label"
                "options[]": "New Label",
                "ui_style": {
                    "type": "block",
                    "columns": 1,
                    "choice_label": "upper-alpha"
                }
            }
        }]
    },
    "ui": {
        "layout": {
            "global_template": "edit_preview",
            "responsive_edit_mode": {
                "breakpoint": 800 // If the container width becomes less than 800px then switch to edit layout
            }
        }
    },
    "widget_type": "response"
};

var hook = ".my-editor";

var callbacks = {
    "readyListener": function () {
        // Question Editor API sucessfully loaded according to pased init options
        // we can now reliably start calling public methods and listen to events
        questionEditorApp.on("widget:ready", function () {
            // widget has changed, probably as a result of calling setWidget()
        });
    },
    "errorListener": function (e) {
        //callback to occur on error
        console.log("Error code ", e.code);
        console.log("Error message ", e.message);
        console.log("Error name ", e.name);
        console.log("Error name ", e.title);
    }
};

var questionEditorApp = LearnosityQuestionEditor.init(initOptions, hook, callbacks);

The Initialization object allows several UI and Question type customizations definable by the host environment. This is possible using the structure described below.

Properties

= mandatory property

Properties
assetRequest

function

If defined the Editor will display a directory/file icon. I.e. "..." in fields where media is supported, as well as binding to the "insert image" button in the html WYSIWIG editor. If the icon is clicked by an author the function is called. 

"assetRequest": function( mediaRequested,
                              returnType,
                              callback ,
                              attributes) {
    // myfunction that opens an asset
    // browser or uploader and then calls
    // callback(URL|HTML|UrlHeightWidth)
},
// example function to be called by assetRequest
var assetRequestFunction = function(mediaRequested, returnType, callback) {
if (mediaRequested === 'image') {
    var $modal = $('.modal.img-upload'),
    $images = $('.asset-img-gallery img'),
    imgClickHandler = function () {
        if (returnType === 'HTML') {
            callback('<img src="' + $(this).data('img') + '"/>');
        } else {
            callback($(this).data('img'));
        }
        $modal.modal('hide');
        $images.off('click', imgClickHandler);
    };
    $images.on('click', imgClickHandler);
    $modal.modal({
        backdrop: 'static'
    });
}
base_question_type

object

Use this config option to modify the behaviour and appearance of all question types. For example, if you wanted to hide certain attributes in all question types, use this config option. It's also worth looking at the knowledge base article on finding attribute paths.

See the knowledge base article on base_question_type, question_types and question_type_templates for more information.

configuration

object

An object containing app configuration.

custom_question_types

object

This config allows you to use Question Editor as a WYSIWYG tool for creating and previewing custom feature content. Provide the custom_question_types config to edit and interact with custom feature types in Question Editor as if they were native Learnosity feature types.

See Authoring custom questions/features with Learnosity Question Editor for more information.

custom_feature_types

object

This config allows you to use Question Editor as a WYSIWYG tool for creating and previewing custom feature content. Provide the custom_feature_types config to edit and interact with custom feature types in Question Editor as if they were native Learnosity feature types.

See Authoring custom questions/features with Learnosity Question Editor for more information.

custom_metadata

object

You can use custom metadata to store additional information relating to a question. For example, you could use custom metadata if you wanted authors to be able to relate the question to an activity in their LMS. If you customize Question layouts, you can specify a div element with data-lrn-qe-custom-metadata to choose where the metadata fields are rendered. If no such element exists in the layout, fields specified in custom_metadata will appear at the bottom of the edit panel.

The data is stored in the metadata attribute of the question JSON.

dependencies

object

An object containing Questions API settings.

group_defaults

boolean

This config option allows you to show or hide the "default" Learnosity template groups in the tile view (e.g. Multiple Choice, Fill in the Blanks (Cloze)). You can see the default groups here.

How the tile view is affected depends on the values set for several other initialization options, primarily question_type_groups - see below for this behavior.

  • If this option is set to true and question_type_groups is not set (i.e. the default values in both cases) the default groups will be shown.
  • If this option is set to true and question_type_groups is set, groups will extend the defaults.
  • If this option is set to false, and question_type_groups is not set, no groups will be shown at all.
  • If this option is set to false, and question_type_groups is set, then only these defined groups will be shown.

For a comprehensive overview of tile view customization, including behavior when customizing the template defaults (via template_defaults and question_type_templates) please see the help article Customizing the Tile View With Author API

Default: true

label_bundle

object

This config allows you to override the Question Editor API labels. This feature can be used for internationalisation or simply for tailoring QE to use phrases your authors are accustomed to. You can also specify placeholder labels in the label bundle.
To make it easy to set labels, you can use the debug flag (see below) which will show the path for each of the labels in the widget.

Any labels you omit from the label_bundle config will use the default value.

See internationalization article with instructions for finding label bundle paths for more information.

premium

object

Some of the question types, or features are defined as premium, and therefore are hidden from authoring unless explicitly enabled. This configuration works as an allowlist, and allows to specify them one by one. Please check the example configuration below. 

premium: {
    question_types: ['video'],
    attributes: {
        fileupload: ['allow_video']
    }
}
question_types

object

Use this config option to modify the behaviour and appearance of Learnosity's question types. For example, if you wanted to change the name of the MCQ question type in the tile view, you can use this config option. Settings in question_types override or extend settings in base_question_type.

See knowledge base article on base_question_type, question_types and question_type_templates for more information.

question_type_groups

array[object]

Use this config option to change the default widget type groups shown in the tile view (e.g. Multiple Choice, Fill in the Blanks (Cloze)).
Supply an array with objects defining a group. Each group needs a unique identifier and a name.
If you want to override the name and/or icon for the default groups, find the reference (look for the data-groupreference attribute in the DOM) and specify a new name and/or icon. Any new references will be added as additional groups in the tile view.

question_type_templates

object

Optional object to customize question type templates. Each template acts as a variation of its base question type. Each object is identified by a key which represents the question type (e.g mcq, shorttext). The value must be an array of objects (in order to allow multiple variations of each question type).

See knowledge base article on base_question_type, question_types and question_type_templates for more information.

simple_feature_templates

array[object]

Optional array of objects to customize simple feature templates within the simple feature modal as listed in the simple feature modal article. The following attributes are customizable name, reference, defaults. The attribute reference must at least be provided for each simple feature you wish to display in the simple feature modal. The ordering of references in the array is reflected in the navigation ordering of the simple feature modal.

rich_text_editor

object

This is the initialization option which determines the rich text editor that will be used by the Question Editor API. All customizable attributes are defined in this object.

template_defaults

boolean

This config option allows you to selectively show or hide the "default" Learnosity templates in the tile view (E.g. "Multiple choice - multiple response", "True or false").

How the tile view is affected depends on the values set for several other initialization options, primarily question_type_templates - see below for this behavior.

  • If this option is set to true and question_type_templates and question_type_groups are not set (I.e. the default values for each), the default templates will be shown, in their default group.
  • If this option is set to true and question_type_templates and/or question_type_groups are set, these options will be appended to the defaults.
  • If this option is set to false and question_type_templates is not set, only the raw question types will be shown (Same as the questions seen in advanced_group when this init option is set.)
  • If this option is set to false and question_type_templates is set, the custom questions will be be shown along with the raw instances of the other question types.
  • If this option is set to false, an image attribute must be set in each template defined in question_type_templates for display in the tile view.

For a comprehensive overview of tile view customization, including behavior when customizing the group defaults (via group_defaults and question_type_groups) please see the help article Customizing the Tile View With Author API

Default: true

ui

object

A list of options to customize visual elements of Question Editor.

See knowledge base for more information.

widget_json

QuestionJson | FeatureJson

JSON used to initialize the Question Editor with pre-existing content.

The Question Editor will render in tile view of question/feature when initialized without widget_json, widget_json allow you to go to edit page of specified question/feature directly.

widget_metadata

object

An option to be used in conjunction with widget_json. If name and template_reference is specified, question/feature will display in given template. Question Editor tries to find a template with the given reference first. If not found, it tries to find one with the given name.

widget_type

string

Determines which supported Learnosity widget type definitions will be loaded in tile view.

Possible values:
  • "response"
  • "feature"

The second parameter passed to window.LearnosityQuestionEditor.init() is a string, containing a full CSS selector to an element on the HTML page. Each example below could be a valid value:

#learnosity_questioneditor // CSS selector based on id of an element
.learnosity_questioneditor // CSS selector based on a class of an element

This value tells Question Editor API where to render itself on the page.

Note If the HTML element selector is not provided, Question Editor API will attempt to look for the element with a class "learnosity-question-editor".

The Callbacks object contains optional callback functions that allow detection of the 'ready' status of a Question Editor API instance and any errors encountered.

These events can be handled by defining a readyListener function and an errorListener function respectively.

Properties
readyListener

function

Function to be called when the API has been successfully initialised. In most circumstances, before calling any public method, or listening to any public event, you should always wait until readyListener is fired.

There may be some events though, which can be fired earlier depending on the global layout and starting view.

See events documentation page for more information.

errorListener

function

Function to be called on a response editor error event.