Methods

This article details methods the client can use to interact with Author API.

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".
Returns: AuthorApp
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"});

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

Returns: boolean 
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

Returns: boolean 
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:
  • edit
  • preview
Returns: boolean 
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:
  • edit
  • preview
Returns: boolean | string 
authorApp.changeItemMode('preview');

This method allows you to deselect all the previously selected Items.

Returns: boolean 
authorApp.clearSelectedItems();
Closes the Item settings view if it's open and returns true, else returns false.

Returns: boolean 
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.
Returns: boolean 
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 true, passages are duplicated among Items. If set to false, passages are shared.

Default: false
Returns: boolean 
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 itemReference does not match the reference of an existing Item in the Item bank (case-sensitive). If true, a new Item will be created with the passed itemReference as its reference. If false or no value is passed, the operation will fail with an error.

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.

Returns: activityTemplate | boolean 
/*
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

Returns: boolean | string 
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.

Returns: array[string] 
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.

Returns: string 
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.

Returns: boolean | string 
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.

Returns: array[tagsV2] | boolean 
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

Returns: boolean | string 
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.

Returns: itemJson
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.

Returns: boolean | string 
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.

Returns: boolean | number 
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.

Returns: boolean | string 
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.

Returns: boolean | string 
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.

Returns: boolean | string 
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.

Returns: array[tagsV2] | boolean 
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

Returns: boolean | string 
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.

Returns: boolean | string 
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.

Returns: boolean | searchParameters 
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.

Returns: Promise 
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.

Returns: boolean | string 
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.

Returns: boolean | widgetJson 
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.

Returns: boolean | widgetMetadata 
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
Returns: boolean 
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
Type: string
Note: Any data in the location string should be URI encoded.
Returns: boolean 
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.

Returns: AuthorApp
// 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

Callback function that will be invoked whenever the event is triggered.
context
Type: object

Execution context that will be used for this when the calback function is invoked.
Returns: AuthorApp
// 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

Callback function that wil be invoked whenever the event is triggered.
context
Type: object

Execution content that will be used for this when the callback function is invoked.
Returns: AuthorApp
// 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.

Returns: questionsApp | boolean 
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.
Returns: boolean 
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.
Returns: boolean 
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

Definition of save options to customize the behaviour of the save() method.
Returns: boolean 
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.

Returns: boolean 
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

Definition of the Activity JSON
options
Type: options
Contains additional parameters which control the behaviour of the method.
Returns: boolean 
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
Returns: boolean 
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.
Returns: boolean 
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:
  • published
  • unpublished
  • archived
Returns: boolean | string 
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)
Returns: array[tagsV2] | boolean 
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
Returns: boolean 
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
Returns: boolean | 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
Returns: boolean 
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
Returns: boolean 
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
Returns: boolean 
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.
Returns: boolean | string 
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
Returns: boolean 
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)
Returns: array[tagsV2] | boolean 
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
Returns: boolean 
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:
  • per-question
  • dependent
  • dichotomous
Returns: boolean 
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:
  • published
  • unpublished
  • archived
Returns: boolean | string 
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

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
Widget template containing the template reference (case-sensitive)
Returns: boolean 
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"
});
object

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.

object
Contains additional parameters which control the behaviour of the method.
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
object

Definition of the Activity template

Properties:
adaptive
Type: adaptive

See adaptive in Items API Initialization for more information.

data
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
object

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.

object

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
object

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.

object

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

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.

object

Definition of the Tag value for the TagsV1 object.

Properties:
name
Type: string
Tag name where maximum length is 255 characters
object

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
object

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
object

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.

object

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
object

Definition of the widget template

See Widget template references Knowledge base for more information.

Properties:
template_reference
Type: string
Widget template reference
object

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 true, then the Items and content of the Activity will be duplicated.

Default: false
duplicateSharedPassages
Type: boolean

If deepCopyActivity is set to true, then setting this value to true will duplicate instead of sharing any shared passages in an Item.

Default: false
showConfirmationScreen
Type: boolean

If set to true, the author will be taken to the confirmation screen. All other arguments have no effect. The init options config.activity_edit.duplicate.deep_copy and config.activity_edit.duplicate.duplicate_shared_passages determine what options display on the confirmation screen.

If set to false, the init options config.activity_edit.duplicate.deep_copy and config.activity_edit.duplicate.duplicate_shared_passages will have no effect.

Default: false
object

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 true, passages are duplicated among Items. If set to false, passages are shared.

Default: false
showConfirmationScreen
Type: boolean

If set to true, the author will be taken to the confirmation screen. All other arguments have no effect.

Default: false 
authorApp.duplicateItem({
    reference: 'NewReference',
    showConfirmationScreen: true,
    duplicateSharedPassages: true
});