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.

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": {
                "enabled": true,  // Not necessary as it is enabled by default
                "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

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.

Parameters
mediaRequested
Type: string

Determine the type of media

Possible values:
  • "audio"
  • "image"
  • "video"
returnType
Type: string

Let the function know whether to supply HTML or a URL or an object that contains image's url, width and height.

Possible values:
  • "HTML"
  • "URL"
  • "UrlHeightWidth"
callback
Type: callback(data)

Function that must be executed once the HTML, URL or UrlHeightWidth is ascertained.

Parameters
data
Type: string | UrlHeightWidth
attributes
Type: object

Attributes of media to be used in assetRequest

Properties:
alt
Type: string

The alternative text for an image.

height
Type: string
src
Type: string

The url of an asset.

width
Type: string
"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'
    });
}
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.

Properties:
defaults
Type: object

Change the default values that will be populated when you load the Question Types. (e.g. you could set the default Stimulus for all question types using this config option). In order to set a default value for new array elements, keys with empty brackets [] can be used.

exclude_options
Type: object

Combination of object key and array value to remove unwanted option(s) from dropdown input.

hidden
Type: Array[string]

Define which attributes should be hidden in all question types.

hidden_sections
Type: Array[string]

Define which attribute sections should be hidden in this question type. Section delimiters are shown if question editor's global template is set to "debug".

As you can see in the image above, sections are usually subdivided into ".heading", ".content", ".toggle" and ".divider". If you want to hide all parts of a section, simply specify the section name without a subdivider (e.g. "more_options" will hide "more_options.heading", "more_options.content", "more_options.toggle" and "more_options.divider").

Note hidden_sections will override shown so if you want to only hide some attributes in a section, you will need to individually hide each attribute using hidden. If you'd like to specify your own sections, you can use a custom editor layout.

See the knowledge base article on customizing display of questions for more information.

image_preview_placeholder
Type: string

Define the URL of an image which is displayed as a placeholder in questions which show an image preview. The specified image is shown, if the image source of the question is empty or points to an incorrect url.

See the knowledge base article on customizing display of questions for more information.

shown
Type: Array[string]

Define which hidden by default attributes should be shown in all question types.

shown_sections
Type: Array[string]

Define which attribute sections should be shown in this question type.

Common use cases for shown_sections would be if you want to show the more options content by default (e.g. add "more_options.content" to shown_sections and "more_options.heading" to hidden_sections) or if you want to hide a section except in one particular question type (e.g. put the hidden section in base_question_type and show the section in question_types).

If you'd like to specify your own sections, you can use a custom editor layout.

See the knowledge base article on customizing display of questions for more information.

object

Change the default values that will be populated when you load the Question Types. (e.g. you could set the default Stimulus for all question types using this config option). In order to set a default value for new array elements, keys with empty brackets [] can be used.

Properties:
[key]
Type: *
object

Combination of object key and array value to remove unwanted option(s) from dropdown input.

Properties:
[optionKey]
Type: *
object

An object containing app configuration.

Properties:
consumer_key
Type: string

Pass a consumer key to load consumer specific CSS.

main_container_selector
Type: string

a jQuery type selector, specifying the wrapper element, in which Question Editor is rendered. This is used to calculate modal positions and also to scroll Question Editor into view on navigation.

questionsApiVersion Deprecated
Type: string

Version of the Questions API to use to preview question rendering.

Note This almost never needs to be set as the Question Editor API internally knows the appropriate version of the Questions API to load.

Example: "v2.12"
scroll_container_selector
Type: string

a jQuery type selector, specifying the element which Question Editor should scroll into view on navigation (overwrites main_container_selector for that purpose).

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.

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.

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.

Properties:
[metadataKey]
Type: object
object
Properties:
description
Type: string

A description of the metadata to be captured

name
Type: string

The title of the metadata field as you want it to appear in the editor.

type
Type: string

The type of input to be displayed to the user; a value of "string" will render a basic text input, and a value of "editor" will render a rich text editor, "arrayEditors" will render an array of rich text editors.

custom_metadata: {
    custom_metadata_key: {
        description: 'custom metadata description',
        name: 'custom metadata name',
        type: 'string'
    }
}
object

An object containing Questions API settings.

Properties:
questions_api
Type: object
object
Properties:
init_options
Type: object

Initialization options to be used for Questions API.

version Deprecated
Type: string

Version of the Questions API to use to preview question rendering.

Note This almost never needs to be set as the Question Editor API internally knows the appropriate version of the Questions API to load.

Example: "latest", "V3"
object

Initialization options to be used for Questions API.

Properties:
allow_negative_scores
Type: boolean

An option to allow score to be less than zero

Note allow_negative_scores option is only available with V3+

math_renderer
Type: string

This option allows you to overwrite the math_renderer option inside all questions.

Possible values:
  • "mathjax"
  • "mathquill"
boolean

this config option allows you to selectively show or hide the "default" Learnosity template groups in the UI

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

Default: true
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 knowledge base article on finding label bundle paths for more information.

Properties:
debug
Type: boolean

Setting the attribute "debug" to true will reveal the key being used for all supported UI elements. This is very helpful when creating label bundle config. Label keys in debug mode are prepended by the question type. It is possible to target these directly or to specify general labels without the question type.

[key]
Type: string
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 a whitelist, and allows to specify them one by one. Please check the example configuration below.

Properties:
question_types
Type: Array[string]

Array of premium question type IDs.

Currently the only supported question type ID is video.

attributes
Type: object

List of features organised by question type IDs.

Currently the only supported question type ID is fileupload.

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

List of features organised by question type IDs.

Currently the only supported question type ID is fileupload.

Properties:
[question_type_ID]
Type: Array[string]

Array of premium feature paths within specific question type to be enabled for authoring.

Currently the only supported feature path is allow_video.

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.

Properties:
[questionTypeName]
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.

Types
object

An object to override a question type group

Properties:
group_icon
Type: string

URL containing an image to be shown as the group icon in the tile view. Image will be scaled to 18px by 18px.

name
Type: string

String name to render in the sidebar for this template group.

reference
Type: string

Unique identifier for a group.

template_references
Type: Array[string]

Array of template references used to specify which templates to show, and the order to show them in, within the group in the tile view. If template_references is defined, it overrides the group_reference specified in question_types.

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.

Properties:
[questionTypeName]
Type: Array[QuestionType]

Attributes hidden, hidden_sections, shown, shown_sections, and defaults extend the definitions in question_types. All other attributes are overwritten. The attribute reference must be provided so that setWidget can identify the correct template to use. Learnosity's default question_type_templates already have references as listed in the template reference knowledge article.

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.

Types
object

An object that defines a simple feature template

Properties:
name
Type: string

the name of the simple feature that will appear in the primary navigation of the simple feature modal.

reference
Type: string

Learnosity's simple_feature_templates have references as listed in the template reference knowledge article.

defaults
Type: object

An object that defines the default value for each simple feature attribute in the simple feature layout.

object

This is the initialization option which determines the rich text editor that will be used by the Question Editor API. If type: "none", textarea input will be rendered instead. All customizable attributes are defined in this object.

Properties:
customButtons
Type: Array[CustomButton]

If defined the Editor will display a custom button in it's toolbar. If the button is clicked by an author the function is called.

See custom buttons knowledge base for more information.

custom_styles
Type: Array[CustomStyle]

An array of extra styles to include in the styles dropdown.

See custom styles article for more information.

font_settings
Type: object

Used to set custom font colors. Works for CKEditor only.

font_sizes
Type: object

Used to set font sizes. Works for CKEditor only.

toolbar
Type: string

Only available for WYSIHTML rich text editor. Customize the toolbar of WYSIHTML rich text editor by adding the control's id that we would like to be visible.

See customizing wysihtml toolbar page for more information.

type
Type: string

Select the default rich text editor type ie. "ckeditor" or "wysihtml". Set to "none" will disable default rich text editor of question editor, textarea will be rendered instead.

Default: ckeditor

See customising the rich text editor for more information.

object

Used to set custom font colors. Works for CKEditor only.

Properties:
colors
Type: string
A comma separated list of font colors (e.g. '2C91AC,0000') to be added to the color dropdown. It can also be specified as an array.
overwrite_defaults
Type: boolean
If set to true, the custom colors overwrite CKEditor's default colors.
Default: false
object

Used to set font sizes. Works for CKEditor only.

Properties:
enabled
Type: boolean
If set to false, the font sizes plugin will be disabled in CKEditor.
Default: true
sizes
Type: string
Used to overwrite the default font sizes. Entries are separated by semi-colons (';') and any kind of size can be used, e.g. '12px;2.3em;x-small'. Optionally, you can define a display name for a size by prefixing an entry with the name and the slash character, e.g. 'Normal/12px;Medium/16px'. Note that specifying font sizes in px can create problems with accessibility settings.
Default: 8/0.5em;10/0.6em;12/0.8em;14/0.9em;15/0.9em;16/1em;18/1.1em;20/1.3em;24/1.5em;25/1.6em;28/1.8em;32/2em;40/3em
boolean

this config option allows you to selectively show or hide the "default" Learnosity templates in the UI

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

Default: true
object

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

See knowledge base for more information.

Properties:
change_button
Type: boolean

Whether to show the change widget button.

Default: true
editor
Type: object

An extra editor features.

help_button
Type: boolean

Whether to show the help button.

Default: true
hide_asset_input_field
Type: boolean

If set to true, the source field of an asset is not displayed. Only works if assetRequest is specified.

Default: false
layout
Type: object

A template customization.

live_score_button
Type: boolean

Whether to show the live score button.

Default: true
search_field
Type: boolean

Boolean value that controls the visibility of the search field above the question groups.

Default: true if ui.layout.mode is "advanced", otherwise false
source_button
Type: boolean

Whether to show the widget source button.

Default: true
template_name
Type: boolean

Whether to show the template name.

Default: true
undo_redo_button
Type: boolean

Whether to show the Undo/Redo button.

Default: true
validate_question_button
Type: boolean

Whether to show the show answers button.

Default: true
object

An extra editor features.

Properties:
response_shortcut

Allows author to insert response boxes by pressing an underscore key.

Enabling a shortcut doesn't affect a button on a toolbar which will still work. This option is only valid in a template field for the following question types: clozeassociation, clozedropdown, clozeinlinetext, clozetext, clozeformula, clozechemistry

Default: "doubleunderscore"
string | boolean

Allows author to insert response boxes by pressing an underscore key.

Enabling a shortcut doesn't affect a button on a toolbar which will still work. This option is only valid in a template field for the following question types: clozeassociation, clozedropdown, clozeinlinetext, clozetext, clozeformula, clozechemistry

Types
string
Possible values:
  • "doubleunderscore" - to insert response box, you need to press underscore key twice, one after another.
  • "singleunderscore" - to insert response box, you need to press underscore key only once.
boolean

To insert response box, you need to press a button on an editor toolbar.

Possible value: false
Default: "doubleunderscore"
object

A template customization.

Properties:
advanced_group
Type: boolean

Whether to show advanced group of questions to appear in the sidebar when a new question is being created.

edit_panel
Type: object

A layout option to be used in custom global template.

See Edit Layout docs for more information.

simple_features
Type: object

An object consisting of layout options used to customise the simple features modal. Each object is identified by a key which represents the simple feature type (e.g videoplayer, audioplayer).

See Simple feature modal layout docs for more information.

global_template
Type: string

The global layout template being used.

Possible values:
  • "edit"
  • "edit_preview"
  • "custom"

See Global Layout docs for more information.

mode
Type: string

Question Editor layout mode, valid values are: "advanced" and "simple".

Default: "advanced"
responsive_edit_mode
Type: object

If the global_template is set to "edit_preview", responsive_edit_mode object can be used to configure the responsive behaviour of Question Editor.

In order to deliver better responsive ui, browser window size smaller than breakpoint will render in edit layout.

object

If the global_template is set to "edit_preview", responsive_edit_mode object can be used to configure the responsive behaviour of Question Editor.

In order to deliver better responsive ui, browser window size smaller than breakpoint will render in edit layout.

Properties:
breakpoint
Type: integer

Integer value (representing pixels) which controls at what container width to switch to edit layout.

Default: 800
enabled
Type: boolean

If set to false, Question Editor will not switch to edit layout when the container width is narrow.

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.

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.

Properties:
name
Type: string
template_reference
Type: string
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.

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.

Function to be called on a response editor error event.

Parameters
error
Type: object

Object containing error details.

Properties:
code
Type: number
message
Type: string
name
Type: string
title
Type: string

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.

The callback function which is executed when the custom button is clicked.

Parameters
attribute
Type: string
callback
Type: function(customContent)

Call this function to add the custom content to the text editor.

Parameters
customContent
Type: string

The custom HTML content to be added to the text editor.

object
Properties:
defaults
Type: object

Change the default values that will be populated when you load the Question Types. (e.g. you could set the default Stimulus for MCQ using this config option). In order to set a default value for new array elements, keys with empty brackets "[]" can be used. Extends whatever is defined in base_question_type.defaults.

dependency
Type: Array[string]

Turns provided array items to become interleaving items. For example: if we create an array like ["options", "metadata.distractor_rationale_response_level"] then "metadata.distractor_rationale_response_level" is now a dependant node of "options" so if an "options" item is added or removed a corresponding "metadata.distractor_rationale_response_level" item will be added or removed as well.

description
Type: string

Overwrites the default description for the Question Type.

exclude_options
Type: object

Combination of object key and array value to remove unwanted option(s) from dropdown input (eg. you could remove "large", "xlarge" fontsizes from mcq question type by adding ui_style.fontsize: ["large", "xlarge"]) or Math question type's custom action group. Overrides base_question_type.exclude_options.

group_reference
Type: string

Changes the tile view group in which this question type will appear. E.g. if you created a new question type group (see the question_type_groups config option) called "Spoken", you could move the Audio question type to that group.

hidden
Type: Array[string]

Define which attributes should be hidden in this question type. Extends base_question_type.hidden

hidden_sections
Type: Array[string]

This property will extend the setting from base_question_type in the specified widget type.

image
Type: string

URI - Changes the image that will appear in the tile view for this question type. If no image is defined a default image for the according question_type will be displayed.

image_preview_placeholder
Type: string

Define the URL of an image which is displayed as a placeholder in questions which show an image preview. The specified image is shown, if the image source of the question is empty or points to an incorrect url. Overrides base_question_type.image_preview_placeholder.

name
Type: string

Changes the display name of the question type in the tile view

reference
Type: string

A unique reference that identifies the Question Type Template. This attribute is only applicable to question_type_templates.

shown
Type: Array[string]

Define which previously hidden attributes should be shown. This is useful, if you define hidden attributes in base_question_type.hidden, but want to show them for a certain question type only.

shown_sections
Type: Array[string]

This property will extend the setting from base_question_type in the specified widget type.

object

Change the default values that will be populated when you load the Question Types. (e.g. you could set the default Stimulus for MCQ using this config option). In order to set a default value for new array elements, keys with empty brackets "[]" can be used. Extends whatever is defined in base_question_type.defaults.

Properties:
[key]
Type: *
object

Combination of object key and array value to remove unwanted option(s) from dropdown input (eg. you could remove "large", "xlarge" fontsizes from mcq question type by adding ui_style.fontsize: ["large", "xlarge"]) or Math question type's custom action group. Overrides base_question_type.exclude_options.

Properties:
[optionKey]
Type: *
object
Properties:
height
Type: string
url
Type: string
width
Type: string
object
Properties:
element
Type: string

The element to wrap content with inside the editor when the style is applied (eg. "em", "strong", "blockquote"). Defaults to "span".

element_class
Type: string

An additional class to be placed on the element surrounding the styled text for custom css.

label
Type: string

The name of the style as shown in the dropdown.

label_class
Type: string

A class to place on the label in the dropdown, allowing the label in the dropdown to be styled by custom css. For WYSIHTML editor only.

is_container_style
Type: boolean
If set to true, the style will be treated as a container style. This only works for div elements.
object
Properties:
attributes
Type: Array[string]

An array of string containing the selectors of the rich text editors with which the custom buttons are to be associated. If this is undefined the buttons will be associated with all rich text editor instances. For array type fields like options, you can either define a selector for a specific entry, e.g. options[0], or you can specify a selector targeting the whole array, e.g. options[*].

See editor layout section for more information.

func

The callback function which is executed when the custom button is clicked.

icon
Type: string

A link to the button icon (Recommended dimensions: 25px by 25px).

label
Type: string

The button label.

name
Type: string

A unique identifier for the button.