Quinoa-presentation-player - data presentations player component

Quinoa-presentation-player is a module that provides a react component for displaying quinoa's data presentations in read-only mode.

It is part of the quinoa project family, a suite of digital storytelling tools tailored for the FORCCAST pedagogical program and médialab sciences po scientific activities.

An example of editing apps for making data presentations is bulgur.

Requirements

• git
• node

npm scripts

npm run build # builds component to ./build dir
npm run lint # lints code (auto fix on) according to linting settings in package.json
npm run comb # prettifies scss code
npm run test # run mocha testing on each *.spec.js files in ./src dir
npm run storybook # starts a storybook instance to live test the component in several implementation scenarii (see ./stories folder)
npm run build-storybook # initializes storybook
npm run git-add-build # adds build to the current git record

Installing the module as a dependency

npm install --save https://github.com/medialab/quinoa-presentation-player

Installing the module as a project

git clone https://github.com/medialab/quinoa-presentation-player
cd quinoa-presentation-player
npm install
npm run build-storybook

Development

The project uses storybook to visually test the possible implementations of the component.

npm run storybook

Module API

The module exports by default a react component. It also exports a templates object which exposes metadata about available templates to display presentations.

import PresentationPlayer from 'quinoa-presentation-player'; // provides usable react component

import {templates} from 'quinoa-presentation-player'; // provide metadata about available templates

Presentation component API

QuinoaPresentationPlayer.propTypes = {
  /**
   * component must be given a presentation as prop
   * (see ./src/presentationModel.json and ./quinoa-presentation-document-model-description.md)
   */
  presentation: PropTypes.object.isRequired,
  /**
   * Component global options
   */
  options: PropTypes.shape({
    /**
     * declares whether users can pan/zoom/navigate inside the view
     * or if the view is strictly controlled by current slide's parameters
     */
    allowViewExploration: PropTypes.bool
  }),
  /**
   * callback when navigation is changed
   */
  onSlideChange: PropTypes.func,
  /**
   * callback when user triggers an exit event on the component 
   * (e.g. for scroller template : scroll down on last slide, scroll up on first slide)
   */
  onExit: PropTypes.func,
  /**
   * callback transmitting wheel events upstream
   */
  onWheel: PropTypes.func,
};

Templating

The component wraps a display-related component which corresponds to a specific templates.

Current templates are :

• stepper : slides are displayed on a pannel on the left of the view, navigation is handled through buttons
• scroller : slides are displayed as blocks, navigation is handled through scrolling

Creating new templates

Creating a new template supposes to create a new folder within src/templates/ folder, and fill it with at least three files:

• an info.json file describing the metadata of the template
• a scss file describing component default style
• a js script exposing a react component

Example of an info.json:

{
  "id": "scroller",
  "name": "Scroller",
  "description": "Slides are browsed through scrolling on the presentation"
}

The react component of the template must comply to the following API :

MyTemplate.propTypes = {
  /**
   * The presentation to display
   */
  presentation: PropTypes.object.isRequired,
  /**
   * The current slide being displayed by the component
   */
  currentSlide: PropTypes.object,
  /**
   * Parameters describing current view's state
   */
  activeViewsParameters: PropTypes.object,
  /**
   * Whether the current view parameters match with current slide's view parameters
   */
  viewDifferentFromSlide: PropTypes.bool,
  /**
   * The transformed datasets to use for displaying visualizations
   */
  datasets: PropTypes.object,
  /**
   * Navigation state description
   */
  navigation: PropTypes.shape({
    /**
     * What is the active slide's id
     */
    currentSlideId: PropTypes.string,
    /**
     * What is the active slide's rank in slides list
     */
    position: PropTypes.number,
    /**
     * Whether active slide is the first
     */
    firstSlide: PropTypes.bool,
    /**
     * Whether active slide is the last
     */
    lastSlide: PropTypes.bool
        
  }),
  /**
   * Callbacks when user asks to jump to a specific slide
   */
  setCurrentSlide: PropTypes.func,
  /**
   * Callbacks when user asks to step forward or backward in slides order
   */
  stepSlide: PropTypes.func,
  /**
   * Callbacks to change the display of presentation's metadata/details in aside
   */
  toggleAside: PropTypes.func,
  /**
   * Interface state description
   */
  gui: PropTypes.shape({
    /**
     * Whether aside displays list of slides or presentation's metadata/details
     */
    asideVisible: PropType.bool,
    /**
     * Whether user is allowed to explore the view or can just navigate into slides' views
     */
    interactionMode: PropType.oneOf(["read", "explore"])
  }),
  /**
   * Component global options
   */
  options: PropTypes.shape({
    /**
     * declares whether users can pan/zoom/navigate inside the view
     * or if the view is strictly controlled by current slide's parameters
     */
    allowViewExploration: PropTypes.bool
  }),
  /**
   * Callbacks when user tries to reset view to current slide's view parameters
   */
  resetView: PropTypes.func,
  /**
   * Callbacks when user changes view manually
   */
  onUserViewChange: PropTypes.func,
  /**
   * Hook to switch between "read" and "explore" interaction modes
   */
  toggleInteractionMode: PropTypes.func,
  /**
   * Trigger to call when user interacts to exit the presentation
   */
  onExit: PropTypes.func
}

Pre-commit hook

The project uses a precommit hook before each commit to ensure the code remains clean at all times. Check out the package.json to learn more about it.