Events

The Author API exposes number of public events so you can trigger custom functionality.

The callback will be called with a PublicEvent instance as an argument (unless indicated otherwise), which provides access to event data. The Event Data column gives information of what can be found in the event.data object.
Event name Description Event data
activityduplicate:error

Fires after an Activity has failed to duplicate.

If this is a shallow copy, this fires after the save:activity:error event. If this is a deep copy, the save:activity:error event doesn't get fired at all.

Version added: v2020.3.LTS
  • Error - object
    Information about the error.
activityduplicate:success

Fires after an Activity has successfully duplicated.

If this is a shallow copy, this fires after the save:activity:success event. If this is a deep copy, the save:activity:success event doesn't get fired at all.

Version added: v2020.3.LTS
activityedit:item:create
Triggered when the “Create Item” button is clicked in the Activity Editor.
activityedit:item:edit
Triggered when an Item reference or title is clicked in the Item list of the Activity Editor.
activityedit:items:added
Triggered when the “Add Items” button is clicked in the Item picker of the Activity Editor.
activityedit:saveable:changed

Triggered when the Activity becomes either saveable or not saveable. It is also triggered when the Activity edit view is rendered.

This event is controlled by the same conditions that control whether the Author API's save button is clickable. Since these conditions could change, this event may behave differently in different versions of Author API.

Therefore, this event is useful if you are creating your own save button and you want it to behave similiar to the Author API save button.

Version added: v2020.2.LTS
  • saveable - boolean
    Indicates whether the Activity can be saved, either via the saveActivity() public method or the save button.
add:widget

Triggered after an author clicks on the add widget button. Use event.preventDefault() to block adding widgets and prevent unexpected behaviour.

Version added: event.preventDefault support added in v2020.2.LTS
  • region_id - string
    ID of the region to which the widget has been added.
itemduplicate:confirm
Triggered after an author confirms duplication of an Item. This is only fired if the Item contains a shared passage.
  • itemJson - object
    JSON of the Item being duplicated.
itemedit:changed
Triggered after an author changes the Item layout, dynamic data or Item tags.
navigate

Triggered when the app location changes, e.g. when visiting an Item from the Item list; when doing a search; when going back from an Item to the Item list; etc.

Can use event.preventDefault() to prevent navigation.

Version added: event.preventDefault support added in v2020.2.LTS
  • location - string
    Latest location.
  • locationEncoded - string
    URI encoded version of latest location.
  • route - string
    Matching route (See list of routes).
open:activity

Triggered when an Activity in the Activity list is clicked. Can use event.preventDefault() to prevent the Activity from being opened.

Version added: event.preventDefault support added in v2020.2.LTS
  • activityJson - object
    JSON of the Activity being opened.
open:item

Triggered when an Item in the Item list is clicked. Can use event.preventDefault() to prevent the Item from being opened.

Version added: event.preventDefault support added in v2020.2.LTS
  • itemJson - object
    JSON of the Item being opened. This does not include questions or features.
render:activity
Triggered after an Activity has finished rendering.
render:activitylist
Triggered after the Activity list has finished rendering. The event is triggered after the first load of the Activity list, every search, sorting, and when loading additional pages.
render:item
Triggered after an Item (including any questions or features it contains) has finished rendering.
render:widgets
Triggered after only widgets (Questions and Features) are re-rendered in an Item (e.g. when navigating from edit to preview mode). This event is not triggered if the whole Item is rendered (e.g. when navigating from Item settings back to Item edit).
  • widgetReferenceList - array
    Array of widget references which were re-rendered. Widgets in the DOM have a span with attribute data-authorapi-widget-reference set to a reference in the list. You can search for like so:[data-authorapi-widget-reference="some-widget-reference"].
render:itemlist
Triggered after the Item list has finished rendering. The event is triggered after the first load of the Item list, every search, sorting, and when loading additional pages.
save

Triggered before an Item is to be saved. Can use event.preventDefault() to prevent the Item from being saved.

If the save event is triggered when editing a Question or Feature, function preventDefault accepts an optional argument {discardWidgetChanges: true/false}. If set to true, the modifications of the Question/Feature are discarded. The default value for discardWidgetChanges is false.

Version added: event.preventDefault support added in v2020.2.LTS
  • itemJson - object
    JSON of the Item to be saved.
save:activity

Triggered before an Activity is to be saved. Can use event.preventDefault() to prevent the Activity from being saved.

Version added: event.preventDefault support added in v2020.2.LTS
  • activityJson - object
    JSON of the Activity to be saved.
save:activity:error
Triggered after an Activity has failed to save.
  • activityJson - object
    JSON of the Activity that has failed to save.
  • Error - object
    Information about the error.
save:activity:success
Triggered after an Activity has successfully saved.
  • activityJson - object
    JSON of the Activity that has successfully saved.
save:error
Triggered after an Item has failed to save.
  • itemJson - object
    JSON of the Item that has failed to save.
  • Error - object
    Information about the error.
save:success
Triggered after an Item has successfully saved.
  • itemJson - object
    JSON of the Item that has successfully saved.
widgetedit:editor:ready
Only supported when using Question Editor v3.
Triggered when the Question Editor has finished loading all of the Global Layout components (e.g. tile view/editor view). For example, it is triggered after init() or reset() methods have successfully completed.
  • This event does not call the callback with a PublicEvent instance as an argument.
widgetedit:preview:changed
Only supported when using Question Editor v3.
Triggered when the author modifies any widget attributes and the question preview updates.
  • This event does not call the callback with a PublicEvent instance as an argument.
widgetedit:widget:changed
Only supported when using Question Editor v3.
Triggered when the editor changes states, e.g. when an author chooses a widget from the tile view or the setWidget() method is called.
Note that it is not triggered when an attribute within the widget changes, use widgetedit:preview:changed for that.
  • This event does not call the callback with a PublicEvent instance as an argument.
widgetedit:widget:ready
Only supported when using Question Editor v3.
Triggered when the editor panel has finished rendering and can be interacted with.
Can occur after setWidget() is called or the author chooses a widget from the tile view.
  • This event does not call the callback with a PublicEvent instance as an argument.
itemlist:selection:changed
Only supported in item_list mode and when item selection is enabled.
Triggered whenever the author selects/unselects an Item, and also when the clearSelectedItems() public method is called.
Note: If the author selects a few Items then opens an Item (clicks an Item reference/title), the previously made selection will be lost and the itemlist:selection:changed public event will not be fired.
  • itemRefs - array
    The references of the selected Items
Event name Description Event data
widgetedit:editor:ready
Only supported when using Question Editor v3.
Triggered when the Question Editor has finished loading all of the Global Layout components (e.g. tile view/editor view). For example, it is triggered after init() or reset() methods have successfully completed.
  • This event does not call the callback with a PublicEvent instance as an argument.
widgetedit:preview:changed
Only supported when using Question Editor v3.
Triggered when the author modifies any widget attributes and the question preview updates.
  • This event does not call the callback with a PublicEvent instance as an argument.
widgetedit:widget:changed
Only supported when using Question Editor v3.
Triggered when the editor changes states, e.g. when an author chooses a widget from the tile view or the setWidget() method is called.
Note that it is not triggered when an attribute within the widget changes, use widgetedit:preview:changed for that.
  • This event does not call the callback with a PublicEvent instance as an argument.
widgetedit:widget:ready
Only supported when using Question Editor v3.
Triggered when the editor panel has finished rendering and can be interacted with.
Can occur after setWidget() is called or the author chooses a widget from the tile view.
  • This event does not call the callback with a PublicEvent instance as an argument.
Event name Description Event data
All Events
All of the events which can be bound via the On public method can be unbound using the Off method.