Metacog Tutorial 02: Playback and Training Instrumentation

Target Audience

This tutorial is aimed to front-end developers who want to include the Metacog Client Library into an existent Widget, with the goal of adding support for recording, playback and scoring of Training Sessions, as appears in the following video:

Please refer to the Tutorial 01 in order to gain context about the widget and the steps required to integrate the Metacog Client Library for basic logging functionality.

Instrumentation Strategy

In this tutorial we are going to refactor the instrumentation made for Tutorial 01, to add support for Playback functionality.

While in the first case we stick to the good practice of isolate the original code from the instrumentation code, in this case we are going to break that rule because the change required to make the widget aware of the Metacog Playback mechanism involves a deepest integration.

Dependencies

Playback and Training have the following dependencies:

  • Use metacog-x.x.x.js instead of metalogger-x.x.x.js: the metacog version of the client library includes all the functionality from the metalogger version, plus the TrainingToolbar modules required for building the UI (more details about different versions here).
  • Include JQuery and D3.js: JQuery is required for the Logger Panel and the Playback and Training toolbars. D3 is used for the indicators panel, an advanced feature for Scoring mode.

This is how looks now the index.html file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
  <script  src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
  <script type="text/javascript" src="js/d3.min.js"></script>
  <script type="text/javascript" src="js/chernoff.js"></script>
  <script type="text/javascript" src="//cdn.metacog.com/metacog-2.2.2.js"></script>
..
</head>

Client Library Initialization

The "mode" attribute in the configuration object passed to the Metacog.init method should be changed from "production" to "training".

1
2
3
4
5
6
7
8
9
Metacog.init({
    "session": {
        "application_id": '76e98b0fea0b86e2fa074e76bd606dc3', // Api credentials: Application key
        "publisher_id": '61580c99',  // Api credentials: Application ID
        "widget_id": "chernoff_tutorial"
    },
    mode: "training",
    log_tab: true
});

Training mode enables all the functionality of the toolbar: recording, playback, and scoring. In order to enable just the playback feature, you will need to set "mode" to "playback", but as you are not going to have the recording functionality, the training session to reproduce should exist beforehand.

Listener implementation

The Training and Playback Toolbar Guide contains a detailed explanation of both the Metacog Router mechanism and the role of the listener object: a object that works as an intermediary between the widget functionality and either the user input or the playback mechanism. In a few words, the goal of the listener is to offer an abstract interface to the event sources. Let's have a look at how it was implemented in the instrumentation.js file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var Listener = {};

Listener.feature_changed = function(data){
  Main.onChange(data.sliderid, data.value);
};

Listener.reset = function(){
  Main.reset();
  Main.render();
};

Metacog.Router.init(Listener);

Some things to notice about the listener's implementation:

  • It doesn't need to be named "listener". It doesn't ever need to be a new, empty object: you can use as listener any object that you already have in your widget, as long as it make sense to add this functionality to that object according to their original design.
  • The only requirement for a Listener is to implement methods with names that matches the names of the events: feature_changed and reset.
  • Changes to the Widget's model should happen only inside these methods (or should be triggered by them).

The last item also requires to change the original Main module of the widget: the part where model manipulation is attached to DOM events event handlers:

Before: Model is changed directly at DOM event handlers (only UI-aware)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
//attaching event listeners
    d3.selectAll("input").on("change", function(){
      Main.onChange(this.getAttribute("id"), this.valueAsNumber);
    });

    d3.selectAll("input").on("input", function(){
      Main.onChange(this.getAttribute("id"), this.valueAsNumber);
    });

    d3.selectAll("button#reset").on("click", function(){
      Main.reset();
      Main.render();
    });

After: UI events are delegated to Metacog Router. (both UI and Metacog aware)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
    //attaching event listeners
    d3.selectAll("input").on("change", function(){
      var sliderid = this.getAttribute("id");
      var value = this.valueAsNumber;

      Metacog.Router.sendEvent({
	      event: "feature_changed",
	      data: {
          id: sliderid,
          value: value
        },
	      type: Metacog.EVENT_TYPE.MODEL
      });
    });

    d3.selectAll("input").on("input", function(){
    });

    d3.selectAll("button#reset").on("click", function(){
      Metacog.Router.sendEvent({
	      event: "reset",
	      data: {},
	      type: Metacog.EVENT_TYPE.MODEL
      });
    });

As can be seen in the compared code, what we did was to move the original DOM-event handlers implementation to our new listener object, and redirect the DOM events as Metacog events throug the Router.

The final step involves to pass the listener object to the Router and turning on the training toolbar:

1
2
3
Metacog.Router.init(Listener);
Metacog.TrainingToolbar.init(true);
Metacog.Logger.start();

Lets have a look to the final result! You will need an Authentication Token to enable the training toolbar. It can be generated by using the Metacog API Sandbox or just try with this one:

52edbedaaffb5bd012bf71e56acdd5664296e498ca80f607ab25379c01e2089c

An authentication token creates an isolated working space for the users of a organization. The search functionality of the Training Toolbar will only list Training Sessions and Scores that had been created with the same Auth. Token used to activate the toolbar.

Summary and next steps

Once you have a widget instrumented with Playback support, you will be able to unlock all the power of the Metacog Platform: The usual workflow involves using the Training Toolbar to record Training Sessions, and using the Playback and Scoring toolbars to identify key behaviors and score them based on custom Rubrics.

Once the platform has a set of Scored Taining Sessions, you will be able to use the Metacog Client Library to ask the platform to score Student Sessions in real time!