Events

This article describes the events that Items API provides, and details how to bind callback functions to these events.

Supported Events

Items API provides methods which provide the ability to bind callback functions to particular events, usually triggered by user actions, or specific events occurring in the Assessment wrapper or Question element.

Assessment

Assessment events are events raised during the course of a user interacting with the assessment player. These are events concerning navigation, interactions with assessment level tools or options, or actions performed at the beginning and end of tests.

A demo showcasing event binding can be found here.

To learn more about how to bind to these events, please see the on(), once() and off() methods in the methods page.

Best Practices

To accurately listen to all Items API events, you should set up your event listener to be listening immediately after creating the Items API instance.

Example

var itemsApp = LearnosityItems.init(initOptions);

itemsApp.on("item:changed", function(itemIndex) {
    console.log("The current item index is: " + itemIndex);
});
Event name Description Event data
button:[name]:clicked

Fires whenever a custom region button or custom dialog button is clicked.

You would want to be notified about this event firing, because you will naturally have some code that you want executed when your custom button is pressed.

Note The name in the event is the name/id given to the custom button, for example a button referenced as 'myCustomButton' will have an event called 'button:myCustomButton:clicked'.

See also:
dynamic:item:changed

Fires when a dynamic Item is changed.

You would want to be notified about this event firing, because you want to know when a student has re-attempted the Item.

See also:
  • reference - string
    The id of the row being rendered in this attempt.
  • attemptIndex - integer
    The zero-based index representing the number of attempts made.
focused

Fires whenever the student has the browser window and tab open when the test comes into focus using the keyboard or mouse.

You would want to be notified about this event firing, because you want to know when the student has left the browser window to another application, and returned.

See also:

  • The unfocused event, to detect when the student is not interacting with the test browser window.
item:changed

Fires when the test has finished navigating to an Item.

You would want to be notified about this event firing, because you may want to perform an external action, such as starting a third-party service.

See also:
  • itemIndex - integer
    The zero-based index of the Item that has been navigated to and is now visible.
item:changing

Fires when the test first begins navigating away to another Item.

You would want to be notified about this event firing, because you may want to display a modal window between Items, for example.

See also:
  • itemIndex - integer
    The zero-based index of the Item that is being navigated to and is yet to be made visible.
item:goto

Fires when navigating between Items in an Activity. This event was created to align with the goto public method.

You would want to be notified about this event firing, because you can add custom logic to be handled while calling the goto public method for Items API.

Notes:

  • This event won't be triggered when the initial Item has been made visible.
  • Use the item:changed or item:changing events to track navigation to the initial Item.
  • Use item:load to track when an intro is made visible.

See also:
  • itemIndex - integer
    The zero-based index of the item that is being navigated to.
items:lazyload:batch

Fires when a new batch of Items have been loaded.

You would want to be notified about this event firing, for example, to know whether a specific Item has loaded so that you can navigate to it.

See also:
  • indicesAppended - array
    An array containing the zero-based index of the items that have been loaded in current batch.
items:lazyload:complete

Fires when all Items have been loaded successfully.

You would want to be notified about this event firing, because you may want to perform an external action after all batches have loaded, such as starting a third-party service.

See also:
items:lazyload:error

Fires when an error occurred during the Item batch loading process.

You would want to be notified about this event firing, so that you can notify the user that a problem occurred during loading.

See also:
item:load

Fires when a selected Item has been loaded, rendered and is ready for the user to interact with.

You would want to be notified about this event firing so that you can execute additional code based on the Item that has loaded, such as tracking user interactions or automatically opening the calculator.

See also:
item:setAttemptedResponse

Fires when a student has entered a response into a Question within an Item.

You would want to be notified about this event firing so that you can execute additional code based on the response content of an Item (in other words, whether the student has made an attempt or not).

See also:
item:beforeunload

Fires when the selected Item is about to be deactivated. This will be fired before the item:unload event.

If preventDefault is called, the current item will not be unloaded and other events like item:unload will not be fired

You would want to be notified about this event firing so that you can gracefully control if the current user can navigate to the next item or not, for example.

See also:

  • The item:load event, the event that occurs when an Item has been loaded, rendered and is ready for the user to interact with.
  • event - object
    An object containing the preventDefault method that can be used to prevent the current item from being unloaded.
item:section:next

Fires just before a section transition.

You would want to be notified about this event firing, so that you can display a custom message to the user, warning them about the change between assessment sections, for example.

See also:
item:unload

Fires when a selected Item is no longer active and the user can no longer interact with it.

You would want to be notified about this event firing so that you can gracefully complete all actions for the current Item and save your own data, for example.

See also:

  • The item:load event, the event that occurs when an Item has been loaded, rendered and is ready for the user to interact with.
item:warningOnChange

If the warning_on_change option is enabled in the items navigation. This event fires when a user attempts to leave an Item that is unattempted or only partially attempted.

You would want to be notified about this event firing so that you can execute additional code to display a custom modal with additional prompts, for example.

Notes:
items:fetch

Fires when a new batch of Items is being fetched using the addItems public method.

You would want to be notified about this event firing so that you can know when dynamic Items are being fetched using adaptive and dynamic assessments so that you can keep track of the navigation state in your own application, for example.

See also:
items:fetch:done

Fires when a batch of Items has been successfully fetched using the addItems public method.

You would want to be notified about this event firing so that you can know when dynamic Items have been fetched using adaptive and dynamic assessments so that you can keep track of the navigation state in your own application, for example.

See also:
section:changed

Fires when the student has navigated into a new section.

You would want to be notified about this event firing so that you can execute some code based on the transition to the new section of the assessment. For example, if the student has navigated from a math section into an English section, you may want to add/remove a calculator or line reader feature.

See also:
test:finished:discard

Fires when the proctor has exited, discarded the test and the process has completed. The student will now be redirected to a preconfigured discard URL, if provided in the init options.

You would want to be notified about this event firing so that you can display an exit message to the student before the redirect occurs, for example.

See also:
test:finished:save
Triggered when a test is finished and has successfully been saved.
test:finished:submit

Fires when the student clicks the "Close" button on the outro screen. This event will also be fired automatically after a proctor submits the Activity.

You would want to be notified about this event firing so that you can execute any logic in your application that will occur after the test submission.

Notes:

  • If there's no outro Item, or if the Item is disabled in the Activity configuration, this event will fire immediately after a successful Activity submission.
  • This event will not be fired if submission did not complete, or was unsuccessful.

See also:
test:panel:hide

Fires when a modal dialog is hidden.

See the DialogList object definition for more information.

test:panel:show

Fires when a modal dialog is shown.

Note Assessment content is hidden while modal dialogs are visible.

See DialogList for more information.

test:pause

Fires when a test has been paused by the student (when the timer for a test is paused). Specifically, this can happen when certain modal dialog windows are shown. For example, the pause dialog, the section change and the save and submit dialogs.

Note The timer will not pause when the student switches to another browser tab, or another application.

You would want to know that the test has paused, because you might want to report that back, or because you are keeping track of time (for example).

See also:

  • The test:resume event, which fires when a modal dialog, which has paused the timer, is closed (because you want to know when the state of the test is no longer paused).
test:reading:end
Triggered when reading time has ended.
test:reading:start
Triggered when reading time has started.
test:ready
Triggered once a test is ready to be started.
test:resume

Fires when the test timer resumes ticking after it was paused. Specifically, when a modal dialog window that paused the timer is closed.

You would want to be notified about this event firing, because you want to be notified when the timer has started ticking, for the student's assessment (in other words, the "test clock") has begun.

Note This is not related to the resume Activity state.

See also:

  • The test:pause event (because you want to be notified that the student has taken some action that pauses the timer),
  • The getTime public method (because it can be called to see the current elapsed time in the assessment),
  • The time:change event (because you want to know when the test time is updated), and
  • The test:start event (because you want to know when the test timer begins ticking).
test:save
Triggered when a test has a pending save.
test:save:error
Triggered when there is an error saving a test.
test:save:success
Triggered when saving a test is successful.
test:start

Fires when the test commences. This is usually when the student clicks the "Start" button in the intro, but may also happen automatically when the intro is hidden, or when in "resume" or "review" states.

You would want to be notified about this event firing, because you might want to start a session on your own servers at the same time, for example.

Note This event will fire before the readyListener callback in "resume" and "review" states.

See also:
  • appInstance - object
    The instance of the Assess API.
test:submit
Triggered when test submission begins.
test:submit:error
Triggered when there is an error submitting a test.
test:submit:success
Triggered when a test is successfully submitted.
time:change

Fires once a second, each time the test timer is updated.

You would want to be notified about this event firing, because you might want to perform some action at a given point in time.

Note This event will not fire during reading time.

See also:
  • timeElapsed - integer
    The time elapsed in seconds.
time:end

Fires when the assessment's max_time has elapsed. max_time is a configurable time limit.

You would want to be notified about this event firing, so that you can take some action (such as communicating with the student), before the next available event, which is submission.

Note This event will only fire when the max_time initialization option is configured.

See also:

  • The max_time setting, because this must be set for this event to work, and
  • The submission event, the event that follows immediately after time:end .
test:proctor:exitAndSubmit
Triggered when a test is exited and submitted by a proctor.
test:proctor:goto
Triggered when a proctor navigates the test to a different item.
test:proctor:paused
Triggered when a proctor pauses a test.
test:proctor:resumed
Triggered when a proctor resumes a test.
test:proctor:save
Triggered when a proctor saves a test.
test:proctor:terminated
Triggered when a proctor terminates a test.
unfocused

Fires whenever the student moves their focus away from the test browser window using the keyboard or mouse.

You would want to be notified about this event firing, because you want to know when the student has left the test browser window to another application.

See also:

  • The focused event, to detect when the student is not interacting with the test browser window.

Questions

Question events are events raised during the course of a user interacting with a specific question, such as whether they have changed the question model (i.e. attempted the question) or clicked the "check answer" button.

To learn more about how to bind to these events, please see the on(), once() and off() methods for the Question Object on our Methods section.

Example

var questions = itemsApp.questions();

Object.values(questions).forEach(function(question) {
    question.on("changed", function() {
        console.log("student has attempted a question");
    });
});
Event name Description Event data
changed
Fired when model value has changed.
beforeValidate

Fired before the question is validated by clicking Check Answer button or via public method validate.

If this event is listened to, developer can prevent the validation from happening by calling event.preventDefault
  • event - object
    Calling event.preventDefault() to prevent the validation from happening.
validated
Fired when validation of question response has completed.
masked
Fired when masking for the corresponding question is enabled.
  • response_id - string
playback:assetLoaded

Important Audio or Video question type only.

Fired when the playback asset within audio or video question type is loaded.
playback:complete

Important Audio or Video question type only.

Fired when the playback within audio or video question type has ended.
playback:paused

Important Audio or Video question type only.

Fired when the playback within audio or video question type has been paused.
playback:resumed

Important Audio or Video question type only.

Fired when the playback asset within audio or video question type has been resumed.
playback:started

Important Audio or Video question type only.

Fired when the playback asset within audio or video question type has started.
playback:stopped

Important Audio or Video question type only.

Fired when the playback within audio or video question type has stopped.
recording:paused

Important Audio or Video question type only.

Fired when the recording within audio or video question type has been paused.
recording:resumed

Important Audio or Video question type only.

Fired when the recording within audio or video question type has been resumed.
recording:started

Important Audio or Video question type only.

Fired when the recording within audio or video question type has started.
recording:stopped

Important Audio or Video question type only.

Fired when the recording within audio or video question type has stopped.
render
Fired when a question has rendered.

Features

Feature events are events raised during the course of a user interacting with a specific feature, such as playing audio or video features.

To learn more about how to bind to these events, please see the on(), once() and off() methods for the Feature Object on our Methods section.

Example

var features = itemsApp.features();

Object.values(features).forEach(function(feature) {
    feature.on("playback:started", function() {
        console.log("student has started playing an audio or video feature");
    });
});
Event name Description Event data
begin
Fired when the Feature begins.
complete
Fired when the Feature completes.
playback:started

Important Audio and video feature types only.

Fired when the playback within audio or video features has started.
playback:assetLoaded

Important Audio and video feature types only.

Fired when the playback asset within audio or video features is loaded.
playback:complete

Important Audio and video feature types only.

Fired when the playback within audio or video features has ended.
playback:paused

Important Audio and video feature types only.

Fired when the playback within audio or video features has been paused.
playback:resumed

Important Audio and video feature types only.

Fired when the playback asset within audio or video features has been resumed.
playback:stopped

Important Audio and video feature types only.

Fired when the playback within audio or video features has stopped.
render
Fired when a feature has rendered.