Question type contract

The following sections list the required contracts that a library must implement.

Functions 

getAnswerGiven()

Checks if answers for this task has been given, and the program can proceed to calculate scores. Should return false if the user can not proceed yet.

Return value

Returns {Boolean} true if answers have been given, else false.

  Blanks.prototype.getAnswerGiven = function () {
    return this.answered || this.blankIsCorrect;
  };

getScore()

Calculates the user's score for this task, f.ex. correct answers subtracted by wrong answers.

Return value

Returns {Number}  User's score for this task.

  Blanks.prototype.getScore = function () {
    return this.points;
  };

getMaxScore()

Calculates the maximum amount of points achievable for this task.

Return value

Returns {Number} Max score achievable for this task.

  Blanks.prototype.getMaxScore = function () {
    return this.calculateMaxScore();
  };

showSolutions()

Displays the solution(s) for this task, should also hide all buttons.

Return value

none

  Blanks.prototype.showSolutions = function () {
    this.showAllSolutions();
    //Hide solution button:
    this._$solutionButton.hide();
    this._$retryButton.hide();

    //Disable dragging during "solution" mode
    this.disableDraggables();
  };

resetTask()

Resets the task to its initial state, should also show buttons that were hidden by the showSolutions() function.

Return value

none

  Blanks.prototype.resetTask = function () {
    this.points = 0;
    this.rawPoints = 0;

    //Enables Draggables
    this.enableDraggables();

    //Reset position and feedback.
    this.draggables.forEach(function (draggable) {
      draggable.resetPosition();
    });

    //Show solution button
    this.$solutionButton.show();
    this.$retryButton.hide();

    // Reset score message
    this.showScore();

  };

getXAPIData()

Retrieves the xAPI data necessary for generating result reports.

Return value

An object with the following fields:

• statement: Should contain the xAPI statement that is usually sent on 'answered. Refer to the xAPI spec.
• children: Optional field with an array of all children's xAPI event. This is implemented by calling getXAPIData() on all children of the content type.

The following properties of the statement structure is essential for the functions where this contract is used: 

• object.definition.interactionType: Type of the interaction. Choose from xAPI spec.
• object.definition.description: Question text and any additional information to generate the report.
• object.definition.correctResponsesPattern: A pattern for determining the correct answers of the interaction. See spec.
• object.definition: Additional definition properties required for the specific interaction type.
• result.response: User answers for interaction. See spec.
• result.score.min: Minimum possible score for task
• result.score.raw: Raw user score
• result.score.max: Maximum possible score for task
• result.score.scaled: Score in percentage.

getCurrentState()

Retrieve a value representing the current state of the task. This is required for libraries that wish to support resume functionality. In H5P integrations where resume is enabled the value returned by this method will be provided as the `previousState` object property of the 3rd parameter passed to the library's constructor (often named `extras` or `contentData` in source). It is then up to the library to use this previousState in order to implement resume functionality, allowing users to pick up where they left off. H5P integrations may call this method continuously to poll for changes, so it is recommended to avoid expensive computations.

The returned object can have any shape, but to fully support resume features its initial or "empty" state should be such that when passed to `H5P.isEmpty` it evaluates to true. This allows H5P integrations to detect whether there is in fact some significant state currently stored, and the user may be presented with the option to clear this state.

Here is some recommended reading for developers looking to implement resume in content types:

• https://snordian.de/2023/03/04/how-does-resuming-an-exercise-work-in-h5p/
• https://snordian.de/2023/03/06/how-can-i-implement-support-for-resuming-in-an-h5p-content-type/

Variables

params.behaviour.enableSolutionsButton {Boolean}

A boolean class parameter that determines if a "show solution" button will be shown in your content type.

Description

The parent content type must be able to override whether a solution button should be displayed. Implementing a class parameter called "enableSolutionsButton" and letting this value determine if the solution button will be displayed, will allow the parent content type to override this value.

Type

Boolean

    // Set this.params.behaviour.enableSolutionsButton to true or false through semantics.
    if (this.params.behaviour.enableSolutionsButton === true) {
      this.addSolutionsButton();
    }

params.behaviour.enableRetry {Boolean}

A boolean class parameter that determines if a "retry" button will be shown in your content type.

Description

The parent content type must be able to override whether a solution button should be displayed. Implementing a class parameter called "enableRetry" and letting this value determine if the solution button will be displayed, will allow the parent content type to override this value.

Type

Boolean

    // Set this.params.behaviour.enablRetry to true or false through semantics.
    if (this.params.behaviour.enableRetry === true) {
      this.addRetryButton();
    }