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.
LearnosityQuestionEditor
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 |
object Object containing Question Editor config parameters. See initOptions for more information. |
selector |
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 |
object Visit the Question Editor API callback object for detailed documentation on callbacks and its parameters. |
questionEditorApp
The following methods are accessed via the questionEditorApp
instance returned by window.LearnosityQuestionEditor.init()
.
Allows you to get, modify, or remove a specified input value 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 |
string |
Return value types: | attributeObject | A returned instance of | undefined | If the attribute does not exist. This could happen with custom questions for example.
For this reason, make sure to check the returned value is a defined object before calling its methods. One way of doing this is by leveraging optional chaining for example with const value = attribute('stimulus')?.getValue(); |
---|
questionEditorApp.attribute("stimulus");
/* example output - returns object with available functions
{
{getValue: f, setValue: f, remove: f}
}
*/
Checks whether the question currently being edited has a correct answer set.
Parameters | |||||
---|---|---|---|---|---|
options |
object
|
Return value types: | validationStatusObject | A return object of | false | If the operation can not be performed. Note An error message will also be logged to the console. |
---|
var result = questionEditorApp.checkValidation({ showErrors: true }); // { 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 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.
Removes a previously-bound callback function for an event.
When called with no parameters, callbacks for all events are removed.
Parameters | |
---|---|
event_name |
string Name of the event that you want to stop listening to. See events list for more information. |
event_callback |
function() If no callback is provided, all callbacks for the event_name will be removed. |
context |
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 |
string Name of the event that you want to listen to. See events list for more information. |
event_callback |
function() Callback function that will be invoked whenever the event is triggered. |
context |
object Execution context that will be used for |
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 |
string Name of the event that you want to listen to. See events list for more information. |
event_callback |
function() Callback function that will be invoked whenever the event is triggered. |
context |
object Execution context that will be used for |
questionEditorApp.once("editor:ready", function() {
console.log("The editor has fully loaded.");
}); // Sets up a one-time event listener for the 'editor:ready' event.
Returns the Questions API instance being used by Question Editor API when editing a widget (used by the set validation area and the preview area).
This instance exposes the public methods (see return value link for exposed public methods.) for use to customise behavior, or getting data directly from it not otherwise exposed by Question Editor API.
Version added: v2021.3.LTS
// Example 1: Validate answer in the preview area
questionEditorApp.questionsApp().validateQuestions();
// Example 2: Get feature and stop video playing (e.g. with custom button)
const features = authorApp.editorApp().questionsApp().features();
Object.values(features).forEach(function(feature) {
feature.video.stop();
});
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.
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 |
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 |
boolean Mark the editor as safe to unload |
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 |
object The widget JSON to be set |
||||
widget_template |
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
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"
}
);
};
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.
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}
Object Definitions
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.
A returned instance of attribute
e.g. stimulus
Properties: | |
---|---|
addArrayItem |
To add a new item to array collection type attribute |
getValue |
function() Get current value of given attribute Returns: string |
remove |
function() To remove given array item, available for node of array collection only |
setValue |
Set value of given attribute Returns: attributeObject |
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 |
string New array item |
Set value of given attribute
Parameters | |
---|---|
value |
string Value of attribute object |
A return object of getMetadata
that contains template name and template_reference data
Properties: | |
---|---|
name |
string Template name of given question/feature |
template_reference |
string Template reference of given question/feature |
A return object of checkValidation
that contains has_validation
property which indicates the presence of validation
Properties: | |
---|---|
has_validation |
boolean If |