Skip to content

Latest commit

 

History

History
184 lines (121 loc) · 6.98 KB

README.md

File metadata and controls

184 lines (121 loc) · 6.98 KB
Raw

@samvera/ramp

Netlify Status CircleCI

A ReactJS component library of interactive components created to display audio/video resources in IIIF Presentation 3.0 manifests. These components are designed and built with reusability, customizability, and accessibility in mind.

This is the renamed NPM component library previously known as @samvera/iiif-react-media-player

Documentation

For full documentation of the component library, visit GitHub Wiki

Demo site built show-casing all the components at https://ramp.avalonmediasystem.org/

Installation Guide:

Prerequisites

Please ensure you have the following installed:

  • Node.js (>= 16.x)
  • react and react-dom (>= 17.x)
  • NPM or Yarn

Only the latest version, i.e. v3.3.0, of @samvera/ramp includes support for React 18. For prior @samvera/ramp versions, please use React 17.

Important: v3.3.0 can still be used with React 17. However, if you choose to upgrade to React 18; react and react-dom both need to be updated simultaneously to the same version.

To upgrade ReactJS in your application, please follow the instruction on the ReactJS' official upgrade guide.

Steps

  1. Add @samvera/ramp components library from NPM into your application"
// Using yarn
yarn add @samvera/ramp

// Using NPM
npm install @samvera/ramp
  1. Add peer dependency for Video.js library:
// Using yarn
yarn add [email protected]

// Using NPM
npm install [email protected]

Important: @samvera/ramp <= v3.1.2 needs [email protected], because the included version of @silvermine/videojs-quality-selector is incompatible with video.js >= v8.0.0.

  1. Import the library and Video.js into your application:
import { IIIFPlayer, MediaPlayer, StructuredNavigation, Transcript } from "@samvera/ramp";
import 'video.js/dist/video-js.css';

// Import starter styles 
import "@samvera/ramp/dist/ramp.css";
  1. Example use of the components from the component library:
const App = () => {
  // Get your manifest from somewhere
  const manifestUrl = "https://some-manifest-url-here.json";

  // Transcript props
  const props = {
    playerID: 'player-id',
    transcripts: [
      {
        canvasId: 0,
        items: [ { title: "Title", url: "https://some-transcript-url-here.json" } ]
      }
    ]
  }

  return (
    <IIIFPlayer manifestUrl={manifestUrl}>
      <MediaPlayer enableFileDownload={false} />
      <StructuredNavigation />
      <Transcript {...props} />
    </IIIFPlayer>
  );
}

export default App;

Development

Ramp provides two development environments,

Both of these can run on your localhost at the same time, and can live-reload based on your code changes.

Styleguidist environment

React Styleguidist, in addition to providing documentation, also offers an isolated development environment. To start the dev environment, run:

yarn dev

To build a static html version of the docs (which Github pages uses), run:

yarn styleguide:build

This will create a set of static documentation HTML files in the project's /docs directory. In this documentation, each component is explained with a code sample and a description of its props and functionality.

Webpack environment

An example usage of all the components in the library is served from the /demo directory. This showcases the real-time usage of the components in an application. To start this example, run:

yarn demo

Testing

Ramp uses Jest and react-testing-library to build an automated unit test suite. To run these tests, with a full coverage report, run:

yarn test

To run tests in watch mode:

yarn test:watch

Deployment

When new code is added into the main branch of the GitHub repo, it is deployed into two locations.

Deploying to Netlify demo site

The demo site is hosted with Netlify, which displays all the components in the library in a similar manner to real-life usage of them.

This demo instance can read a publicly available IIIF Presentation 3.0 Manifest given the URL of the manifest and display content in the manifest.

A new build is triggered and published in Netlify when code changes are merged to main branch in this repository.

Deploying to GitHub Pages

The GitHub pages site, https://samvera-labs.github.io/ramp/ is built using ReactJS Styleguidist docs.

Similar to the demo site, a new build of this site it triggered and published when new code changes are merged to main branch.

Contributing

If you're working on PR for this project, create a feature branch off of main.

We welcome your contributions. This repository follows the Samvera Community Code of Conduct and language recommendations.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Contributors

See also the list of contributors to see others who participated in this project.

License

The library is available as open source under the terms of the Apache 2.0 License.

Acknowledgments