Training and Playback Toolbar Guide

Overview

This document is focused on the technical aspects of integrating the metacog™ Training and Playback Toolbar into a Learning Object. Developers are the intended audience. For a user manual of the Toolbar, please check the Training and Playback Toolbar User manual

Introduction

Instrumentation for basic event logging as described in the Instrumentation guide just requires the use of the Metacog.send method. But a playback-enabled instrumentation requires most of the time some refactoring effort.

Let's see how the diferent instrumentation modes relates to each other:

  • A. Original Widget: This is the original widget. The typical architecture is to attach event handlers to UI events to fire model and view updates.
  • B. Logging-only Widget: Calls to Metacog.send method are made at those points of code where there are relevant changes in model and view in order to send notifications of those changes to the Metacog Platform. Calls can be directly placed in the relevant methods or using method interception to keep the isolation betwen widget's original code and instrumentation code.
  • C. Playback-enabled Widget in recording mode: The link between UI events and widget's model and view had been broken, and a new object, the "custom listener" appears as an intermediate for those events (see Metacog.setEventListener). The logic code in the widget had been refactored to assume that all events will be triggered by the listener, not for the UI. The listener will send events to the Metacog platform and then fire the appropiate model-view code.
  • D. Playback-enabled Widget in playback mode: UI events are discarded silently. Previously recorded events are retrieved from Metacog Platform and passed to the listener. Notice that the widget code doesn't need to know if the events comes from the UI or the backend, only that they come from the listener.

How intrumentation works (optional)

This is an optional section, whose intention is to provide an insight on the internal mechanism of the Library. If you prefer to skip this, please go to the next section "implemeting playback support on your widget"

The following diagram present the main objects contained in the metacog client library. Both scenarios show the interactions of a playback-enabled widget, but the one in the left is in Training Session's recording mode, while in the right the playback mode is displayed.

Training Session's Recording mode:

  1. The widget uses Metacog.send calls to send UI events through the router (instead of using them to manipulate widget status).
  2. The router performs two tasks at once: send the event to the logger (2.b), for remote storage, and pushing-back the event through the Listener object (2.a). It is here that the logic of the widget is executed.
  3. The Logger stores the events in a temporal persistent queue (either an IndexedDB database or the LocalStorage, according to the browser's support).
  4. It also will poll the queue periodically, packaging events stored there and send to the Metacog Platform through the Training API (an endpoint different to the production endpoint used for simple logging widgets).

Playback Mode:

    Events stored previously in the Metacog Platform are retrieved through paginated network calls.
  1. Those events are injected into the Router. In this mode, the router will only pass the events to the listener, ignoring the call to the Logger.

Implementing playback support on your widget

The steps to initialize the playblack-enabled Learning Object involves the following steps:

  1. Initialize the Metacog Library.
  2. Creation of a listener to process Metacog Events.
  3. Register the listener with the Library.
  4. Display the training toolbar.

Configuration Object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Metacog.init({
        "widget": "My Learning Object",
        "widgetVersion": "1.1.0",
        "session": {
            "publisher_id": 'e9d10dx1',
            "application_id": '0b559f05489e2bwer0f52f09x9',
            "widget_id": 'My_LO_01',
            "learner_id": studentId,
            "session_id": sessionId
        },
        "log_tab":true,
        mode:"training"
    }, function(){
  console.log("Metacog Library is ready!");
});

Initialization happens in the same way that for a only-logging widget, through the Metacog.init method. The only difference is the value of the attribute mode.

The mode attribute defines what is going to do the logger with all the events it receives. available modes are production, training and development.

  • production sends the events to the main input API, that is the way how basic instrumented Learning Objects behave.
  • training sends the events to the training API endpoint while in "Training Session's Recording Mode", and also enables the playback and scoring functionality. All these features are handled through the Training Toolbar.
  • development mode consumes all the events locally, without sending them to any server. Events are printed to the Log tab.

Metacog Event Listener

Now we need to create an object that will be invoked each time a event pass through the router. It is just a plain javascript object. The router will examine the methods of the object using a convention over configuration rule: if there is a event named "my_event", it will explore the listener for a method named on_my_event. If that method exist, it will be invoked, passing as parameter the original event.data.

1
2
var listener ={};
listener.my_event = function(data){...};

Default callback

It is not mandatory to catch all the possible events in the listener. If the router does not find a callback for a given event, it will try to invoke by default the on_event(evt) method, if present. Notice that this method receives the whole event object, not just the data attribute, because as it will receive different events as parameters, the developer will need access to the evt.name attribute.

Registering the listener

The last initialization step involves to register the listener in the Metacog Client Library.This is done through the Metacog.setEventListener method. At this point, all the components are ready for sending events to the metacog™ platform.

1
Metacog.setEventListener(listener); 

Training Toolbar initialization

A call to Metacog.TrainingToolbar.init is required to load the UI of the training toolbar, and make it visible:

1
Metacog.TrainingToolbar.init(true);

Starting the logger

Once all the objects had been initialized, it is time to start the process that consumes events in the logger. this is done through the Metacog.start() method.

The reason why the logger did not starts automatically to process is because some learning objects may need to wait until all of its resources are loading or maybe there are some initial screens with authentication forms and there is the need to validate the user before sending events to the platform.

A possible good point to start the logger is the done callback of the Metacog.init method.

The next code snippet shows the proper way to send events and process them in the listener:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
Metacog.Router.sendEvent({
   event:'init',
   data:{
          att1: "value1",
          att2: "value2"
         },
   type:Metacog.EVENT_TYPE.MODEL
   });

listener.init = function(data){
 console.log("I got a init event, with att1="+data.att1 + " and att2="+ data.att2);  
}
ic implies that there will be more method declarations in the learning object.

Handling internal events

When using the Training Toolbar and the Playback Controller, some special events are thrown through the router in order to keep things in sync. You can intercept and use those events in the same listener callback used for regular events.

These internal events can be recognized because their type is metacog. Internal events are neither send to the Metacog Platform nor displayed in the log_tab. The list of internal events include:

  • metacog-setmode: it has an 'enabled' boolean attribute that indicates when the mode is changed from recording to playback.

Styling the Toolbar

The toolbar uses an external HTML template and CSS files to define its look and feel. The path to these resources may be changed through the MetaConfig object, allowing a full customization of the UI to adapt the toolbar to the visual styles of the Learning Object.

1
2
3
4
5
6
7
var config = {
training: {
        toolbar:{
            css: 'http://cdn.metacog.com/training-toolbar.css',
            template: 'http://cdn.metacog.com/training-toolbar.html'
        }
};