Submit a request
Submit a request

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();
            }
        });

    }
});

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();
            }
        });

    }
});

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('{"referenceOrContent":"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('{"referenceOrContent":"test"}')
Description
Shows Item list with search query and results. Available parameters outlined in section on search parameters.

 

8. Create new Item

Route
items/new
Location Example
'items/new'
Description
Shows Item edit with a new Item.

 

9. Read Item

Route
items/:reference
Location Example
'items/example-reference'
Description
Shows Item edit with the matching Item.

  

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

 

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

  

12. 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).

 

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

 

14. Create widget on new Item with parameters

Route
items/new/widgets/new/:data
Location Example
'items/example-reference/widgets/new/' + encodeURIComponent('{"widgetTemplate":"Match List"}')
Description
Opens a new widget configured with the given data parameters, on a new Item. Available parameters outlined in section on widget data parameters.

 

15. 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 section on widget data parameters.

  

16. 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 section on widget data parameters.

 

Search parameters

1. Question Reference

Key
questionReference
Type
string
Default
''
Description
Filters by Question reference.

  

2. Reference content

Key
referenceOrContent
Type
string
Default
''
Description
Filters based on Item reference and content. An Item is contained in the search results if its reference is similar to referenceOrContent or if its searchable content matches referenceOrContent. 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 referenceOrContent are matched against the searchable content via 'AND', so that the search results will shrink the more words you enter. In order to search for a specific phrase you can enclose it in double quotes ("").

 

3. Sort

Key
sort
Type
''
Default
'desc'
Description
Sets order of results: 'asc' for oldest to newest, or 'desc' for newest to oldest.

 

4. 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'.

 

 

5. Status

Key
status
Type
string
Default
''
Description
Filters by status: 'unpublished''published', or 'deleted' (i.e. archived).

 

 

6. Tags

Key
tags
Type
object
Default
{}
Description
Allows filtering based on Tags.

 

7. All Tags

Key
tags.all
Type
array
Default
[]
Description
See section on tags.all in the Item list filter section of the config docs..

 

 

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

 

 

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

 

10. Either Tags

Key
tags.either
Type
array
Default
[]
Description
See section on tags.either in the item list filter section of the config docs.

 

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

 

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

 

 

13. Widget type

Key
widgetType
Type
string
Default
''
Description
Filter by Question type or Feature type.

 

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

 

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

 

16. 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 Reference 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.
Was this article helpful?
0 out of 0 found this helpful