Initialization

This article details the properties that are passed as parameters to the window.LearnosityAuthor.init() method to initialize Author API.

This method is the starting point to initializing and rendering Author API, and as you can see in the example below, takes three key parameters.

The Initialization object is mandatory. Further detail on getting started and initializing Author API can also be found in the Quick Start guide.

var initializationObject = {
    "security": {
        "consumer_key": "INSERT_CONSUMER_KEY_HERE",
        "domain": "my.domain.com",
        "timestamp": "20120202-1234",
        "signature": "SHA256-HASH - See Security"
    },
    "request": {
        "mode": "item_edit",
        "reference": "my-item-reference",
        "config": {
            "global": {
                "disable_onbeforeunload": true,
                // All tags of type "internal_category_uuid" are hidden in the UI
                "hide_tags":
                [
                  {
                    "type": "internal_category_uuid"
                  }
                ]
            },
            "item_edit": {
                "item": {
                    "back": true,
                    "columns": true,
                    "answers": true,
                    "scoring": true,
                    "reference": {
                        "edit": false,
                        "show": false,
                        "prefix": "LEAR_" // The reference for a new item will start with LEAR_
                    },
                    "save": true,
                    "status": false,
                    "dynamic_content": true,
                    "shared_passage": true
                },
                "widget": {
                    "delete": false,
                    "edit": true
                }
            },
            "item_list": {
                "item": {
                    "status": true,
                    "url": "http://myApp.com/items/:reference/edit"
                },
                "toolbar": {
                    "add": true,
                    "browse": {
                      "controls": [
                        {
                          "type": "hierarchy",
                          "hierarchies": [
                            {
                              "reference": "CCSS_Math_Hierarchy",
                              "label": "CCSS Math"
                            },
                            {
                              "reference": "CCSS_ELA_Hierarchy",
                              "label": "CCSS ELA"
                            },
                            {
                              "reference": "Demo_Items_Hierarchy",
                              "label": "Demo Items"
                            }
                          ]
                        },
                        {
                          "type": "tag",
                          "tag": {
                             "type": "difficulty",
                             "label": "Difficulty"
                          }
                        },
                        {
                          "type": "tag",
                          "tag": {
                             "type": "content_provider",
                             "label": "Source"
                          }
                        }
                      ]
                    }
                },
                "filter": {
                    "restricted": {
                        "current_user": true,
                        "tags": {
                            "all": [
                                {
                                    "type": "Alignment",
                                    "name": ["def456", "abc123"]
                                },
                                {
                                    "type": "Course"
                                }
                            ],
                            "either": [
                                {
                                    "type": "Grade",
                                    "name": "4"
                                },
                                {
                                    "type": "Grade",
                                    "name": "5"
                                },
                                {
                                    "type": "Subject",
                                    "name": ["Math", "Science"]
                                }
                            ],
                            "none": [
                                {
                                    "type": "Grade",
                                    "name": "6"
                                }
                            ]
                        }
                    }
                }
            },
            "dependencies": {
                "question_editor_api": {
                    "init_options": {}
                },
                "questions_api": {
                    "init_options": {}
                }
            },
            "widget_templates": {
                "back": true,
                "save": true,
                "widget_types": {
                    "default": "questions",
                    "show": true
                }
            },
            "container": {
                "height": "auto",
                "fixed_footer_height": 0,
                "scroll_into_view_selector": "body"
            },
            "label_bundle": { // German translation and date/time format changes
                // Generic components and partials
                "backButton": "Zurück",
                "loadingText": "Wird geladen",
                "modalClose": "Schließen",
                "saveButton": "Speichern",
                "duplicateButton": "Duplikat",

                // itemList > dates (using Moment.js)
                "dateTimeLocale": "",
                "toolTipDateTimeSeparator": "um",
                "toolTipDateFormat": "DD-MM-YYYY",
                "toolTipTimeFormat": "HH:MM:SS",
            }
        },
    }
}

var callbacks = {
    "readyListener": function () {
        console.log("Learnosity Author API is ready");
    },
    "errorListener": function (e) {
        //callback to occur on error
        console.log("Error code ", e.code);
        console.log("Error message ", e.message);
        console.log("Error name ", e.name);
        console.log("Error name ", e.title);
    }
};

var authorApp = LearnosityAuthor.init(initializationObject, callbacks);

The Initialization object is a JSON object which is passed as the first parameter into the window.LearnosityAuthor.init() method. It includes all the information needed to initialize the API.

It contains the following two top-level properties:

Security Object

The security object handles authentication and security in communication with the API.

The signature is the result of applying a SHA-256 hash algorithm on the attributes of the security object and string representation of the request object.

A guide on how to accomplish this can be found on our Security & Authentication page, as well as in the source for our demos site

Request Object

The request object contains all of configuration properties of authoring items and activities as well as user identification

Properties

= mandatory property

object
Optional configuration for each of the components that make up the Author API. This includes:
  • activity_edit: configuration for activity_edit mode
  • activity_list: configuration for activity_list mode
  • container: configuration for Author API container
  • dependencies: configuration for Author API dependencies including QuestionEditor API and Questions API
  • global: global configuration
  • item_edit: configuration for item_edit mode
  • item_list: configuration for item_list mode
  • label_bundle: configration to overrides lables in Author API
  • widget_templates: configuration for widget templates
Properties:
activity_edit
Type: object

Hold configuration for the Activity edit view.

activity_list
Type: object
Hold configuration for the Activity list view.

container
Type: object

Holds configuration for the Author API container.

dependencies
Type: object

Holds configuration for the dependencies.

global
Type: object
item_edit
Type: object
item_list
Type: object
label_bundle
Type: object

Holds optional overrides for each label in the API. Each label has a default English value (shown in the example JSON), and any labels omitted from the label_bundle object will use that default value.

widget_templates
Type: object
object

Hold configuration for the Activity edit view.

Properties:
activity_preview
Type: object
Holds configuration for the Activity preview view.

back
Type: boolean

Controls whether back button is shown.

Note Setting both back and save.show to boolean false will hide the navigation bar.

duplicate
Type: object

Holds the configuration for the Activity duplication behavior.

default_player_template
Type: string

Represents the player template which is selected by default when creating a new Activity.

Reference can be either a preconfigured or custom template.

Preconfigured template references can be found by inspecting the DOM element of the selection button, or by searching the DOM for [data-authorapi-player-reference].

If no value is provided or the provided reference does not exist in the dropdown (default, or as specified in player_templates), the default value is the first option in the dropdown.

enabled_player_templates
Type: array

Holds an array of player template references (both preconfigured, and custom as defined in player_templates).

Use this to specify which templates should be displayed in the Player Tab of the Activity editor, and how they will be ordered.

This can be used to hide default templates and show only custom ones, or alternatively hide the entire selection area by passing an empty array.

Note Template references are case sensitive.

Default: contains all preconfigured templates, and all templates from player_templates array.
Type: object

Holds configuration for the Item lookup screens (Item picker, intro and outro picker views) used by the Activity editor.

Important If a filter is specified for item list and none for item search, the item list filter will be applied.
item_title
Type: object
Holds configuration for the Item title.

mode
Type: object
Holds configuration for the Activity edit mode buttons.

player_templates
Type: Array[object]

Holds custom assess player templates for authors to select from in the Activity editor.

An assess player template is a defined set of Assess API config options which will be used to display the Activity. Custom assess player templates specified here will be included in the list of preconfigured templates available on the Player tab of the Activity editor.

Each array object represents a custom player template. The following properties are supported in each template:

Default: []
reference
Type: object
Holds configuration for the Activity reference.

save
Type: object
Holds configuration for the Activity save behavior.

source
Type: boolean
Controls whether the source tab is shown.

Default: true
tags_on_create
Type: Array[object]

Holds Tag objects which are added to a new Activity when saved.

A maximum of 50 Tags are allowed.

Note Tag types defined in hide_tags and tags_on_create will be saved but not displayed in the UI.

Default: []

See knowledgebase article on Tag formats for more information.

title
Type: object
Holds configuration for Activity titles. See knowledge base article on Activity titles.

object
Holds configuration for the Activity preview view.

Properties:
item
Type: object

Holds configuration for the Items within the Activity preview view.

Holds configuration for the Items within the Activity preview view.

Properties:
reference
Type: object
Properties:
show
Type: boolean

Controls whether Item references are shown in the Activity preview panels.

In the "Player" tab, Item references will be shown top left of the player.

In the "List" tab, Item references will be shown above each Item.

Default: false
object

Holds the configuration for the Activity duplication behavior.

Properties:
show
Type: boolean

Controls whether the duplicate button is shown.

Default: true
deep_copy
Type: boolean

Controls whether the user will be presented with the option to duplicate or share the Items and content of the Activity.

Default: false
duplicate_shared_passages
Type: boolean

If deep_copy is enabled, setting this to true will give the author the option to share or duplicate shared passages.

Default: false
object

Holds configuration for the Item lookup screens (Item picker, intro and outro picker views) used by the Activity editor.

Important If a filter is specified for item list and none for item search, the item list filter will be applied.
Properties:
back
Type: boolean
Controls whether the "back" button is shown.

Default: true
filter
Type: object

Options for filtering and restricting content that is displayed on the Item lookup screens

item_banks
Type: Array[ItemBankDefinition]
An optional array of Item banks from where Items for Activities can be loaded. If no item_banks are specified, all Items are loaded from the default Item bank.

See Knowledge base article on multi Item bank access for more information.

limit
Type: number
Control the number of Items listed on each page in the Item picker, intro and outro picker views.
Valid value is an integer between 1 and 50.

Default: 25
search Deprecated
Type: boolean
Controls whether the Item search bar is shown.

Note this is deprecated. Use toolbar.search.show instead.

Default: true
show
Type: boolean
Controls whether the "Find Items" button is shown in the Activity edit view.

Default: true
sort
Type: boolean
Controls whether the sort option is shown.

Default: true
tags Deprecated
Type: boolean

Controls whether the tag search dropdown is shown.

Note this is deprecated. Use toolbar.search.tags instead.
Default: true
widgets Deprecated
Type: boolean
Controls whether the Features and Question types dropdown in the "Find By Content" popup is shown.

Note this is deprecated. Use toolbar.search.widget_type instead.

Default: true
toolbar
Type: object
Holds configuration options for the search toolbar.

Options for filtering and restricting content that is displayed on the Item lookup screens

Properties:
restricted
Type: object

Holds config for filters which are applied by default to the search criteria for the Item lookup results. Use this to restrict what items users can see, as these cannot be changed by the user.

Holds config for filters which are applied by default to the search criteria for the Item lookup results. Use this to restrict what items users can see, as these cannot be changed by the user.

Properties:
created_by
Type: array

Only display Items created by the users in the passed array of strings (based on their user.id).

A maximum of 50 string values are allowed.

Default: []
current_user
Type: boolean

Only display Items created by the current user (based on their user.id), if created_by is present, this option overrides created_by.

Default: false
tags
Type: object

Holds config for tag filters which are applied by default to the search criteria for the Item lookup results.

Holds config for tag filters which are applied by default to the search criteria for the Item lookup results.

Properties:
all
Type: array

Each entry in the tags.all array is an object.

This object can follow three formats, the first being the TagsV2 object format where it only has the type and name properties.

It can also follow a variation of the said format where the name attribute is instead an array of strings which makes it more convenient to specify multiple tags of the same type.
For these two formats, Items must have all the specified tags to be visible.

The last format is another variation of the first one where the name property is omitted leaving the object with just the type property. In this case, Items must have at least one tag of the given type to be visible.

If there is more than one entry in tags.all, Items are only displayed if they have all of the tags specified for each entry in this initialization option.

See knowledge base article on advanced tag search for more information.

either
Type: array

Each entry in the tags.either array is an object.

This object can follow the TagsV2 object format where it only has the type and name properties.

It can also follow a variation of the said format where the name property is instead an array of strings which makes it more convenient to specify multiple tags of the same type.

Items are only displayed if they have at least one of the tags specified for at least one entry in this initialization option.

Note tags.either only supports an array of TagsV2 objects, not arrays of TagsV2 objects.

See knowledge base article on advanced tag search for more information.

none
Type: array

Each entry in the tags.none array is an object.

This object can follow the TagsV2 object format where it only has the type and name properties.

It can also follow a variation of the said format where the name property is instead an array of strings which makes it more convenient to specify multiple tags of the same type.

Items are only displayed if they don't have each tag specified for each entry in this initialization option.

Note For performance reasons, this initialization option will only work if tags.all or tags.either are set as well. If that's not the case, tags.none will be ignored.

See knowledge base article on advanced tag search for more information.

Holds configuration options for the search toolbar.

Properties:
search
Type: object
Holds configuration options for the search toolbar.

Holds configuration options for the search toolbar.

Properties:
show
Type: boolean
Determines if the search interface is displayed.

Default: true
controls
Type: array
Specifies search options. Possible values for the array are reference, content and title. title is only allowed if items are configured to display their title. reference is only allowed if title is disabled.

Default: ['reference', 'content']
widget_type
Type: boolean
Determines if search by widget type is available.

Default: true
tags
Type: object
Contains options for the tag search.

Contains options for the tag search.

Properties:
show
Type: boolean
Determines if search by tags is available.

Default: true
object
Holds configuration for the Item title.

Properties:
show
Type: boolean
Controls whether the Item title is shown in the Activity edit view.
If the Item does not have a title, it instead shows the reference.
When this is set to boolean true, Item title can be used to search in the Item lookup screens.

Default: false
Holds configuration for the Activity edit mode buttons.

Properties:
default
Type: string

Default Activity edit mode, valid values are: edit, preview (case sensitive).

Default: "edit"
show
Type: boolean

Controls whether the mode buttons are shown.

Note Setting both mode.show and reference.show to boolean false will hide the entire toolbar.

Default: true
Array[object]

Holds custom assess player templates for authors to select from in the Activity editor.

An assess player template is a defined set of Assess API config options which will be used to display the Activity. Custom assess player templates specified here will be included in the list of preconfigured templates available on the Player tab of the Activity editor.

Each array object represents a custom player template. The following properties are supported in each template:

Types
object
Properties:
labelBundle
Type: object
Specifies label bundle config to pass to Assess API.

Assess APIs default label bundle will be used if not specified.

See full documentation on Assess API's label bundle for more information.

name
Type: string
Display name of the template to be shown in the templates list.

reference
Type: string
The unique identifier of the player template. Max length for the reference is 150 characters

regions
Type: object
Specifies the regions configuration to pass to Assess API.

See full documentation on Assess API's regions options for more information.

object
Holds configuration for the Activity reference.

Properties:
edit
Type: boolean
Controls whether the reference can be changed.

Default: true
show
Type: boolean

Controls whether the reference is shown.

Note Setting both reference.show and mode.show to boolean false will hide the entire toolbar.

Default: true
Holds configuration for the Activity save behavior.

Properties:
persist
Type: boolean
Controls whether the Activity data is persisted in Activity bank.

Default: true
show
Type: boolean
Controls whether the save button is shown.

Note Setting both save.show and back to boolean false will hide the entire toolbar.

Default: true
Array[object]

Holds Tag objects which are added to a new Activity when saved.

A maximum of 50 Tags are allowed.

Note Tag types defined in hide_tags and tags_on_create will be saved but not displayed in the UI.

See knowledgebase article on Tag formats for more information.

Types
object
Properties:
type
Type: string
Type that Tag belongs to
name
Type: string
Name of Tag
"tags_on_create": [
    {
        "type": "Subject",
        "name": "Math"
    },
    {
        "type": "Grade",
        "name": "Grade 9"
    }
]
Holds configuration for Activity titles. See knowledge base article on Activity titles.

Properties:
edit
Type: boolean
Controls whether the Activity title can be changed.

Default: true
mandatory
Type: boolean

Controls whether a title is required when saving an Activity. The mandatory option requires both title.show and title.edit to be true.

Default: false
show
Type: boolean

Controls whether the Activity title is shown. If true, the Activity reference will not be shown and reference.show and reference.edit are ignored.

Note that the navigate search parameter when using Activity titles is titleOrReferenceOrDescription instead of referenceOrDescription, which will be ignored.

Default: false
object
Hold configuration for the Activity list view.

Properties:
filter
Type: object

Controls which Activities are to be displayed and can be accessed by users.

limit
Type: integer
Control the number of Activities listed on each page in the Activity list view.
Valid value is an integer between 1 and 50.

Default: 25
status
Type: boolean
Controls whether the Activity status is shown in the Activity list view.

Default: true
title
Type: object
toolbar
Type: object

Holds configuration for the Activity list (search) toolbar.

object

Controls which Activities are to be displayed and can be accessed by users.

Properties:
restricted
Type: object

Specifies a filter which cannot be changed by the user.

Important If a tag filter is specified and a user should be allowed to create Activities, tags matching that filter will need to be set on Activity creation (using setActivityTags).
"filter": {
  "restricted": {
    "tags": {
      "all": [
        {
          "type": "Depth of Knowledge",
          "name": "1"
        }
      ]
    }
  }
}
object

Specifies a filter which cannot be changed by the user.

Important If a tag filter is specified and a user should be allowed to create Activities, tags matching that filter will need to be set on Activity creation (using setActivityTags).
Properties:
created_by
Type: array

Only display Activities created by the users in the passed array of strings (based on their user.id).

Default: []
current_user
Type: boolean

Only display Activities created by the current user (based on their user.id), if created_by is present, this option overrides created_by.

Default: false
status
Type: array

Only display Activities that have a status matching one of the statuses in the array. Valid statuses are published, unpublished, archived. If status is an empty array, then no restrictions apply.

Default: ['published', 'unpublished']
tags
Type: object

Holds config for tag filters which are applied by default to the search criteria for the Activity list results.

Holds config for tag filters which are applied by default to the search criteria for the Activity list results.

Properties:
allow_filtered_tags_overwrite
Type: boolean

If set to true, then a user can save Activities which do not have the tags required by the tag filters below.

Default: false
all
Type: array

Each entry in tags.all is an object. The object can either have only a "type" attribute, meaning that all Activities must have at least one tag of the given type. Or the object can have a "type" and "name" attribute meaning that all Activities must have all the specified tags.

If several entries are specified in tags.all, Activity must have all those tags to be visible.

Default: []

See knowledge base article on advanced tag search for more information.

either
Type: array

Each entry in tags.either is an object with a "type" and "name". Activities must have one of the specified either tags to be displayed.

Note If this contains a pair of tags that was also set in tags.all, then tags.all takes precedence.

Default: []

See knowledge base article on advanced tag search for more information.

none
Type: array

Each entry in tags.none is an object with a "type" and "name". Activities are only displayed, if they don't have any of the tags.none tags.

Note For performance reasons, tags.none tags are only allowed if tags.all or tags.either tags are specified as well. If that's not the case, the none tags will be ignored.

Note If this contains a pair of tags that was also set in tags.all or tags.either, then tags.none takes precedence.

Default: []

See knowledge base article on advanced tag search for more information.

Properties:
show
Type: boolean

Controls whether Activity titles are visible in the Activity list view. When enabled, if an Activity has a title, it will show its title, else its reference will be shown.

Default: false
object

Holds configuration for the Activity list (search) toolbar.

Properties:
search
Type: boolean
Controls whether the main search button is shown.

Default: true
add
Type: boolean
Controls whether the create new Activity button is shown.

Default: true
object

Holds configuration for the Author API container.

Properties:
Type: integer

If the height of the container is left as 'auto' and scrolling is enabled then preview mode will accommodate all the space to the bottom of a viewport. There are cases though, when a host page may use a footer with position set to fixed. Such footer will cover bottom part of the preview mode making it inaccessible. Specifying a height of the footer will let a preview mode to adjust its height accordingly.

This is the height from the bottom edge of div.lrn-author-item-content to the bottom edge of the bottom element (footer) in the page.

Integer value corresponds to pixels.

Default: 0
height
Type: integer

The height of Author API app is automatic, which means the more content is there, the more it grows. Except in a preview mode where scrolling is enabled, the height of the container of Author API will be adjusted and will fit exactly within specified height to expose how scrolling functionality works. It's in particular very useful when loading Author API in fixed size modal window.

Setting this sets the height of the Author API container in Item edit/preview mode when "Enable scrolling for long content" is ticked in the Item settings view only.

Integer value corresponds to pixels.

Default: auto
scroll_into_view_selector
Type: string

When navigating between views (e.g. from Item edit to Question edit view), Author API scrolls its main container into view by default. If you want Author API to scroll another container into view, you can define that container's selector (as a jQuery selector) here. In Author Site, this is set to 'body' so that Author API is not partially hidden by Author Site's navigation bar.

This only affects the following transitions:
  • Clicking an item from the item list
  • Adding a new widget to an item
  • Edit an existing widget in an item
  • Selecting a widget from the tile view
Author API will scroll into the selector only if the top edge of its container is not visible in the viewport. This is not yet supported in Activity Builder.

object

Holds configuration for the dependencies.

Properties:
question_editor_api
Type: object

Holds initialization options for instances of Question Editor API that will be used.

questions_api
Type: object

Holds initialization options for instances of Questions API that will be used.

object

Holds initialization options for instances of Question Editor API that will be used.

Properties:
init_options
Type: object

The initialization options for the instance of Question Editor API that will be used.

Do not set Questions API config in question_editor_api.init_options.dependencies object as it will not be used. Instead set questions_api.init_options config.

Default: {}
preload
Type: boolean

If true, load Question Editor API when Author API is first loaded.

If false, load Question Editor API when the author visits the Item edit page (I.e. when QE is needed).

Default: true
version Deprecated
Type: string

Determines which version of Question Editor API will be used.

Note This almost never needs to be set as the Author API internally knows the appropriate version of the Question Editor API to load.

Default: "v3"
object

Holds initialization options for instances of Questions API that will be used.

Properties:
init_options
Type: object

The initialization options for the instance of Questions API that will be used.

Default: {}
version Deprecated
Type: string

Determines which version of Questions API will be used.

Note This almost never needs to be set as the Author API internally knows the appropriate version of the Questions API to load.

Default: "latest"
object
Properties:
disable_onbeforeunload
Type: boolean

If set to true, the HTML DOM onbefore event is not listened to by Author API.

One example is that no alert will be shown if an Item, Activity or Question was modified (but not saved) and the user refreshes the page. The alert is still shown if you click back/change the URL.

Default: false
hide_tags
Type: array

Tag types defined in hide_tags will not be displayed in Tag suggestions when using "Find by tags" dropdown in the Item or Activity list views, browsing via browse controls, when applying Tags to Items/Activities, or when viewing the tags attached to an Item/Activity

You can only specify hide_tags or show_tags, but not both at the same time.

Specify each array entry as a TagSearchByType object.

show_tags
Type: array

If you define Tag types in show_tags, only Tags of the specified type will be displayed in the Tag suggestions when using "Find by tags" dropdown in the Item or Activity list views.

You can only specify hide_tags or show_tags, but not both at the same time.

Specify each array entry as a TagSearchByType object.

object
Properties:
item
Type: object

Holds configuration for the Item.

widget
Type: object

Holds configuration for each widget (Question/Feature) on an Item.

tags_on_create
Type: Array[object]

Holds Tag objects which are added to a new Item when saved.

A maximum of 50 Tags are allowed.

Note Tag types also defined in the hide_tags array will be added on save, but will not displayed in the UI.

Default: []

See knowledgebase article on Tag formats for more information.

object

Holds configuration for the Item.

Properties:
answers
Type: boolean
Controls whether the "Show Answers" button is displayed in the Item preview view.

Default: true
back
Type: boolean
Controls whether the back button is shown in the Item edit view.

Default: true
columns
Type: boolean
Controls whether the preconfigured columns options are shown in the layout tab of the settings view.

Default: true
duplicate
Type: object
Holds configuration for the item duplication behavior.

See knowledge base article on item duplication for more information.

dynamic_content
Type: boolean
Controls whether the dynamic content data table tab in the settings view.

Default: false
dynamic_image_tag
Type: boolean
If set to true, when a URL is added into dynamic data and that URL's MIME type is an image, then the URL will automatically be converted into a HTML <img> element.

Default: false
enable_audio_recording
Type: boolean

Controls whether audio recording is enabled for the Audio player simple feature.

Currently, audio recording is only supported in Chrome, Safari, Firefox and Edge. The host page must also be using HTTPS. HTTP is not supported yet.

Default: false
mode
Type: object
Holds configuration for the Item edit mode buttons.

reference
Type: object
Holds configuration for the Item reference.

save
Configuration for the Item save behavior.

scoring
Type: boolean
Controls whether local scoring is enabled in the Item preview view. Immediately marks the Questions and shows the score to the user.

Default: true
shared_passage
Type: boolean
Controls whether the "Find existing passage" button is displayed in the add widget button in Item edit view.

Default: true
status
Type: boolean
Controls whether the Item status is shown in the Item edit view.

Default: false
tabs
Type: boolean
Controls whether the enable tabs checkboxes are shown in the layout tab in the settings view.

Default: true
tags
Type: object
template
Type: object
Item template to be used when new Items are created. This will be ignored if the Item reference already exists in the itembank.

title
Type: object
object
Holds configuration for the item duplication behavior.

See knowledge base article on item duplication for more information.

Properties:
show
Type: boolean
Controls whether the duplicate button is shown.

Default: true
duplicate_shared_passages
Type: boolean
Controls whether the user will be presented with the option to duplicate or share passages.

Default: false
Holds configuration for the Item edit mode buttons.

Properties:
default
Type: string

Default Item edit mode, valid values are: edit, preview (case sensitive).

Default: "edit"
show
Type: boolean

Controls whether the mode buttons are shown.

Default: true
object
Holds configuration for the Item reference.

Properties:
edit
Type: boolean
Controls whether the reference can be changed.

Default: false
prefix
Type: string

Sets the prefix for a newly created Item's reference.

Max length for the prefix is 114 characters. Since the prefix will be prepended to a UUID of 36 characters, the prefix is limited so as not to exceed the maximum Item reference length of 150 characters.

New references are generated in a different way if you use Author API within Author Site. If you don't specify a prefix here, Author Site will automatically generate a prefix consisting of the first 4 letters of your organisation's name followed by an underscore '_'. E.g. for Learnosity, the prefix would be 'LEAR_'. The prefix is then concatenated with a number to make the reference unique.

show
Type: boolean
Controls whether the reference is shown.

Default: false
boolean | object
Configuration for the Item save behavior.

Types
boolean
Controls whether the save button is shown on the Item edit view.
object
Holds configuration for the save button.
Properties:
persist
Type: boolean
Controls whether the Item data is persisted in Item bank.

Default: true
show
Type: boolean
Controls whether the save button is shown in the Item edit view.

Default: true
Properties:
show
Type: boolean

Controls whether Item level tagging (Tags tab) is shown in the Item settings view.

Default: true
object
Item template to be used when new Items are created. This will be ignored if the Item reference already exists in the itembank.

Properties:
type
Type: string

"dynamic": A flexible template that allows the author to choose a single or two-column layout, along with multiple (zero-to-many) Questions and/or Features.

Deprecated "single_question": A single column, single Question template.

Deprecated "feature_question": A two-column layout that allows for a single Feature in the left and a single Question in the right columns.

Default: "dynamic"
Properties:
edit
Type: boolean
Controls whether the Item title can be changed.

Default: true
mandatory
Type: boolean

Controls whether a title is required when saving an Item. The mandatory option requires both title.show and title.edit to be true.

Default: false
show
Type: boolean

Controls whether the Item title is shown. If true, the Item reference will not be shown and reference.show and reference.edit are ignored.

Default: false
object

Holds configuration for each widget (Question/Feature) on an Item.

Properties:
delete
Type: boolean
Controls whether authors are able to delete widgets.

Default: true
edit
Type: boolean
Controls whether authors are able to edit widgets.

Default: true
Array[object]

Holds Tag objects which are added to a new Item when saved.

A maximum of 50 Tags are allowed.

Note Tag types also defined in the hide_tags array will be added on save, but will not displayed in the UI.

See knowledgebase article on Tag formats for more information.

Types
object
Properties:
type
Type: string
Type that Tag belongs to
name
Type: string
Name of Tag
"tags_on_create": [
    {
        "type": "Subject",
        "name": "Math"
    },
    {
        "type": "Grade",
        "name": "Grade 9"
    }
]
object
Properties:
filter
Type: object

Options for filtering and restricting content that is displayed on the item list view

item
Type: object
Configuration options for each Item row in the item list.
limit
Type: integer
Control the number of Items listed on each page in the Item list view.
Valid value is an integer between 1 and 50.

Default: 10
toolbar
Type: object

Holds configuration for the Item list (search) toolbar.

object

Options for filtering and restricting content that is displayed on the item list view

Properties:
restricted
Type: object

Holds config for filters which are applied by default to the search criteria for the Item list results. Use this to restrict what items users can see, as these cannot be changed by the user.

Important If a tag filter is specified and a user should be allowed to create Items, tags matching that filter will need to be set on Item creation (using the setItemTags public method). You can disable this security feature by setting tags.allow_filtered_tags_overwrite option to true.

object

Holds config for filters which are applied by default to the search criteria for the Item list results. Use this to restrict what items users can see, as these cannot be changed by the user.

Important If a tag filter is specified and a user should be allowed to create Items, tags matching that filter will need to be set on Item creation (using the setItemTags public method). You can disable this security feature by setting tags.allow_filtered_tags_overwrite option to true.

Properties:
created_by
Type: array

Only display Items created by the users in the passed array of strings (based on their user.id).

A maximum of 50 string values are allowed.

Default: []
current_user
Type: boolean

Only display Items created by the current user (based on their user.id), if created_by is present, this option overrides created_by.

Default: false
status
Type: array

Only display Items that have a status that matches one of the statuses in the array. Valid statuses are published, unpublished, archived. If status is an empty array, then no restrictions apply.

Default: ['published', 'unpublished']
tags
Type: object

Holds config for tag filters which are applied by default to the search criteria for the Item list results.

Holds config for tag filters which are applied by default to the search criteria for the Item list results.

Properties:
allow_filtered_tags_overwrite
Type: boolean

If set to true, then a user can save Items which do not have the tags required by the tag filters below.

Default: false
all
Type: array

Each entry in the tags.all array is an object.

This object can follow three formats, the first being the TagsV2 object format where it only has the type and name properties.

It can also follow a variation of the said format where the name attribute is instead an array of strings which makes it more convenient to specify multiple tags of the same type.
For these two formats, Items must have all the specified tags to be visible.

The last format is another variation of the first one where the name property is omitted leaving the object with just the type property. In this case, Items must have at least one tag of the given type to be visible.

If there is more than one entry in tags.all, Items are only displayed if they have all of the tags specified for each entry in this initialization option.

See knowledge base article on advanced tag search for more information.

either
Type: array

Each entry in the tags.either array is an object.

This object can follow the TagsV2 object format where it only has the type and name properties.

It can also follow a variation of the said format where the name property is instead an array of strings which makes it more convenient to specify multiple tags of the same type.

Items are only displayed if they have at least one of the tags specified for at least one entry in this initialization option.

Note tags.either only supports an array of TagsV2 objects, not arrays of TagsV2 objects.

See knowledge base article on advanced tag search for more information.

none
Type: array

Each entry in the tags.none array is an object.

This object can follow the TagsV2 object format where it only has the type and name properties.

It can also follow a variation of the said format where the name property is instead an array of strings which makes it more convenient to specify multiple tags of the same type.

Items are only displayed if they don't have each tag specified for each entry in this initialization option.

Note For performance reasons, this initialization option will only work if tags.all or tags.either are set as well. If that's not the case, tags.none will be ignored.

See knowledge base article on advanced tag search for more information.

object
Configuration options for each Item row in the item list.
Properties:
enable_selection
Type: boolean
Controls whether a checkbox appears next to the items in the list. When one or more of these checkboxes are ticked, the items' JSON can be retrieved via public method getSelectedItems

Default: false
status
Type: boolean
Controls whether Item status icon is shown in Item list view.

Default: true
title
Type: object
url
Type: string

URL used as href for Items in Item list view when opening an Item in a new tab/window.

Must contain string ":reference" which will get replaced with the Item reference by Author API.

If this is not provided, then links cannot be opened in a new tab/window.

Properties:
show
Type: boolean

Controls whether Item titles are visible in the Item list view. When enabled, if an Item has a title, it will show its title, else its reference will be shown.

Default: false
object

Holds configuration for the Item list (search) toolbar.

Properties:
add
Type: boolean
Controls whether the create Item button is shown.

Default: true
browse
Type: object
Holds config options pertaining to the Item list's browse controls.

search
Type: object
Holds configuration options for the search toolbar.

Holds config options pertaining to the Item list's browse controls.

Properties:
controls

Ordered array of browse control objects to render within the browse control part of the toolbar. The supported types of browse control objects are defined in the toolbar browse controls section.

Ordered array of browse control objects to render within the browse control part of the toolbar. The supported types of browse control objects are defined in the toolbar browse controls section.

Types
TagObject
HierarchyObject
SeparatorObject
Holds configuration options for the search toolbar.

Properties:
show
Type: boolean

Determines if the search interface is displayed.

Default: true
controls
Type: array
Specifies search options. Possible values for the array are reference, content and title. title is only allowed if items are configured to display their title. reference is only allowed if title is disabled.

Default: ['reference', 'content']
widget_type
Type: boolean
Determines if search by widget type is available.

Default: true
status
Type: boolean
Determines if search by status is available.

Default: true
tags
Type: object
Contains options for the tag search.

Contains options for the tag search.

Properties:
show
Type: boolean

Determines if search by tags is available.

Default: true
object

Holds optional overrides for each label in the API. Each label has a default English value (shown in the example JSON), and any labels omitted from the label_bundle object will use that default value.

Properties:
config.label_bundle.dateTimeLocale
Type: string

Automatically localises dates and times using Moment.js. This defaults to an empty string, which Moment.js interprets as "en-us". Values can be passed in by language (such as "fr" for French), or region and language (such as "en-au" for Australian English).

toolTipDateFormat
Type: string

The tooltip date format will automatically be localised when you set dateTimeLocale, but can be further customised if needed. For more, see the Moment.js docs on String + Format.

toolTipDateTimeSeparator
Type: string

Set the separator between the date and time.
E.g. setting it to "at" would give "18/12/2017 at 18:39

toolTipTimeFormat
Type: string

The tooltip time format will automatically be localised when you set dateTimeLocale, but can be further customised if needed. For more, see the Moment.js docs on String + Format.

object
Properties:
back
Type: boolean

Controls whether the back button is shown on the widget edit view (when editing or creating a widget).

Setting this to boolean false hides the navigation bar in the tile view.

Setting widget_templates.back and widget_templates.save to boolean false hides the entire toolbar bar in widget edit view.

Default: true
save
Type: boolean

Controls whether the save button is shown on the widget templates view when editing a widget and upon new widget creation.

Setting widget_templates.save and widget_templates.back to boolean false hides the entire toolbar bar in widget edit view.

Default: true
widget_types
Type: object
Holds configuration for the widget types (Questions and Features) toolbar in the tile view upon new widget creation.

object
Holds configuration for the widget types (Questions and Features) toolbar in the tile view upon new widget creation.

Properties:
default
Type: string

Controls which widget type (Questions or Features) button is selected when first loaded.

Valid values are questions and features(case-sensitive).

Default: "questions"
show
Type: boolean

Controls whether the widget type (Questions and Features) buttons are shown.

Default: true
string
The mode of component to be loaded. This attribute is required. Currently we support:
  • "item_edit"
  • "item_list"
  • "activity_edit"
  • "activity_list"
In item_edit mode, users cannot navigate to the Item list. Thus, this mode is useful for integrating a custom CMS instead of using Learnosity's.

string | boolean
Applies in item_edit and activity_edit modes only, denotes the reference of the Item or Activity you are creating/editing. If the Item or Activity already exists, it will be loaded from the Item bank. Otherwise, a new item/activity will be created with the provided reference, and will be stored in the Item bank once saved.

If using Author API v1.20.0 or later, do not encode the reference by calling encodeURIComponent or any other encoding method since Author API already encodes it.

Keep track of your Item references and Activity references in your CMS, or use the list view (item_list and activity_list modes) for easier management of Items and Activities.

For item_edit mode, you can also pass false (Boolean), will simply initialize Author API without fetching and loading an Item or creating a new Item. The UI will be empty, and a reference can be set later.
object

Required user object to ensure that any content changes are properly tracked in an audit trail.

Properties:
email
Type: string
The email address of the content author.

firstname
Type: string
The first name of the content author.

id
Type: string
The unique identifier of the content author (case-sensitive).

lastname
Type: string
The last name of the content author.

object
Properties:
label
Type: string

If provided, specifies a label to render in the hierarchy selector dropdown for this hierarchy. By default, the hierarchy reference is used as the label.

reference
Type: string

Reference of a tag hierarchy to include in the browse control. The specified hierarchy must be pre-configured by the Learnosity support team. Contact us for details.

object
Properties:
hierarchies
Type: Array[HierarchyConfig]

Array of objects specifying which hierarchies are browseable with this control.

type
Type: string

Determines the type of the browse control to render. Specify "hierarchy" for the hierarchy browse control.

object
Properties:
type
Type: string

Determines the type of the browse control to render. Specify "separator" for the separator browse control.

object
Properties:
type
Type: string

Determines the type of the browse control to render. Specify "tag" for the tag browse control.

tag
Type: object

Object specifying which tag type is browsable with this control.

object

Object specifying which tag type is browsable with this control.

Properties:
label
Type: string

If provided, specifies the label to render for the tag control. By default, the tag type is used.

type
Type: string

Tag type on which the dropdown control should operate.

object

An ItemBankDefinition describes from which sources Items can be loaded for an Activity. It is used as an entry in Activity edit's item_banks.

Properties:
organisation_id
Type: number
Specifies the organisation from which the Items are loaded
item_bank_name
Type: string
The name of the Item bank displayed by Author API
item_pool_id
Type: string
The id of the Item pool from which Items are loaded
filter
Type: object
A specific filter for the Item bank. The specification of the filter is the same as the Item search root filter

The second parameter passed to window.LearnosityAuthor.init() is a string, containing a full CSS selector to an element on the HTML page. Each example below could be a valid value:

#learnosity_author // CSS selector based on id of an element
.learnosity_author // CSS selector based on a class of an element

This value tells Author API where to render itself on the page.

Note If the HTML element selector is not provided, Author API will attempt to look for the element with a id "learnosity-author".

Note See the quick start guide for more information on how to build an example HTML page.

The callbacks object contains optional callback functions that allow detection of the 'ready' status of a Author API instance and any errors encountered.

These events can be handled by defining a readyListener function and an errorListener function respectively.

Function to be called on an error event.

Parameters
error
Type: error
Object containing error details.
Function to be called when the API has been successfully initialised or reset.

See available events for more information.

Use assetRequest to integrate a custom asset loader into author API. If defined, Question Editor API will display a directory/file icon (i.e. "...") in fields where media is supported, as well as binding to the "insert image" button in the html WYSIWYG editor. If the icon is clicked by an author the function is called.

Parameters
mediaRequested
Type: string

Determine the type of media

Possible values:
  • "audio"
  • "image"
  • "video"
returnType
Type: string

Lets the function know whether to supply HTML, a URL, or an object that contains image's URL, width and height.

Possible values:
  • HTML
  • URL
  • UrlHeightWidth
callback
Type: callback()

Function to be executed once the returnType is ascertained.

attributes
Type: attributes

JSON object containing properties of the asset.

Properties:
src
Type: string
The URL of an asset.
alt
Type: string
The alternative text for an image.
height
Type: string
Height of the image.
width
Type: string
Width of the image.
cssClass
Type: string
CSS classes on the image.
function(mediaRequested, returnType, callback, attributes) {
    // Function that opens an asset browser or uploader and then calls
    // callback(URL|HTML|UrlHeightWidth)
},
array
Use customButtons for custom behaviour, e.g. adding an embedded video into a field. If customButtons are defined, Question Editor API will display a custom button in its toolbar. When the button is clicked by an author, the function is called.

Properties:
name
Type: string
A unique identifier for the button.
icon
Type: string
A link to the button icon (Recommended dimensions: 25px by 25px).
label
Type: string
The buttons label.
func(attribute, callback)
Type: callback()
The callback function which is executed when the custom button is clicked.
attributes
Type: array
A string array containing the path selectors of the rich text editors with which the custom buttons are to be associated with. If this is undefined (or empty), the buttons will be associated with all rich text editor instances.
For array type fields like options, you can either define a selector for a specific entry, e.g. options[0], or you can specify a selector targeting the whole array, e.g. options[*]. For more on rich text editor selectors see the editor layout components section.
"customButtons": [{
         "name": "name",
         "label": "label",
         "icon": "icon",
         "func": function( attribute, callback) {
             // Function that opens a form which enables embedding of custom
             // content into the editor and then calls callback(HTML)
         },
         "attributes": []
     }]
 } // EventOptions object.
object
Properties:
code
Type: number
Error code.
message
Type: string
Message containing information about the error.
status
Type: boolean
timestamp
Type: number
Returns time (in milliseconds) when the error occured.
callback
Properties:
attribute
Type: string
callback
Type: callback()