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.
Example
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);
initialization
The initialization
object allows several UI and question type customizations definable by the host environment.
This is possible using the structure described below.
= 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:
|
||||||||||
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:
|
||||||||||
callback
|
Type:
callback(data)
Function that must be executed once the
|
||||||||||
attributes
|
Type:
object
Attributes of media to be used in
|
"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'
});
}
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 |
exclude_options
|
Type:
object
Combination of object key and array value to remove unwanted option(s) from dropdown input. |
Type:
Array[string]
Define which attributes should be hidden in all question types.
For array type fields like |
|
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
As you can see in the image above, sections are usually subdivided into
Note
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 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. |
base_question_typedefaults
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:
*
|
base_question_typeexclude_options
objectCombination of object key and array value to remove unwanted option(s) from dropdown input.
Properties: | |
---|---|
[optionKey]
|
Type:
*
|
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. |
scroll_container_selector
|
Type:
string
a jQuery type selector, specifying the element which Question Editor should scroll into view on navigation (overwrites |
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.
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.
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
|
custom_metadata[metadataKey]
objectProperties: | |
---|---|
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 |
custom_metadata: {
custom_metadata_key: {
description: 'custom metadata description',
name: 'custom metadata name',
type: 'string'
}
}
An object containing Questions API settings.
Properties: | |
---|---|
questions_api
|
Type:
object
|
dependenciesquestions_api
objectProperties: | |
---|---|
init_options
|
Type:
object
Initialization options to be used for Questions API. |
dependenciesquestions_apiinit_options
objectInitialization 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 |
math_renderer
|
Type:
string
This option allows you to overwrite the
Possible values:
|
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
andquestion_type_groups
is set, groups will extend the defaults. -
If this option is set to
false
, andquestion_type_groups
is not set, no groups will be shown at all. -
If this option is set to
false
, andquestion_type_groups
is set, then only these defined groups will be shown.
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
|
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 |
attributes
|
Type:
object
List of features organised by question type IDs. Currently the only supported question type ID is |
premium: {
question_types: ['video'],
attributes: {
fileupload: ['allow_video']
}
}
premiumattributes
objectList 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 |
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]
|
Type:
QuestionType
|
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
|
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 |
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
|
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.
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. |
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. |
overwrite_basic_styles
|
Type:
boolean
Only available for CKEditor. If set to
Default: false
|
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. |
toolbar_settings
|
Type:
object
Only available for CKEditor. Can be used to customize CKEditor's toolbar. See customizing CKEditor's toolbar page for more information. |
type
|
Type:
string
Select the default rich text editor type ie.
Default:
ckeditor
See customising the rich text editor for more information. |
rich_text_editorfont_settings
objectUsed 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
|
rich_text_editorfont_sizes
objectUsed 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
|
this config option allows you to selectively show or hide the "default" Learnosity templates in the UI
-
If this option is set to
true
andquestion_type_templates
and/orquestion_type_groups
are set, these options will be appended to the defaults. -
If this option is set to
false
andquestion_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
andquestion_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
, animage
attribute must be set in each template defined inquestion_type_templates
for display in the tile view.
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
|
distractor_rationale_button
|
Type:
object
Configuration settings for the distractor rationale button shown in the question preview toolbar. |
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
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
|
uidistractor_rationale_button
objectConfiguration settings for the distractor rationale button shown in the question preview toolbar.
Properties: | |
---|---|
enabled
|
Type:
boolean
Whether to show the distractor rationale button.
Default:
false
|
options
|
Type:
array
An array that specifies the kinds of distractor rationale to be displayed – either
Possible values:
|
uieditor
objectAn extra editor features.
Properties: | |
---|---|
response_shortcut
|
Type:
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
Default:
"doubleunderscore"
|
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:
|
boolean |
To insert response box, you need to press a button on an editor toolbar.
Possible value(s):
false
|
"doubleunderscore"
uilayout
objectA 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 See Simple feature modal layout docs for more information. |
global_template
|
Type:
string
The global layout template being used.
Possible values:
See Global Layout docs for more information. |
mode
|
Type:
string
Question Editor layout mode, valid values are:
Default:
"advanced"
|
responsive_edit_mode
|
Type:
object
If the global_template is set to In order to deliver better responsive ui, browser window size smaller than breakpoint will render in edit layout. |
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
|
widget_json
QuestionJson | FeatureJsonJSON 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.
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
|
Determines which supported Learnosity widget type definitions will be loaded in tile view.
"response"
"feature"
HTML Element Selector
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"
.
Callbacks
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.
|
Object Definitions
In the Initialization and Callback sections above, there are some object definitions which are complex enough to document separately. These are listed below, and linked from the relevant documentation above.
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.
|
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 |
dependency
|
Type:
Array[string]
Turns provided array items to become dependent items. To use, specify the "parent" as the first (odd) array value, then the "dependent" (child) as the next (even) array value. To set up multi-dependency, specify the parent again, with the second dependent after.
For example: if we create an array like
Note
The dependent array item should either have no default values set, or have the same number of array entries as the parent (use the |
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 |
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 |
Type:
Array[string]
Define which attributes should be hidden in all question types.
For array type fields like
Extends |
|
Type:
Array[string]
This property will extend the setting from |
|
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 |
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 |
shown
|
Type:
Array[string]
Define which previously hidden attributes should be shown. This is useful, if you define hidden attributes in |
shown_sections
|
Type:
Array[string]
This property will extend the setting from |
QuestionTypedefaults
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:
*
|
QuestionTypeexclude_options
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:
*
|
Properties: | |
---|---|
height
|
Type:
string
|
url
|
Type:
string
|
width
|
Type:
string
|
Properties: | |
---|---|
element
|
Type:
string
The element to wrap content with inside the editor when the style is applied (eg. |
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.
|
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. 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. |