Building Your Own Author API User Journey Using .navigate()

This article demonstrates how to hook into the ‘navigate’ event for custom integration.

The navigate event contains data about the intended location of the Author API instance and preventDefaultmethod 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 navigate call.

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 navigate call.

 

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
{"browse": {
    "hierarchy": {
        "reference": "test-hierarchy"
    }
}
}
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": {
    "hierarchy": {
        "reference": "CCSS_Math_Hierarchy",
        "tags": [
            {"type": "Subject", "name": "Math"},
            {"type": "Grade", "name": "7"}
        ]
    }
}
}
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

{"browse": {
    "tags": [
        {"type": "difficulty", "name": "Intermediate"},
        {"type": "content_provider", "name": "Internal content"}
    ]
}
}

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.

Did you arrive here by accident? If so, learn more about Learnosity by clicking here.