Upgrade Notes - samvera-labs/ramp GitHub Wiki

Upgrading from v2.0.0 to v3.0.0

This upgrade carries a lot of new components and changes to the player and is backward compatible with v2.0.0 while there are some new props added to the existing components to make them more customizable.

This version bump doesn't require any new dependencies to be installed. But v3.0.0 doesn't require to install yarn add videojs-hotkeys as a peer dependency. This functionality is built into the Ramp code from v3.0.0, thus after installing v3.0.0 run;

yarn remove videojs-hotkeys

New components

Changes to existing components

  • IIIFPlayer component:

    Props:

    • 3 new props added to it; they are customErrorMessage, startCanvasId, and startCanvasTime. These are explained in detail in the documentation here.

  • MediaPlayer component:

    Props:

    • One new prop for disabling Picture-In-Picture in the player called enablePIP, this prop has a default value of false.

    ** CHANGED DEFAULT BEHAVIOR: This prop changes the default behavior of v2.0.0, which had Picture-In-Picture enabled by DEFAULT.

  • Transcript component:

    Props:

    • One new prop for providing a manifestUrl, which is the same Manifest url given to IIIFPlayer component. The component will parse the supplementing annotation for each Canvas in the Manifest and generate a transcripts list. More information is available in the documentation.

    Functionality changes:

    • Transcripts component used to always auto-scroll with playback when there are transcripts with time information. In v3.0.0 the auto-scrolling can be turned on/off using the check box in the component. This is only available with transcripts with time information (e.g. WebVTT)
    • Indicates machine generated transcripts in the component. More information can be found in the documentation. Screenshot 2024-02-14 at 4 41 27 PM

  • StructuredNavigation component:

    UI changes:

    • In v3.0.0 the component has a new look and feel. In the new look it indicates each root-level Range explicitly, displays time information, and displays a Scroll to see more message on the bottom of the component when there are long structures.

      Example from the IIIF Cookbook's Table of Content for A/V Content recipe;

      In v2.0.0: In v3.0.0:

Upgrading from 3.0.0 to 3.1.2

This upgrade includes the following changes to the existing components;

  • MetadataDisplay component:

    • Supports Null values for metadata fields

  • MediaPlayer component:

    • Removed Video.js handling of any captions embedded into HLS manifests only supporting captions/subtitles via IIIF Annotations with supplementing motivation (related issue)
    • Minor bug fixes related to Canvas transitions, and styling

  • StructuredNavigation component:

    • Minor bug fixes to improve usability
    • Removed strict filtering when marking structure items with media fragments (related issue)

  • Transcript component:

    New Feature:

    Added support for displaying SRT files with playback synchronization

Upgrading from 3.1.2 to 3.2.0

This upgrade includes a version bump to Video.js from 7.21.3 to 8.10.0, which was waiting on a Video.js upgrade to @silvermine/videojs-quality-selector, a plugin Ramp uses. To install the new Video.js version, run the relevant command based on the package manager used in your application;

yarn add [email protected] OR npm install [email protected]

This upgrade includes the following changes to the existing components;

  • IIIFPlayer component:

    Props:

    • One new prop called emptyManifestMessage to provide a customized message to display when a given IIIF Manifest is empty. More information can be found under the component's documentation

  • MediaPlayer component:

    Props:

    • This component has 3 new props in this version, and they are enablePlaybackRate, enableTitleLink, and withCredentials all of which are optional props. More information can be found under the component's documentation

    Functionality changes:

    • For inaccessible/empty items the player now displays previous/next buttons to navigate through canvases along with a given message. More information can be found under the component's documentation

  • MetadataDisplay component:

    Functionality change:

    • Added support to display both rights and requiredStatement properties under both Manifest and Canvas. They are displayed after the respective metadata block in the same component (related issue)

  • Transcript component:

    New Feature:

    A search within feature for all supported transcript file types was added to the Transcript component. More information can be found under the component's documentation

Upgrading from 3.2.0 to 3.3.0

This upgrade includes a version bump to react and react-dom libraries from 17.0.1 to 18.3.1, and major code refactor to the state management portion of the code. None of these changes break the general functionalities and the user interface of the components.

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

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

This upgrade includes the following changes to the existing component(s);

  • StructuredNavigation component:

    Props:

    • This component has 2 new props in this version, and they are showAllSectionsButton, and sectionsHeading all of which are optional props. More information can be found in the component's documentation

    Functionality and UI changes:

    • Carries a new button for each section in structures to easily collapse and expand the structural content within the section
    • A new button on top of the component to collapse and expand all collapsible structural content within structures, which can be enabled via showAllSectionsButton prop in the component.

Upgrading from 3.3.0 to 4.0.0

Bug fixes

Accessibility fixes

Feature changes

  • MarkersDisplay component:

    • This component has 2 new props in this version, and they are displayMotivations, and showMoreSettings all of which are optional props. More information can be found in the component's documentation
    • Supports the display of annotations with commenting, supplementing, tagging motivations in addition to highlighting annotations. More information in the component's documentation page NEW❗
    • BREAKING CHANGE💥 Renamed the component from MarkersDisplay to Annotations

Upgrading from 4.0.0 to 4.0.1 -> 4.0.2

Feature changes

  • Transcript component:

    • 1 new prop added to turn ON/OFF display of metadata block at the top of a WEBVTT file in the component. More information can be found in the documentation

Bug Fixes

Accessibility Fixes

Upgrading from 4.0.x to 5.0.0

This upgrade includes breaking changes to React version requirements, the build system, and VideoJS dependency management.

Breaking Changes💥

  • React 19 required: This version drops support for React 17 and React 18. Both react and react-dom must be upgraded to ^19.0.0 before installing @samvera/[email protected]. To upgrade ReactJS in your application, please follow the instructions on the ReactJS official upgrade guide (related issue)

  • VideoJS is now bundled: video.js is no longer a peer dependency — it is bundled directly into the library. After upgrading, remove it from your application dependencies:

    yarn remove video.js
npm uninstall video.js

  • Build system migrated to Vite: The library is now built using Vite in library mode (previously Rollup). This makes no difference to consumers as the bundle output filenames remain the same (ramp.esm.js, ramp.cjs.js, ramp.umd.js, ramp.css) (related issue)

New Features

Bug Fixes

Improvements