{{warning}}

Player Methods

Interact with the Item Player by implementing callback methods or by calling the API methods exposed by the player.

setMode()

Change the current view mode of the player:

    player.setMode("view");
    player.setMode("gather");
    player.setMode("evaluate");
    player.setMode("instructor");

Note: Changing the mode to 'evaluate' will retrieve correct answers, feedback and score information from the server and deliver them to the client. The method is disabled if 'secure' is enabled.

The setMode method takes a callback which is called when setMode finishes

    player.setMode("view", function(err){
      if(err){
        //setMode failed
      } else {
        //setMode succeeded
      }
    });
    //Note: that you'll also receive an error through the main error handler that you passed in to the constructor.

saveResponses(countAsAttempt = false, callback)

Persist the current state of a user's responses in the player to the server.

    player.saveResponses(isAttempt, function(result){
      if(result.error){
        console.warn(result.error);
      } else {
        console.log(result.session);
      }
    });

The score based on the current response values will be calculated on the server, and made available through the getScore() method.

The optional boolean parameter countAsAttempt defaults to false. Use this in conjunction with countAttempts() if you wish to allow a user have several attempts to response to an item.

The callback receives an object that has 2 properties: error and session. error may or may not be defined. If it is you should handle it.

countAttempts(callback)

Returns the number of times saveResponses(countAsAttempt = true) as been called.

    player.countAttempts(function(count){
      console.log("countAttempts result" + count);
    });

getScore(format, callback)

Get the calculated score based on the current state of responses. The method is only available if 'secure' is not enabled.

The format parameter can be either 'scaled' or 'percent'. If it is 'scaled', a value between 0 and 1.0 is returned. If it is 'percent' a value between 0 and 100 is returned.

    player.getScore('percent', function(score){
      console.log("getScore result" + score);
    });

completeResponse(callback)

Mark the item as completed.

    player.completeResponse(function(error, isComplete) {
      if (error) {
        console.warn(error);
      } else {
        console.log(isComplete);
      }
    });

This can be called when the student or system determines that the no further revision of the responses are intended. This is optional in basic use, but is used in tandem with the secure option, which prevents the answer from being revised after it has been marked as complete.

isComplete(callback)

Check if the item has been marked completed.

    player.isComplete( function callback(complete) {
      console.log('complete?', complete); //complete? true|false
    });

getSessionStatus(callback)

     player.getSessionStatus( function callback(status) {
      console.log('status:', status); //status: {...}
    });

This method allows you retrieve the current state of user's response to the item. It returns an object with the following properties:

  • allInteractionsHaveResponse (number) - is there a response entered for all interactions in the item?
  • interactionCount (number) - number of interactions in the item
  • interactionsWithResponseCount (number) - number of interactions which have some response input
Name Type Description
allInteractionsHaveResponse boolean Is there a response entered for all interactions in the item?
interactionCount number Number of interactions in the item
interactionsWithResponseCount number Number of interactions which have some response input

This is useful for example to set the paramaters for final submission acceptance (e.g., all or some partial number of questions have a response).

reset()

Reset clears all responses and state from the interactions in the item.

Callback Methods

The following callback functions can be added to the options object passed into the Item Player.

    var options = {};
    options.onSessionCreated = function(sessionId) {};
    options.onInputReceived = function(itemStatus) {};
    options.onPlayerRendered =  function(){};

onSessionCreated(sessionId)

Only available when gather mode is active and triggered when the player is loaded with an itemId. In this case the player will create a new session and callback this function with the new sessionId.

onInputReceived(itemStatus: Object)

Only available when gather mode is active and triggered when user input is received for interactions in the item Receives itemStatus, an object with information about the current state of the user's response:

Name Type Description
allQuestionsAnswered boolean Is a response present for all interactions in the item?
questionCount number Number of interactions in the item
questionsWithInput number Number of interactions which have input

onPlayerRendered()

This callback is called once the player is loaded in the UI and ready to be used. You should not call player methods until the callback has been called.