-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #745 from samvera-labs/update-readme
Update README for 3.3.0 release
- Loading branch information
Showing
1 changed file
with
68 additions
and
42 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,35 +2,64 @@ | |
| [](https://app.netlify.com/sites/iiif-react-media-player/deploys) | ||
| [](https://app.circleci.com/pipelines/github/samvera-labs/ramp) | ||
|
|
||
| ### **Renamed NPM component library previously known as [`@samvera/iiif-react-media-player`](https://www.npmjs.com/package/@samvera/iiif-react-media-player)** | ||
| A ReactJS component library of interactive components created to display audio/video resources in [IIIF Presentation 3.0 manifests](http://iiif.io/api/presentation/3.0/). These components are designed and built with reusability, customizability, and accessibility in mind. | ||
|
|
||
| An NPM component library of interactive [IIIF Presentation 3.0 API](http://iiif.io/api/presentation/3.0/) powered audio/video media player ReactJS components. | ||
| #### **This is the renamed NPM component library previously known as [`@samvera/iiif-react-media-player`](https://www.npmjs.com/package/@samvera/iiif-react-media-player)** | ||
|
|
||
| ### **[Demo](https://ramp.avalonmediasystem.org/) | [GitHub Wiki](https://github.com/samvera-labs/ramp/wiki)** | ||
| ## Documentation | ||
|
|
||
| For full documentation of the component library, visit [GitHub Wiki](https://github.com/samvera-labs/ramp/wiki) | ||
|
|
||
| Demo site built show-casing all the components at https://ramp.avalonmediasystem.org/ | ||
|
|
||
| ## Installation Guide: | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| ## General Usage: | ||
| Please ensure you have the following installed: | ||
| - Node.js (>= 16.x) | ||
| - `react` and `react-dom` (>= 17.x) | ||
| - NPM or Yarn | ||
|
|
||
| Add the `@samvera/ramp` components library from NPM into your ReactJS application via `yarn` or `npm`. | ||
| 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](https://react.dev/blog/2022/03/08/react-18-upgrade-guide#updates-to-client-rendering-apis). | ||
|
|
||
| ### Steps | ||
|
|
||
| 1. Add `@samvera/ramp` components library from NPM into your application" | ||
| ``` | ||
| // Using yarn | ||
| yarn add @samvera/ramp | ||
| // Add peer dependencies | ||
| yarn add [email protected] | ||
| // Using NPM | ||
| npm install @samvera/ramp | ||
| ``` | ||
| 2. Add peer dependency for `Video.js` library: | ||
|
|
||
| **NOTE** (*Ramp <= v3.1.2*): `[email protected]` needs to be used because the included version of `@silvermine/videojs-quality-selector` is incompatible with Video.js >= v8.0.0. | ||
| ``` | ||
| // Using yarn | ||
| yarn add [email protected] | ||
| ### Example usage | ||
| // 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`. | ||
|
|
||
| 3. Import the library and `Video.js` into your application: | ||
| ``` | ||
| import React from 'react'; | ||
| import { IIIFPlayer, MediaPlayer, StructuredNavigation, Transcript } from "@samvera/ramp"; | ||
| import 'video.js/dist/video-js.css'; | ||
| // Import starter styles | ||
| import "@samvera/ramp/dist/ramp.css"; | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| ``` | ||
| const App = () => { | ||
| // Get your manifest from somewhere | ||
| const manifestUrl = "https://some-manifest-url-here.json"; | ||
|
|
@@ -58,16 +87,17 @@ const App = () => { | |
| export default App; | ||
| ``` | ||
|
|
||
| ## Documentation | ||
|
|
||
| See the [Styleguidist docs](https://samvera-labs.github.io/ramp/) for documentation on the components. And the [GitHub Wiki](https://github.com/samvera-labs/ramp/wiki) for more details on usage and implementation of these components. | ||
| ## Development | ||
|
|
||
| Ramp provides two development environments, | ||
| - using [React Styleguidist](https://react-styleguidist.js.org/): a documentation site for all the components and their usage accompanied with code snippets, running on http://localhost:6060. | ||
| - using [Webpack](https://webpack.js.org/): show-case of how these components can be arranged on a web page and styled according to user preference, running on http://localhost:3003. | ||
|
|
||
| ## Developing | ||
| Both of these can run on your localhost at the same time, and can live-reload based on your code changes. | ||
|
|
||
| ### Styleguidist development | ||
| ### Styleguidist environment | ||
|
|
||
| Styleguidist, in addition to providing documentation, also offers an isolated development environment. To start the dev environment, run: | ||
| [React Styleguidist](https://react-styleguidist.js.org/), in addition to providing documentation, also offers an isolated development environment. To start the dev environment, run: | ||
|
|
||
| ``` | ||
| yarn dev | ||
|
|
@@ -79,59 +109,55 @@ 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 `/styleguide` directory. In this documentation, each component is explained with a code sample and a description of its props and functionality. | ||
| 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 | ||
| ``` | ||
|
|
||
| Then open up a browser and navigate to http://localhost:3003. It has live reload enabled via `webpack`, so live updates are immediately rendered in the browser during development. | ||
| ## Testing | ||
|
|
||
| ## Deployment | ||
|
|
||
| To deploy your forked version of this repo, run: | ||
| Ramp uses [`Jest`](https://jestjs.io/) and [`react-testing-library`](https://github.com/testing-library/react-testing-library) to build an automated unit test suite. To run these tests, with a full coverage report, run: | ||
|
|
||
| ``` | ||
| yarn build | ||
| yarn test | ||
| ``` | ||
|
|
||
| This will create CommoneJS, ES Module, and UMD distribution files located in the `/dist/` directory. | ||
|
|
||
| ### Netlify Demo-site Deploy | ||
| To run tests in `watch` mode: | ||
|
|
||
| A [demo site](https://ramp.avalonmediasystem.org/) is hosted with [Netlify](https://www.netlify.com). | ||
| ``` | ||
| yarn test:watch | ||
| ``` | ||
|
|
||
| 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. | ||
| ## Deployment | ||
|
|
||
| A new build is triggered and published in Netlify when code changes are merged to the `main` branch in this repository. | ||
| When new code is added into the `main` branch of the GitHub repo, it is deployed into two locations. | ||
|
|
||
| ## Running the tests | ||
|
|
||
| To run the tests, with a full coverage report, run: | ||
| ### Deploying to Netlify demo site | ||
|
|
||
| ``` | ||
| yarn test | ||
| ``` | ||
| The [demo site](https://ramp.avalonmediasystem.org/) is hosted with [Netlify](https://www.netlify.com), which displays all the components in the library in a similar manner to real-life usage of them. | ||
|
|
||
| To run tests in `watch` mode: | ||
| 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. | ||
|
|
||
| ``` | ||
| yarn test:watch | ||
| ``` | ||
| A new build is triggered and published in Netlify when code changes are merged to `main` branch in this repository. | ||
|
|
||
| Ramp uses [`Jest`](https://jestjs.io/) and [`react-testing-library`](https://github.com/testing-library/react-testing-library) to build its test suite. | ||
| ### Deploying to GitHub Pages | ||
|
|
||
| ### Coding style tests | ||
| The GitHub pages site, https://samvera-labs.github.io/ramp/ is built using ReactJS Styleguidist docs. | ||
|
|
||
| There is a `prettierrc` file with project coding style settings. | ||
| 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. | ||
| If you're working on PR for this project, create a feature branch off of `main`. | ||
|
|
||
| This repository follows the [Samvera Community Code of Conduct](https://samvera.atlassian.net/wiki/spaces/samvera/pages/405212316/Code+of+Conduct) and [language recommendations](https://github.com/samvera/maintenance/blob/main/templates/CONTRIBUTING.md#language). | ||
| We welcome your contributions. This repository follows the [Samvera Community Code of Conduct](https://samvera.atlassian.net/wiki/spaces/samvera/pages/405212316/Code+of+Conduct) and [language recommendations](https://github.com/samvera/maintenance/blob/main/templates/CONTRIBUTING.md#language). | ||
|
|
||
| ## Versioning | ||
|
|
||
|
|
||