The navigate
event contains data about the intended location of the Author API instance and preventDefault
method that can be used to halt moving to this location. For example, you might want to prevent the adding of a Question or a Feature to an Item, and handle this in your own way:
var authorApp = LearnosityAuthor.init(initOptions, {
readyListener: function () {
authorApp.on("navigate", function (event) {
var isNewWidgetLocation = event.data.route === "items/new/widgets/new" ||
event.data.route === "items/:reference/widgets/new";
if (isNewWidgetLocation) {
myApp.addNewQuestionOrFeature();
event.preventDefault();
}
});
}
});
Code example 1: preventing the addition of Questions or Features to an Item
Or perhaps you'd only like to use the Author API for browsing and searching a collection of Items, but you'd like to handle the creation and editing of Items in a custom way:
var authorApp = LearnosityAuthor.init(initOptions, {
readyListener: function () {
authorApp.on("navigate", function (event) {
var itemRef;
if (event.data.route === "items/new") {
myApp.createNewItem();
event.preventDefault();
}
if (event.data.route === "items/:reference") {
// Extract the reference from e.g. "items/example-item-ref"
itemRef = event.data.location.replace(/^(items\/)/, "");
myApp.openItem(itemRef);
event.preventDefault();
}
});
}
});
Code example 2: custom handling for the creation and editing of Items
Routes
1. List Activities
Route |
---|
activities |
Location Example |
'activities' |
Description |
Shows Activity list. |
2. Create new Activity
Route |
---|
activities/new |
Location Example |
'activities/new' |
Description |
Shows Activity edit with a new Activity. |
3. Read Activity
Route |
---|
activities/:reference |
Location Example |
'activities/example-reference' |
Description |
Shows Activity edit with the matching Activity. |
4. Search Activities
Route |
---|
activities/search/:query |
Location Example |
'activities/search/' + encodeURIComponent('{"referenceOrDescription":"test"}') |
Description |
Shows Activity list with search query and results. |
5. List Items
Route |
---|
items |
Location Example |
'items' |
Description |
Shows Item list. |
6. List Items for Activity
Route |
---|
activities/:reference/searchItems |
Location Example |
'activities/example-reference/findItems' |
Description |
Shows Item list to add to an Activity. |
7. Search Items
Route |
---|
items/search/:query |
Location Example |
'items/search/' + encodeURIComponent('{"reference":"test"}') |
Description |
Shows Item list with search query and results. Available parameters outlined in the section on search parameters on this page. |
8. Create new Item
Route |
---|
items/new |
Location Example |
'items/new'
|
Description |
Shows Item edit with a new Item. |
9. Create new Item and Activity
Route |
---|
activities/new/items/new |
Location Example |
'activities/new/items/new'
|
Description |
Shows Item edit with a new Item, on a new Activity. |
10. Create new Item on an Activity
Route |
---|
activities/:reference/items/new |
Location Example |
'activities/example-reference/items/new'
|
Description |
Shows Item edit with a new Item, on the matching Activity. |
11. Read Item
Route |
---|
items/:reference |
Location Example |
'items/example-reference' |
Description |
Shows Item edit with the matching Item. |
12. Read Item on an Activity
Route |
---|
activities/:reference/items/:idOrReference |
Location Example |
'activities/example-reference/items/example-reference-or-id' |
Description |
Shows Item edit with the matching Item, on the matching Activity. Note: If Item reference provided is for existing Item in Itembank but not in the Activity yet, Item edit view will be opened with the Item reference provided. Item will be added to Activity and Activity will be saved as a part of If Item reference provided is for non-existing Item in Itembank, Item edit view will be opened with the Item reference provided. Item will not be added to Activity as a part of |
13. Read Item definition
Route |
---|
items/:data |
Location Example |
'items/' + encodeURIComponent('{"item":{"reference":"example-reference-2","definition":{"widgets":[{"reference":"qwidget-ref1"}]}},"questions":[{"reference":"qwidget-ref1","widget_type":"response","data":{"stimulus":"short text","type":"shorttext"},"type":"shorttext"}]}') |
Description |
Shows Item edit with Item definition. The Item definition is explained in the section on Item definition on this page. |
14. Create widget and Item
Route |
---|
items/new/widgets/new |
Location Example |
'items/new/widgets/new' |
Description |
Shows widget templates with a new widget, on a new Item. |
15. Create widget on an Item
Route |
---|
items/:reference/widgets/new |
Location Example |
'items/example-reference/widgets/new' |
Description |
Shows widget templates with a new widget, on the matching Item (or Item definition). |
16. Read widget on an Item
Route |
---|
items/:reference/widgets/:reference |
Location Example |
'items/example-reference/widgets/example-reference' |
Description |
Shows widget edit with the matching widget, on the matching Item (or Item definition). Note that you cannot create a new widget by specifying a non-existent UID e.g. items/:reference/widgets/a-new-widget. Doing this will cause unexpected behaviour and may cause data loss upon subsequent editing. If you want to create a new widget, use /widgets/new |
17. Create widget on new Item with parameters
Route |
---|
items/new/widgets/new/:data |
Location Example |
'items/example-reference/widgets/new/' + encodeURIComponent('{"widgetType":"Match List"}') |
Description |
Opens a new widget configured with the given data parameters, on a new Item. Available parameters outlined in the section on widget data parameters on this page. |
18. Create widget on an Item
Route |
---|
items/:reference/widgets/new/:data |
Location Example |
'items/example-reference/widgets/new/' + encodeURIComponent('{"widgetTemplate": { "template_reference": "1fa22aac-1f88-47f7-941b-3c77759549e6" }}') |
Description |
Opens a new widget configured with the given data parameters, on the matching Item (or Item definition). Available parameters outlined in the section on widget data parameters on this page. |
19. Overwrite widget on an Item with parameters
Route |
---|
items/:reference/widgets/:reference/:data |
Location Example |
'items/example-reference/widgets/example-reference/' + encodeURIComponent('{"widgetJson": {"possible_responses": ["[Choice A]","[Choice B]","[Choice C]"],"stimulus": "Stem","stimulus_list": ["[Stem 1]","[Stem 2]","[Stem 3]"],"type": "association","validation": {"scoring_type": "exactMatch","valid_response": {"score": 1,"value": [null,null,null]}}}, "widgetTemplate": {"template_reference": "1fa22aac-1f88-47f7-941b-3c77759549e6"}}') |
Description |
Opens an existing widget and overrides its data with the given data parameters, on the matching Item. Available parameters outlined in the section on widget data parameters on this page. |
20. View settings for an existing Item
Route |
---|
items/:reference/settings |
Location Example |
'items/example-reference/settings' |
Description |
Opens the settings screen for an existing Item. |
21. View settings for a new Item
Route |
---|
items/new/settings |
Location Example |
'items/new/settings' |
Description |
Opens the settings screen for a new Item. |
22. Open a specific tab in settings for an existing Item
Route |
---|
items/:reference/settings/:tab |
Location Example |
'items/example-reference/settings/layout' |
Description |
Opens a specific tab in the settings view for an existing Item. Possible values for the tab parameter are: 'layout' , 'details' , 'tags' , 'data-table' or 'actions' . |
23. Open a specific tab in settings for a new Item
Route |
---|
items/new/settings/:tab |
Location Example |
'items/new/settings/layout' |
Description |
Opens a specific tab in the settings view for a new Item. Possible values for the tab parameter are: 'layout' , 'details' , 'tags' , 'data-table' or 'actions' . |
Search parameters
1. Question Reference
Key |
---|
questionReference |
Type |
string |
Default |
'' |
Description |
Filters by Question reference. |
2. Reference
Key |
---|
reference |
Type |
string |
Default |
'' |
Description |
Filters based on Item reference. An Item is contained in the search results if its reference is contains reference . |
3. Content
Key |
---|
content |
Type |
string |
Default |
'' |
Description |
Filters based on Item content. An Item is contained in the search results if its searchable content matches content . The searchable content of an Item consists of the stimulus, the template, any shared passage content, the Item's HTML markup, description, note, source and acknowledgement as well as the references of the Item's Questions. Words separated by a blank in content are matched against the searchable content via 'AND', so that the search results will shrink as more words are entered. |
4. Sort
Key |
---|
sort |
Type |
'' |
Default |
'desc' |
Description |
Sets order of results: 'asc' for oldest to newest, or 'desc' for newest to oldest. |
5. Sort field
Key |
---|
sort_field |
Type |
string |
Default |
'updated' |
Description |
Sets what sorting should be based on. This could be either when the Item was 'created' or 'updated' or it can be the Item's 'title' or 'reference' . |
6. Status
Key |
---|
status |
Type |
string |
Default |
'' |
Description |
Filters by status: 'unpublished' , 'published' , or 'archived' . |
7. Tags
Key |
---|
tags |
Type |
object |
Default |
{} |
Description |
Allows filtering based on Tags. |
8. All Tags
Key |
---|
tags.all |
Type |
array |
Default |
[] |
Description |
See section on tags.all in the Item list filter section of the config docs. |
9. All Tags of type
Key |
---|
tags.all[].type |
Type |
string |
Default |
- |
Description |
See section on tags.all in the Item list filter section of the config docs. |
10. All Tags of name
Key |
---|
tags.all[].name |
Type |
string |
Default |
- |
Description |
See section on tags.all in the Item list filter section of the config docs. |
11. Either Tags
Key |
---|
tags.either |
Type |
array |
Default |
[] |
Description |
See section on tags.either in the Item list filter section of the config docs. |
12. Either type of Tags
Key |
---|
tags.either[].type |
Type |
string |
Default |
- |
Description |
See section on tags.either in the Item list filter section of the config docs. |
13. Either name of Tags
Key |
---|
tags.either[].name |
Type |
string |
Default |
- |
Description |
See section on tags.either in the Item list filter section of the config docs. |
14. Widget type
Key |
---|
widgetType |
Type |
string |
Default |
'' |
Description |
Filter by Question type or Feature type. |
15. Browse hierarchy reference
Key |
---|
browse.hierarchy.reference |
Type |
string |
Default |
|
Description |
Specifies a hierarchy reference that should be preselected via a hierarchy browse control. The specified hierarchy must have been included in a hierarchy browse control in the options passed to LearnosityAuthor.init() . See the initialisation options for toolbar browse controls. |
16. Browse hierarchy Tags
Key |
---|
browse.hierarchy.tags |
Type |
array |
Default |
{"browse": { |
Description |
Specifies a hierarchy reference and a number of Tags within that hierarchy that should be preselected via a hierarchy browse control. The specified hierarchy must have been included in a hierarchy browse control in the options passed to LearnosityAuthor.init() . See the initialization options documentation for toolbar browse controls. |
17. Browse Tags
Key |
---|
browse.tags |
Type |
array |
Default |
|
Description |
Specifies Tags that should be preselected via Tag browse controls. The specified Tag types must have been associated with a Tag browse control in the options passed to LearnosityAuthor.init() . See the initialization options documentation for toolbar browse controls. |
Widget data parameters
Key | Type | Default | Description |
---|---|---|---|
widgetType | string | 'questions' |
Filters possible templates by Question type or Feature type. If no widget template or JSON is provided, this navigates to the corresponding widget tile view. |
widgetJson | object | - | Optional. The JSON that may be used to initialize the widget. If a widget template is also provided, the JSON attributes will override any attributes in the template. This parameter is only available in Question Editor version 3. |
widgetTemplate | object | - | An object containing key "template_reference" to denote a widget template. This is useful for navigating directly into a particular widget template, bypassing the tile view. Note: must be an exact string match, including case and punctuation (e.g. en dash versus hypen). For more details refer to the Widget Template documentation |
regionId | string | '1' |
Specifies which region in the Item to create the widget in. Only valid when creating for an existing Item. The region must already exist. |
Item definition
Note: the use case for passing Item JSON `data` is for new Items only. Existing Item references passed will result in a duplication error thrown on save. Existing widget references behave differently and will be overridden if passed.
The ideal use case is for templating new Items for authors, for example, two-column layout.
Key | Type | Description |
---|---|---|
item | object | Item definition, including Item reference. |
questions | array | (optional) An array of Questions. |
features | array | (optional) An array of Features. |