Methods
This article details methods the client can use to interact with Author API.
LearnosityAuthor
The following methods are accessed via the window.LearnosityAuthor
object.
When the <script src="https://authorapi.learnosity.com?v1"></script>
tag is included on the page, the window.LearnosityAuthor
object is instantiated, and ready for use.
Initialises the Author API and injects the authoring UI into a container element of the DOM.
Returns authorApp (object), representing the Author API instance and it's callable methods. All other public methods should be called against the instantiated Author app (see example below).
Parameters | |
---|---|
initOptions |
Type:
object Configures the Author API's behaviour. See Initialization for more information. |
eventOptions |
Type:
object Attaches a readyListener and/or errorListener. See Events for more information. |
elementId |
Type:
string This should match the id of a DOM container element (e.g. a div) into
which the authoring UI should be injected. By default, the authoring UI will be
injected into a container with id="learnosity-author" .
|
var initOptions = {
/*
See the Initialisation Options section
for guidance on the initOptions object.
*/
};
// Instantiate the AuthorApp. The authoring UI
// will be injected into a container with id="learnosity-author".
var authorApp = LearnosityAuthor.init(initOptions, {
readyListener: function () {
bindEvents(); // Custom method
createItem();
}
});
// Alternatively, instantiate AuthorApp and inject
// into a container with id="my-custom-container".
var authorApp = LearnosityAuthor.init(initOptions, "my-custom-container"});
AuthorApp
The following methods are accessed via the authorApp
instance returned by window.LearnosityAuthor.init()
.
Navigates back to the Activity list view from the Activity edit view, restoring the state to what it was before navigating away from the Activity list view.
Returns true
if successful, else false
.
Version added: v2022.3.LTS
var result = authorApp.backToActivityList();
Navigates back to the Item edit view from any Item edit subview including the Question/Feature edit view, Item settings views or the passage list view. It checks if the state is dirty and prompts the user before navigation.
Returns true
if successful, else false
.
Version added: v2020.2.LTS
var result = authorApp.backToItemEdit();
Changes the mode being used in Activity edit view.
Returns true (boolean) if successful, or false (boolean) if unable to change the
Activity mode (e.g. when not on Activity edit view, the passed mode
is not
valid or is the same as the current mode).
Parameters | |
---|---|
mode |
Type:
string If no value is passed, the mode will simply be toggled from edit to preview and vice-versa.
Possible values:
|
var result = authorApp.changeActivityMode('preview');
result = authorApp.changeActivityMode(); // toggle Activity view mode
Changes the mode being used in Item edit view.
Returns mode (string), the new Item mode, if successful, or false (boolean) if unable to
change the Item mode (e.g. when not on Item edit view or Item settings view, the passed
mode
is not valid or is the same as the current mode).
Parameters | |
---|---|
mode |
Type:
string If no value is passed, the mode will simply be toggled from edit to preview and vice-versa.
Possible values:
|
authorApp.changeItemMode('preview');
This method allows you to deselect all the previously selected Items.
authorApp.clearSelectedItems();
true
, else returns false
.authorApp.closeItemSettings();
Creates a new Activity with the specified reference.
Parameters | |
---|---|
activityReference |
Type:
string Maximum length is 150 characters. It must not match the reference of an existing Activity in the Item bank (case-insensitive); otherwise, the operation will fail with an error. If no value is passed, the new Activity that will be created will have a UUID as the reference. |
authorApp.createActivity();
Creates a new Item with the specified reference.
Parameters | |
---|---|
itemReference |
Type:
string Maximum length is 150 characters. It must not match the reference of an existing Item in the Item bank (case-insensitive); otherwise, the operation will fail with an error. If no value is passed, the new Item that will be created will have a UUID as the reference. |
authorApp.createItem();
Destroys the current instance of the Author app. This will also restore the HTML hook used to first initialize the app. Remember to delete any reference to the instance.
authorApp.destroy();
Duplicates the Activity currently being edited or takes the author to the confirmation
screen if duplicateActivitySettings.showConfirmationScreen
is set to
true
.
Returns true (boolean) if it's possible to attempt duplication, or false (boolean) if
unable to attempt duplication (e.g. when not editing an Activity, the passed
duplicateActivitySettings.reference
is not valid, Activity is empty).
Note
This method may throw an error later despite returning true (boolean) if
something goes wrong, for example, if the passed
duplicateActivitySettings.reference
is used by an existing Activity in the
Item bank or the Activity that will be duplicated has missing Items.
Parameters | |
---|---|
duplicateActivitySettings |
Object containing the arguments for Activity duplication. |
authorApp.duplicateActivity({
reference: 'NewReference',
deepCopy: true,
duplicateSharedPassages: true
});
Duplicates the current Item being edited. The duplicate Item will use the specified reference as its reference. All widgets in the Item are fully cloned with new internal UUID references except for shared passages because they are copied by reference. Any future changes to a shared passage will thus be applied to all of its copies. If the operation is successful, the duplicate Item is automatically loaded and saved.
Note
The duplicate Item is not persisted in the Item bank if
config.item_edit.item.save.persist
option is
false. Item duplication using this method is not supported when editing an Item within an Activity.
Returns true (boolean) if it's possible to attempt duplication, or false (boolean) if
unable to attempt duplication (e.g. when not editing an Item, the passed
reference
is not valid, Item is empty).
Note
This method may throw an error later despite returning true (boolean) if
something goes wrong, for example, if the passed reference
is used by an
existing Item in the Item bank.
Alternatively, this method can be called by passing in duplicateItemSettings. This is only available on version 2019.2.LTS onwards.
Parameters | |
---|---|
reference |
Type:
string Maximum length is 150 characters. It must not match the reference of an existing Item in the Item bank (case-insensitive); otherwise, the operation will fail with an error. If an empty string or no value is passed, the duplicate Item that will be created will have a UUID as the reference. |
duplicatePassages |
Type:
boolean If set to to Default: false |
authorApp.duplicateItem('', true); // Duplicate Item with random reference and duplicated passages
Loads an existing Activity with the specified reference. The said Activity must be owned by
the consumer in the security parameters passed to the init
method.
Parameters | |
---|---|
activityReference |
Type:
string Maximum length is 150 characters. It must match the reference of an existing Activity in the Item bank (case-sensitive); otherwise the operation will fail with an error. |
authorApp.editActivity('authorapi-activity-demo');
Loads an existing Item with the specified reference. The said Item must be owned by the
consumer in the security parameters passed to the init
method.
Parameters | |
---|---|
itemReference |
Type:
string Maximum length is 150 characters. |
create |
Type:
boolean This controls what happens when the passed This argument is not supported in the Activity edit view. |
authorApp.editItem('authorapi_demo2');
Gets the Question Editor app facade which exposes a set of Question Editor API public methods for use when editing a widget.
var editorAppFacade = authorApp.editorApp();
editorAppFacade.checkValidation(); // { has_validation: true }
editorAppFacade.attribute("stimulus").getValue(); // "[This is stem.]"
Gets the current Activity template of the Activity being edited.
Returns activityTemplate (object), the current Activity template, or false (boolean) if not editing an Activity.
From version 1.34 onwards Activity Items are returned as objects, specifying from which Item bank they are loaded.
/*
activityObject == {
"reference": "test",
"description": "test",
"data": {
"items": [
{
reference: "test1",
organisation_id: 1
},
{
reference: "test3",
organisation_id: 1,
item_pool_id: "pool_1"
}
],
"rendering_type": "assess"
},
"status": "published",
"dt_created": "2017-05-22 05:01:21",
"dt_updated": "2017-05-30 07:04:26",
"last_updated_by": "639",
"tags": [],
"adaptive": {
"difficulty": null,
"operational_exposure": null,
"seeding_exposure": null
},
"tagsCount": 0,
"content": "",
"rendering_type": "assess"
}
*/
var activityObject = authorApp.getActivity();
Gets the current description of the Activity being edited.
Returns description (string), the current Activity description, or false (boolean) if not editing an Activity.
Version added: v2020.2.LTS
authorApp.getActivityDescription();
Gets the current list of Items associated with the Activity being edited.
Returns Items (array[string]), the current list of Item references, or false (boolean) if not editing an Activity.
From version 1.34 Items are returned as objects, specifying in which Item bank they are stored.
var items = authorApp.getActivityItems();
/*
items == ["Demo_1","Demo3","Demo4"] (old versions)
items == [
{
"reference": "Demo_1",
"organisation_id": 1
},
{
"reference": "Demo3",
"organisation_id": 1
"item_pool_id" "test_pool"
},
{
"reference": "Demo4"
"organisation_id": 2
}
] (version 1.34 and newer)
*/
Gets the current reference of the Activity being edited.
Returns activityReference (string), the current Activity reference, or false (boolean) if not editing an Activity.
var activityReference = authorApp.getActivityReference();
Gets the current status of the Activity being edited.
Returns status (string), the current Activity status which can be one of:
published
, unpublished
, archived
, or false (boolean)
if not editing an Activity.
var activityStatus = authorApp.getActivityStatus();
Gets the current list of Tags associated with the Activity being edited.
Returns Tags (array[tagsV2]), the current list of Activity TagsV2 objects, or false
(boolean) if not editing an Activity. Note: Tags hidden by the
config.global.hide_tags
option are not returned by
this method.
var tags = authorApp.getActivityTags();
/**
tags == [
{"type":"demo-tagtype-1","tags":[ {"name":"tag11"}, {"name":"tag3"} ]},
{"type":"demo-tagtype-2","tags":[ {"name":"tag11"} ]}
];
*/
Gets the current title of the Activity being edited.
Returns title (string), the current Activity title, or false (boolean) if not editing an Activity.
Version added: v2020.2.LTS
authorApp.getActivityTitle();
Gets the current Item JSON of the Item being edited.
Returns itemJson (object), the current Item JSON, or false (boolean) if not editing an Item.
authorApp.getItem();
Gets the current description of the Item being edited.
Returns description (string), the current Item description, or false (boolean) if not editing an Item.
authorApp.getItemDescription();
Gets the current difficulty of the Item being edited.
Returns difficulty (number), the current Item difficulty, or false (boolean) if not editing an Item.
authorApp.getItemDifficulty();
Gets the current Notes of the Item being edited.
Returns notes (string), the current Item Notes, or false (boolean) if not editing an Item.
authorApp.getItemNotes();
Gets the current reference of the Item being edited.
Returns itemReference (string), the current Item reference, or false (boolean) if not editing an Item.
authorApp.getItemReference();
Gets the current source of the Item being edited.
Returns source (string), the current Item source, or false (boolean) if not editing an Item.
authorApp.getItemSource();
Gets the current list of Tags associated with the Item being edited.
Returns Tags (array[tagsV2]), the current list of Item TagsV2 objects, or false
(boolean) if not editing an Item. Note: Tags hidden by the
config.global.hide_tags
option are not returned by
this method.
authorApp.getItemTags();
Gets the current title of the Item being edited.
Returns title (string), the current Item title, or false (boolean) if not editing an Item.
Version added: v2020.2.LTS
authorApp.getItemTitle();
Gets the current location of the Author app.
Returns locationObject, the current location object.
authorApp.getLocation();
Gets the current scoring type of the Item being edited.
Returns scoringType (string), the current Item scoring type which can be one of:
dependent
, per-question
, dichotomous
, or false
(boolean) if not editing an Item.
authorApp.getScoringType();
Gets the current search parameters used in Item list view, Activity list view, Item
picker view, Intro picker view or Outro picker view. This can be used to add custom
filtering UIs (e.g. button to quickly search by a certain Tag). The search parameters can
be fed back into the navigate
method.
Returns searchParameters (object), the current search parameters; false (boolean) if not searching for an Item or Activity.
authorApp.getSearch();
/* Example response
* {"sort":"desc","sort_field":"updated","limit":20}
*/
If you have enabled Item selection
in the Item list, you can retrieve the selected Items JSONs with this method. The method returns a
Promise
which resolves with an array of Item JSON from the server. If no Items are selected or if
this method is called while not in Item list view, false
is returned.
To clear current selection see the clearSelectedItems() public method.
var getPromise = authorApp.getSelectedItems();
getPromise && getPromise.then(function (response) {
/**
* response = {
* data: {
* {
* items: [
* {
* item: {
* .
* .
* },
* questions: {
* .
* .
* },
* features: {
* .
* .
* }
* },
* .
* .
* ]
* }
* }
* }
*/
};
Gets the current status of the Item being edited.
Returns status (string), the current Item status which can be one of:
published
, unpublished
, archived
, or false (boolean)
if not editing an Item.
authorApp.getStatus();
Gets the current widget JSON of the widget being edited in an Item. This only works with Question Editor v3.
Returns widgetJson (object), the current widget JSON, or false (boolean) if not editing a widget.
authorApp.getWidget();
Gets the current metadata JSON of the widget being edited in an Item. This only works with Question Editor v3.
Returns widgetMetadata (object), the current widget metadata, or false (boolean) if not editing a widget.
authorApp.getWidgetMetadata();
Move the Author API instance to the specified DOM element.
Returns true (boolean) if successful, or false (boolean) if unable to append the Author
API instance to the passed element
.
Parameters | |
---|---|
element |
Type:
DOM DOM element to append the Author API instance to |
function moveInstanceTo1 () {
var dom = document.getElementById('author-api-container');
return authorApp.moveInstanceTo(dom);
}
moveInstanceTo1(); // returns true
function moveInstanceTo2 () {
var dom = document.getElementById('non-existing-element');
return authorApp.moveInstanceTo(dom);
}
moveInstanceTo2(); // returns false, because element doesn't exist
function moveInstanceTo3 () {
var dom = document.getElementsByClassName('author-api-container');
return authorApp.moveInstanceTo(dom);
}
moveInstanceTo3(); // returns false, as it doesn't accept arrays
Navigates the Author app to the specified location. The dirty state is not checked before navigating.
Returns true (boolean) if it's possible to navigate, or false (boolean) if unable to
navigate (e.g. the passed location
is not valid, or it is the same as the
current location when editing an Item or an Activity).
Note Navigating multiple times in quick succession can have unintended side effects, so it's recommended to wait for a relevant public event before navigating again (do not use the return value, as it does not indicate that the navigate completed, only if it's possible).
Version added: v2022.1.LTS
See knowledge base article on navigation routes for more information.
Parameters | |
---|---|
location |
Type:
string Note: Any data in the location string should be URI encoded.
|
function goToItem (reference) {
return authorApp.navigate('item/' + reference);
}
function goToItemList () {
return authorApp.navigate('items');
}
function gotToItemListWithHierarchies () {
authorApp.navigate('items/search/' + encodeURIComponent(JSON.stringify({
"browse": {
"hierarchy": {
"reference": "CCSS",
"tags": [
{"type": "Common Core Topic", "name": "The Number System", "label": "The Number System"},
{"type": "Common Core State Standard", "name": "Geometry", "label": "Geometry"}
]
},
"tags": [
{"type": "course", "name": "Introduction to algebra"}
]
}
})));
}
function showUnpublishedItems () {
return authorApp.navigate(
'items/search/' + encodeURIComponent('{"status":"unpublished"}')
);
}
// The following are examples of navigating to different sections of the Tile view.
function goToWidgetsTileView (itemReferenceOrNew) {
return authorApp.navigate(
'items/' + itemReferenceOrNew + '/widgets/new'
)
}
function goToFeaturesTileView (itemReferenceOrNew) {
return authorApp.navigate(
'items/' + itemReferenceOrNew + '/widgets/new/' + encodeURIComponent('{"widgetType":"features"}')
)
}
// One way to use navigate is for loading straight into the widget editor with a particular template.
// See the knowledge base for a list of available template references.
function createMultipleChoiceQuestion (itemReferenceOrNew) {
return authorApp.navigate('items/' + itemReferenceOrNew + '/widgets/new/' + encodeURIComponent(JSON.stringify(
{
widgetTemplate: {
template_reference: '9e8149bd-e4d8-4dd6-a751-1a113a4b9163'
}
})));
}
// Below is an example of how to initialize directly to any widget template (e.g. "Calculator"):
function goToWidgetEdit (itemReferenceOrNew, widgetType, templateName) {
return authorApp.navigate(
'items/' + itemReferenceOrNew + '/widgets/new/' + encodeURIComponent(JSON.stringify({
widgetType: widgetType,
widgetTemplate: {
template_reference: templateName
}
}))
)
}
// Add a calculator feature.
goToWidgetEdit('my - item - reference', 'features', '532767d1-40e7-47e4-be81-ec5cdbfb5fd8');
Removes a previously-bound callback function for an event.
Returns authorApp (object), the Author API instance if successful.
When called with no parameters, callbacks for all events are removed.
Parameters | |
---|---|
eventName |
Type:
string Name of the event that you want to stop listening to. See events list for more information. |
// Stop listening for the 'widgetedit:widget:ready' event.
authorApp.off('widgetedit:widget:ready');
// This is a chained call, which allows multiple public method calls.
authorApp.off('widgetedit:widget:changed').off('widgetedit:preview:changed');
// Removing all event listeners.
authorApp.off('');
Set up an event listener.
Parameters | |
---|---|
eventName |
Type:
string Name of the event that you want to listen to. See events list for more information. |
eventCallback |
Type:
eventCallback Callback function that will be invoked whenever the event is triggered. |
context |
Type:
object Execution context that will be used for |
// Turn on event listener for 'render:item' event.
authorApp.on('render:item', function (event) {
console.log("Item rendered.");
});
// This is a chained call, which allows multiple public method calls.
authorApp.on('save', function (event) {
console.log("Save complete.");
})
.on('save:error', function (event) {
console.log("There was an error saving. Please try again.");
});
Set up a one time event listener. Will fire once and then stop listening.
Parameters | |
---|---|
eventName |
Type:
string Name of the event you want to listen to. See events list for more information. |
eventCallback |
Type:
eventCallback Callback function that wil be invoked whenever the event is triggered. |
context |
Type:
object Execution content that will be used for |
// Listen once for the event reporting that the editor panel has finished rendering.
authorApp.once('widgetedit:widget:ready', function (event) {
console.log("Widget is ready for editing.");
});
// This is a chained call, which allows multiple public method calls.
// This example listens for the editor changing states and changes to the widget preview.
authorApp.once('widgetedit:widget:changed', function (event) {
// code to handle the event
})
.once('widgetedit:preview:changed', function (event) {
// code to handle the event
});
Gets the current Questions API instance which exposes a set of Questions API public
methods for use. Properties of the Questions app include all Questions API methods except
the init
method
Returns questionsApp (object), the current Questions API instance, or false (boolean) if not editing an Item.
Note
New Questions API instances are created throughout
the lifetime of an Author app (e.g. whenever an Item is rendered) so it is best to hook
into the Author API's render:item
event to get the current Questions API
instance.
authorApp.questionsApp();
Checks if the current Item or Activity being edited is clean (i.e. no unsaved changes) and thus safe to be unloaded.
Returns true (boolean) if the Item or Activity is clean or when not editing an Item or Activity, or false (boolean) if the Item or Activity is dirty.
Note
As of v2021.1.LTS, in Item edit view, calling safeToUnload(true)
has been deprecated in favor of more explicit setter: setSafeToUnload('item_edit')
.
Parameters | |
---|---|
isSafe |
Type:
boolean If true, the Item or Activity is marked clean regardless of whether it has unsaved
changes or not. This is necessary if saving Items is done externally. If false or
no value is passed, the Item or Activity is marked dirty when it has any unsaved
changes. Note that when creating a new Item, its state is initially clean until a
change is made. However, when creating a new Activity, its state is initially dirty
to allow saving of an empty Activity.
|
authorApp.safeToUnload(true);
Marks componentName
safe or unsafe to unload based on the value of isSafe
.
Returns true
(boolean) if the method call succeeded, and false
(boolean) otherwise.
Parameters | |
---|---|
componentName |
Type:
string The name of the component. Supported component names are: "item_edit".
|
isSafe |
Type:
boolean If true or not passed, componentName is marked safe to unload. This is necessary if saving Items is done externally.
If false , componentName is marked unsafe to unload. Note that when creating a new Item, it is initially safe to unload until a
change is made. However, when creating a new Activity, it is initially unsafe to unload to allow saving of an empty Activity.
|
authorApp.setSafeToUnload('item_edit'); // Equivalent to authorApp.setSafeToUnload('item_edit', true);
authorApp.setSafeToUnload('item_edit', false);
Saves the current Item being edited.
Returns true (boolean) if successful, or false (boolean) if unable to save the Item (e.g when not on Item edit view or Widget edit view, no changes to save in an Item, Item is empty).
Note
Saved Item is not persisted in the Item bank if
config.item_edit.item.save.persist
option is false.
Parameters | |
---|---|
saveOptions |
Type:
saveOptions Definition of save options to customize the behaviour of the |
authorApp.save();
// or
authorApp.save({navigate: false});
Saves the current activity being edited.
Returns true (boolean) if successful, or false (boolean) if unable to save the Activity (e.g when not on Activity edit view, no changes to save in an existing Activity in the Item bank).
Note
Saved Activity is not persisted in the Item bank if
config.activity_edit.save.persist
option is false.
authorApp.saveActivity();
Sets the Activity JSON of the Activity being edited.
Returns true (boolean) if successful, or false (boolean) if unable to set the Activity JSON (e.g. when not editing an Activity).
From version 1.34 onwards, Items can also be passed as objects specifying in which Item bank they are stored
Parameters | |
---|---|
activityJson |
Type:
activityJson Definition of the Activity JSON |
options |
Type:
options Contains additional parameters which control the behaviour of the method. |
authorApp.setActivity({
"items": ["08ca8f0d-b883-402e-b365-4bf8ab4c433b", "e81a4901-2f15-4c5c-84db-92332086fdb6", "LongItemForActivity"],
"rendering_type": "inline"
});// old versions
authorApp.setActivity({
"items": [
{
reference: "test1",
organisation_id: 1
},
{
reference: "test3",
organisation_id: 1,
item_pool_id: "pool_1"
}
],
"rendering_type": "inline"
});// version 1.34 and newer
Sets the description of the Activity being edited.
Returns true (boolean), if successful, or false (boolean) if unable to set the Activity description (e.g. when not editing an Activity or the passed value is not valid).
Version added: v2020.2.LTS
Parameters | |
---|---|
description |
Type:
string |
authorApp.setActivityDescription(description);
Sets the list of Items to associate with the Activity being edited. This overwrites the current list of associated Items.
Returns true (boolean) if successful, or false (boolean) if unable to to set the Activity Items (e.g. when not editing an Activity).
From version 1.34 onwards, Items can also be passed as objects specifying in which Item bank they are stored
Note
Set up an array of ItemBankDefinition
as an entry in Activity edit's item_banks
,
if loading Items from multiple resources for an Activity.
Parameters | |
---|---|
items |
Type:
array[string] An array of Item references (case-sensitive). Any reference that do not correspond
to an existing Item in the Item bank is ignored.
|
authorApp.setActivityItems(["Demo_1","Demo3","Demo4"]);// older versions
authorApp.setActivityItems(
[
{
reference: "test1",
organisation_id: 1
},
{
reference: "test3",
organisation_id: 1,
item_pool_id: "pool_1"
}
]
);// version 1.34 and newer
Sets the status of the Activity being edited.
Returns status (string), the new Activity status, if successful, or false (boolean) if
unable to set the Activity status (e.g. when not editing an Activity, the passed
status
is not valid or is the same as the current status).
Parameters | |
---|---|
status |
Type:
string Activity status (case-sensitive)
Possible values:
|
var status = authorApp.setActivityStatus('published');
Sets the list of Tags to associate with the Activity being edited. This overwrites the current list of associated Tags. Note that if the Tag(s) being attached to an Activity don't already exist in the Item bank, they will be created. Caution should be taken to avoid extraneous content.
Returns Tags (array[tagsV2]), the new list of Activity TagsV2 objects, or false
(boolean) if unable to set the Activity Tags (e.g. when not editing an Activity, passed
tags
is invalid).
Note
Tags hidden by the
config.global.hide_tags
option are returned by this method if they are included in the passed tags
.
Parameters | |
---|---|
tags |
Type:
array[tagsV2] An array of TagsV2 objects (case-insenstive)
|
authorApp.setActivityTags([
{"type": "demo-tagtype-1", "name": "tag11"},
{"type": "demo-tagtype-1", "name": "tag12"},
{"type": "demo-tagtype-2", "name": "tag22"}
]);
Sets the title of the Activity being edited.
Returns true (boolean), if successful, or false (boolean) if unable to set the Activity title (e.g. when not editing an Activity or the passed value is not valid).
Version added: v2020.2.LTS
Parameters | |
---|---|
title |
Type:
string |
authorApp.setActivityTitle(title);
Sets the description of the Item being edited.
Returns description (string), the new Item description, if successful, or false (boolean) if unable to set the Item description (e.g. when not editing an Item or the passed value is not valid).
Parameters | |
---|---|
description |
Type:
string |
authorApp.setItemDescription(description);
Sets the difficulty of the Item being edited.
Returns true (boolean), if successful or false (boolean) if unable to set the Item difficulty (e.g. when not editing an Item or the passed value is not valid).
Parameters | |
---|---|
difficulty |
Type:
number |
authorApp.setItemDifficulty(difficulty);
Sets the Item JSON.
Returns true (boolean), if it started updating or false (boolean) if unable to set the Item JSON. It will return false if the Item reference in the JSON is invalid or if the user is not in the Item edit view.
Calling this method will apply the Item JSON to the Item currently being edited.
Therefore, this method won't allow you to switch between Items. If you want to set the JSON of a different Item, you must first
navigate
to that Item.
Version added: v2020.2.LTS
Parameters | |
---|---|
itemJson |
Type:
itemJson Definition of the Item JSON |
authorApp.setItemJson({
"item": {
"reference": "example-item-1",
"title": "example-title",
"definition": {
"widgets": [{
"reference": "example-widget-ref1"
}]
}
},
"questions": [{
"reference": "example-widget-ref1",
"widget_type": "response",
"data": {
"stimulus": "short text",
"type": "shorttext"
},
"type": "shorttext"
}]
});
Sets the notes of the Item being edited.
Returns true (boolean), if successful or false (boolean) if unable to set the Item notes (e.g. when not editing an Item or the passed value is not valid).
Parameters | |
---|---|
notes |
Type:
string |
authorApp.setItemNotes(notes);
Sets the reference of the Item being edited.
Returns itemReference (string), the new Item reference, if successful, or false
(boolean) if unable to set the Item reference (e.g. when not editing an Item, the passed
itemReference
is not valid or is the same as the current reference).
Parameters | |
---|---|
itemReference |
Type:
string Maximum length is 150 characters.
|
authorApp.setItemReference(reference);
Sets the source of the Item being edited.
Returns true (boolean), if successful or false (boolean) if unable to set the Item source (e.g. when not editing an Item or the passed value is not valid).
Parameters | |
---|---|
source |
Type:
string |
authorApp.setItemSource(source);
Set the list of Tags to associate with the Item being edited. This overwrites the current list of associated Tags. Note that if the Tag(s) being attached to an Item don't already exist in the Item bank, they will be created. Caution should be taken to avoid extraneous content.
Returns Tags (array[tagsV2]), the new list of Item TagsV2 objects, or false
(boolean) if unable to set the Item Tags (e.g. when not editing an Item, passed
tags
is invalid or the same as the current Tags).
Note
Tags hidden by the
config.global.hide_tags
option are returned by this method if they are included in the passed tags
.
Parameters | |
---|---|
tags |
Type:
array[tagsV2] An array of TagsV2 objects (case-insenstive) |
authorApp.setItemTags(tags);
Sets the title of the Item being edited.
Returns true (boolean), if successful, or false (boolean) if unable to set the Item title (e.g. when not editing an Item or the passed value is not valid).
Version added: v2020.2.LTS
Parameters | |
---|---|
title |
Type:
string |
authorApp.setItemTitle(title);
Set the scoring type of the Item being edited.
Returns true (boolean) if successful, or false (boolean) if unable to set the Item scoring type (e.g. when not editing an Item, the passed scoringType is not valid).
Parameters | |
---|---|
scoringType |
Type:
string Item scoring type (case-sensitive)
Possible values:
|
authorApp.setScoringType(scoringType);
Set the status of the Item being edited.
Returns status (string), the new Item status, if successful, or false (boolean) if unable to set the Item status (e.g. when not editing an Item, the passed status is not valid or is the same as the current status).
Parameters | |
---|---|
status |
Type:
string Item status (case-sensitive)
Possible values:
|
authorApp.setStatus(status);
Set the widget JSON of the widget being edited in an Item. This only works with Question Editor v3.
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
.
Returns true (boolean) if successful, or false (boolean) if unable to set the widget JSON (e.g. when not on Tile view or Widget edit view)
Parameters | |
---|---|
widgetJson |
Type:
widgetJson Properties of the widget JSON vary depending on the Question type or feature type. See Question Types and Features Types in Questions API for more information. |
widgetTemplate |
Type:
widgetTemplate Widget template containing the template reference (case-sensitive) |
function setWidget (widgetJson, widgetTemplate) {
return authorApp.setWidget(widgetJson, widgetTemplate);
}
setWidget({
"options": [{
"label": "[Choice A]",
"value": "0"
}, {
"label": "[Choice B]",
"value": "1"
}, {
"label": "[Choice C]",
"value": "2"
}, {
"label": "[Choice D]",
"value": "3"
}],
"stimulus": "<p>[This is the stem.]</p>",
"type": "mcq",
"ui_style": {},
"validation": {
"scoring_type": "exactMatch",
"valid_response": {
"score": 1,
"value": [""]
}
}
},
{
"template_reference": "908de244-5c71-4c09-b094-7fb49554f2f9"
});
Definition of the Activity JSON
Properties: | |
---|---|
config |
Type:
config See config in Items API Initialization for more information. |
items |
Type:
array[string] Array of Item references |
rendering_type |
Type:
string See rendering_type in Items API Initialization for more information. |
Properties: | |
---|---|
extend |
Type:
boolean When extend is true (the default),
the supplied Activity JSON extends the existing JSON, and when extend
is false , the supplied Activity JSON replaces the existing JSON,
allowing client developers to remove certain keys from the Activity JSON.
Default: true |
Definition of the Activity template
Properties: | |
---|---|
adaptive |
Type:
adaptive See adaptive in Items API Initialization for more information. |
data |
Type:
activityJson Holds the Activity data. |
description |
Type:
string Activity description |
dt_created |
Type:
string Date and time when the Activity was created |
dt_updated |
Type:
string Date and time when the Activity was last updated |
reference |
Type:
string Activity reference |
status |
Type:
string Activity status |
tags |
Type:
array[tagsV2] Array of tagsV2 objects corresponding to Tags associated with the Activity
|
tagsCount |
Type:
number Number of Tags associated with the Activity |
Definition of the Question Editor app facade
Properties: | |
---|---|
attribute |
Type:
function() See attribute in Question Editor API Methods for more information. |
checkValidation |
Type:
function() See checkValidation in Question Editor API Methods for more information. |
redo |
Type:
function() See redo in Question Editor API Methods for more information. |
undo |
Type:
function() See undo in Question Editor API Methods for more information. |
Definition of the event callback function
Parameters | |
---|---|
event |
Type:
string Public event instance which provides access to event data (default behaviour
can be disabled by using the event data's preventDefault() method)
See Author API Events for more information. |
Definition of the Item JSON
Properties: | |
---|---|
features |
Type:
array[widgetObject] Array of widget objects for features in the Item |
item |
Type:
object Holds the Item data. |
questions |
Type:
array[widgetObject] Array of widget objects for Questions in the Item |
Definition of the location object
Properties: | |
---|---|
location |
Type:
string Author app location |
locationEncoded |
Type:
string URI encoded version of the Author app location |
route |
Type:
string Route matching the Author app location See Routes in Custom integration using the navigate event Knowledge base for more information. |
Definition of save options to customize the behaviour of the save()
method.
Properties: | |
---|---|
navigate |
Type:
boolean This controls what happens after the Item is saved successfully when the
save() method is called on Widget edit view. If true or
no value is passed, it automatically goes back to Item edit view.
If false, it remains on the same view.
|
Properties of the search parameters vary depending on the view (i.e. Item list view, Activity list view, Item picker view, Intro picker view, Outro picker view).
See Search parameters Knowledge base for more information.
Definition of the Tag value for the TagsV1 object.
Properties: | |
---|---|
name |
Type:
string Tag name where maximum length is 255 characters |
Definition of the TagsV1 object used in Author API Methods
See TagsV1 in Tag Formats Knowledge base for more information.
Properties: | |
---|---|
tags |
Type:
array[tagsValue] Tag value |
type |
Type:
string Tag type where maximum length is 255 characters |
Definition of the TagsV2 object used in Author API Methods
See TagsV2 in Tag Formats Knowledge base for more information.
Properties: | |
---|---|
name |
Type:
string Tag name where maximum length is 255 characters |
type |
Type:
string Tag type where maximum length is 255 characters |
Properties of the widget JSON vary depending on the Question type or feature type. See Question Types and Features Types in Questions API for more information.
Definition of the widget metadata
See Widget template references Knowledge base for more information.
Properties: | |
---|---|
name |
Type:
string Widget template name |
template_reference |
Type:
string Widget template reference |
Definition of the widget template
See Widget template references Knowledge base for more information.
Properties: | |
---|---|
template_reference |
Type:
string Widget template reference |
Arguments for the duplicateActivity method
Properties: | |
---|---|
reference |
Type:
string Maximum length is 150 characters. It must not match the reference of an existing Activity in the Item bank (case-insensitive); otherwise, the operation will fail with an error. If an empty string or no value is passed, the duplicate Activity that will be created will have a UUID as the reference. |
deepCopy |
Type:
boolean If set to Default: false |
duplicateSharedPassages |
Type:
boolean If Default: false |
showConfirmationScreen |
Type:
boolean
If set to
If set to Default: false |
Arguments for the duplicateItem method.
Properties: | |
---|---|
reference |
Type:
string Maximum length is 150 characters. It must not match the reference of an existing Item in the Item bank (case-insensitive); otherwise, the operation will fail with an error. If an empty string or no value is passed, the duplicate Item that will be created will have a UUID as the reference. |
duplicateSharedPassages |
Type:
boolean If set to to Default: false |
showConfirmationScreen |
Type:
boolean If set to Default: false |
authorApp.duplicateItem({
reference: 'NewReference',
showConfirmationScreen: true,
duplicateSharedPassages: true
});