amp-up.io QTI 3 Stimulus Player Component

The amp-up.io QTI 3 Stimulus Player Component ("QTI 3 Stimulus Player") is a 100% JavaScript component that aims to encapsulate the best practices and behaviors of the IMS Global QTI 3 Assessment Stimulus specification. A conforming QTI 3 authoring or exporting system can construct a QTI 3 Assessment Stimulus XML solution that will "play" authentically and reliably in the QTI 3 Stimulus Player - according to the Best Practices Implementation Guide which can be found here:

IMS Global QTI v3 Best Practices and Implementation Guide

The QTI 3 Stimulus Player supports all three sub-elements permitted in a qti-assessment-stimulus which are:

• qti-stylesheet
• qti-stimulus-body
• qti-catalog-info

About The Project

The QTI 3 Stimulus Player component is 100% JavaScript and implements the full expressive QTI 3 Assessment Stimulus XML vocabulary according to best practices - including support for qti-stylesheet injection, qti-catalog-info and Personal Needs and Preferences. Consequently, you don't have to know anything about QTI. Just install the component in your project, inject qti-assessment-stimulus XML, and go!

Getting Started

1. Clone the repo

git clone https://github.com/amp-up-io/qti3-stimulus-player.git

2. Installation

npm install

3. Compiles and hot-reloads for development

npm run serve

4. Compiles, minifies, creates package

npm run build:npm

Usage

1. Import QTI 3 Item Player CSS

The Qti 3 Stimulus Player contains a dependency on Qti3Player (the Item player) in order to access the built-in shared CSS.

// The Qti3Player built-in CSS
import 'qti3-item-player/dist/qti3Player.css'

2. Load the QTI 3 Stimulus Player component into your Page or Template

<Qti3StimulusPlayer
  ref="qti3Stimulusplayer"
  :container-class="containerClass"
  :container-padding-class="containerPaddingClass"
  :color-class="colorClass"
  @notifyQti3StimulusPlayerReady="handleStimulusPlayerReady"
  @notifyQti3StimulusReady="handleStimulusReady"
  @notifyQti3StimulusCatalogEvent="handleStimulusCatalogEvent"
/>

3. Listen for the QTI 3 Stimulus Player 'notifyQti3StimulusPlayerReady' event

This event signifies that the QTI 3 Stimulus Player component is loaded and ready for action. The following snippet is a sample handler for the notifyQti3StimulusPlayerReady event. QTI 3 Stimulus Player hands itself as an argument to the notifyQti3StimulusPlayerReady event, thus simplifying further QTI 3 Stimulus Player API calls.

/**
 * @description Event handler for the QTI3StimulusPlayer component's 'notifyQti3StimulusPlayerReady'
 * event.  This event is fired upon mounting of the Qti3StimulusPlayer component.
 *
 * The Qti3StimulusPlayer is now ready for XML loading.
 * @param {Component} qti3StimulusPlayer - the Qti3StimulusPlayer component itself
 */
handleStimulusPlayerReady (qti3StimulusPlayer) {
  this.qti3StimulusPlayer = qti3StimulusPlayer
}

4. Load a QTI 3 qti-assessment-stimulus into QTI 3 Stimulus Player

After QTI 3 Stimulus Player is loaded and ready (see #3 above), QTI 3 Stimulus XML can be loaded directly into QTI 3 Stimulus Player via the Player's loadStimulusFromXML method which takes two arguments xml {String} and configuration {Object}.

// Load qti-assessment-stimulus XML with a configuration.  Use the 'this.qti3StimulusPlayer' reference
// saved in the notifyQti3StimulusPlayerReady event handler.
this.qti3StimulusPlayer.loadStimulusFromXml(xml, configuration)

4a) About a Configuration

The configuration object is used to specify runtime context to QTI 3 Stimulus Player during the stimulus session loaded in loadStimulusFromXml. A configuration object has the following structure:

configuration: {
  guid: <{String} identifier used to track item state>,
  pnp: <{Object} used to define Personal Needs and Preferences>,
  sessionControl: null // ignored
}

4b) Constructing a Configuration

The following snippet is an example of how an application can construct a configuration.

// Intialize
const configuration = {}

// Stamp a stimulus' tracking guid (if any) onto the configuration
configuration.guid = myItemTrackingGuid

// QTI 3 Stimulus Player includes a helper class called 'PnpFactory' which can be used
// to build a Personal Needs and Preferences definition.
// The Default pnp object in the PnpFactory is:
const pnp = {
  textAppearance: {
    colorStyle: 'qti3-player-color-default'
  },
  // Glossary is universal support turned on (true) by default
  glossaryOnScreen: true,
  // Keyword translation is off ('') by default
  keywordTranslationLanguage: '',
  // Custom SBAC Illustrated Glossary is off (false) by default
  extSbacGlossaryIllustration: false,
  layoutSingleColumn: false // unsupported - see Roadmap (Simplified Layout)
}

// Set the configuration's 'pnp' property
configuration.pnp = pnp

// Session Control is ignored by QTI 3 Stimulus Player.
configuration.sessionControl = null

In the absence of a pnp property, QTI 3 Stimulus Player will use defaults, or previous settings, for presentation and accessibility supports. The sessionControl property is ignored by QTI 3 Stimulus Player.

5. Listen for the QTI 3 Stimulus Player 'notifyQti3StimulusReady' Event

QTI 3 Stimulus Player triggers a notifyQti3StimulusReady event upon completion of the Player's loadStimulusFromXML method. The following snippet is a sample handler for the notifyQti3StimulusReady event.

/**
 * @description Event handler for the Qti3StimulusPlayer component's 'notifyQti3StimulusReady'
 * event.  This event is fired upon completion of the qti-assessment-stimulus
 * component's loading of XML.
 */
handleStimulusReady () {
  console.log('QTI 3 Stimulus XML is loaded and rendered!')
}

6. Stimulus 'Catalog' Events

A stimulus 'catalog' event is triggered by QTI 3 Stimulus Player when a user selects a control (such as a highlighted term) within the stimulus' presentation that is bound to a stimulus' catalog. QTI 3 Stimulus Player will display its own Catalog Dialog component when a user selects a control within the stimulus' presentation that is bound to glossary, keyword translation, and custom ext:sbac-glossary-illustration events.

An encapsulating application may instrument the QTI 3 Stimulus Player to not display its internal Catalog Dialog component by specifying the boolean attribute suppress-catalog-messages. When instrumenting QTI 3 Stimulus Player to suppress its internal catalog message display, an application should implement a handler for the notifyQti3StimulusCatalogEvent. This permits an application to handle and display catalog event messages using its own UX. Example:

<Qti3StimulusPlayer
  ref="qti3Stimulusplayer"
  suppress-catalog-messages
  @notifyQti3StimulusCatalogEvent="handleStimulusCatalogEvent"
/>

    /**
     * @description Handler for QTI stimulus catalog events such as 'glossary' events.
     * @param {Object} event - object containing a catalog event payload
     * Sample event schema:
     * {
     *   type: "glossary",
     *   term: "acronym",
     *   catalogIdRef: "glosscat",
     *   data: [
     *     {
     *       support: "glossary-on-screen",
     *       card: {
     *         content: ""<p>An abbreviation.</p>"",
     *         properties: {
     *           name: "qti-html-content"
     *         }
     *       }
     *     }
     *     ... additional Card supports in Catalog based on PNP ...
     *   ]
     * }
     */
    handleStimulusCatalogEvent (event) {
      console.log('[StimulusCatalogEvent][Type: ' + event.type + ']', event)
      switch (event.type) {
        case 'glossary':
          // Do something!
          break
        default:
      }
    },

Supported Keyword Translation Language Codes

QTI 3 Stimulus Player groups PNP 'glossary-on-screen', 'keyword-translation', and 'ext:sbac-glossary-illustration' supports into 'glossary' events that will trigger a Catalog event of type 'glossary'.

As of the 0.1.0 release, QTI 3 Stimulus Player supports the following IS0 639 language codes for keyword translations:

{ ar | cmn | de | en | es | fr | hmn | it | ja | ko | my | nl | pa | ru | so | tl | uk | vi | yue | zh }

7. About Dynamic Catalog Rebinding

Under most use-cases, a PNP is passed into QTI 3 Stimulus Player as part of the configuration (see 4b Constructing a Configuration) as an item's XML is loaded. However, after an item is loaded, an encapsulating application may update PNP settings and then force a catalog rebinding with the updated PNP settings. QTI 3 Stimulus Player implements a bindCatalog API method for this use-case.

// 1) Use the PnpFactory helper class to build an updated PNP.
let pnpFactory = new PnpFactory()
// Example: turn off glossary
pnpFactory.setGlossaryOnScreen(false)
// Example: turn on Spanish keyword translations
pnpFactory.setKeywordTranslationLanguage('es')
// Example: turn on ext:sbac-glossary-illustration
pnpFactory.setExtSbacGlossaryIllustration(true)

// 2) Set QTI 3 Stimulus Player's current PNP to our new PNP constructed in 1) above.
this.qti3StimulusPlayer.setStimulusContextPnp(pnpFactory.getPnp())

// 3) Even with a new Stimulus Context PNP (step 2) above, QTI 3 Stimulus Player
//  will not automatically rebind the PNP + Catalog.  
// Force QTI3 Stimulus Player to bind (rebind) the Catalog.
this.qti3StimulusPlayer.bindCatalog()

QTI 3 Stimulus Player Presentation Attributes

QTI 3 Stimulus Player has several attributes to instrument presentation within an encapsulating application/web page. These attributes are container-class, container-padding-class, and color-class

container-class

Container classes are used to contain and pad content within them. QTI 3 Stimulus Player comes with built-in support for two container classes: qti3-player-container-fluid and qti3-player-container.

• qti3-player-container-fluid DEFAULT

  This container is a width=100%, padding=0 container at all widths.

• qti3-player-container

  This container has responsive breakpoints at screen widths of 1200px, 980px, and 768px.

container-padding-class

Container padding classes are for setting the padding between the QTI 3 Player container and the qti-assessment-item rendered content. QTI 3 Stimulus Player comes with built-in support for six container padding classes.

• qti3-player-container-padding-0 { padding: 0; } DEFAULT
• qti3-player-container-padding-1 { padding: 0.25rem; }
• qti3-player-container-padding-2 { padding: 0.5rem; }
• qti3-player-container-padding-3 { padding: 1rem; }
• qti3-player-container-padding-4 { padding: 1.5rem; }
• qti3-player-container-padding-5 { padding: 3rem; }

color-class

QTI 3 Stimulus Player has built-in support for 14 foreground / background color combinations in accordance with best practices for many forms of color blindness or other visual impairments. In addition to setting a colorClass in a PNP, color settings may also be applied dynamically.

• qti3-player-color-default DEFAULT
• qti3-player-color-defaultreverse (Default - Reverse Polarity)
• qti3-player-color-blackwhite (High Contrast - foreground color: black, background color: white)
• qti3-player-color-whiteblack (High Contrast - foreground color: white, background color: black)
• qti3-player-color-blackrose (foreground color: black, background color: rose)
• qti3-player-color-roseblack (foreground color: rose, background color: black)
• qti3-player-color-dgraymgray (foreground color: dark gray, background color: medium gray)
• qti3-player-color-mgraydgray (foreground color: medium gray, background color: dark gray)
• qti3-player-color-yellowblue (foreground color: yellow, background color: blue)
• qti3-player-color-blueyellow (foreground color: blue, background color: yellow)
• qti3-player-color-blackcyan (foreground color: black, background color: lblue)
• qti3-player-color-cyanblack (foreground color: lblue, background color: black)
• qti3-player-color-blackcream (foreground color: black, background color: lemonchiffon)
• qti3-player-color-creamblack (foreground color: lemonchiffon, background color: black)

Roadmap

The QTI3 Stimulus Player 2023 development roadmap includes the following capabilities:

• [ ] Catalog Support for American Sign Language videos
• [ ] Improved Audio Player
• [ ] Improved Video Player

License

Distributed under the MIT License. See LICENSE for more information.

Built With

The QTI3 Stimulus Player is built with the Vue.js (v2) framework.

• Vue.js

Contact

Paul Grudnitski - [email protected]

Project Link: https://github.com/amp-up-io/qti3-stimulus-player

Acknowledgments

This component would not be possible were it not for a fortuitous decision by the aQTI Task Force (the original name of the QTI 3 Working Group) - meeting at CITO headquarters in Arnhem, NE, January 2015 - to make the aQTI / QTI 3 specification "web component friendly".