sv-preview

v0.1.2

Published

a year ago

SV Preview. Official release coming soon...

Downloads

0High
0Medium
0Low

jonwhite

Storiiies Viewer

Storiiies Viewer is an open source viewer for Storiiies, the IIIF digital storytelling platform.

Usage

API documentation

Adding the dependencies

There are two options for adding StoriiiesViewer to your project:

In the browser

(This is the quickest and easiest way to get started)

You can include the JavaScript and CSS in the HTML like so, using the unpkg CDN:

<head>
  <!-- ... -->
  <link rel="stylesheet" href="https://unpkg.com/browse/@cogapp/storiiiesviewer@latest/dist/storiiies-viewer.css">
  <script src="https://unpkg.com/browse/@cogapp/storiiiesviewer@latest/dist/umd/storiiies-viewer.js"></script>
  <!-- ... -->
</head>

Or you could save these files and serve them locally if you prefer.

Including the JavaScript file this way will make StoriiiesViewer available globally in JavaScript.

Using a bundler

Install the dependecy with npm install @cogapp/storiiiesviewer
Use import StoriiiesViewer from '@cogapp/storiiiesviewer' in your code to access the StoriiiesViewer constructor
Depending on how your tooling handles importing CSS you might also be able to import the CSS file with import @cogapp/storiiiesviewer/dist/storiiies-viewer.css — but you could also use the method above, or copy the contents of the CSS file into your own src files.

Initialise a viewer

In your HTML:

<div id="storiiies-viewer"></div>

In your JavaScript

document.addEventListener('DOMContentLoaded', () => {
  const myViewer = new StoriiiesViewer({
    container: "#storiiies-viewer", // or document.querySelector("#storiiies-viewer")
    manifestUrl: "https://path-to-your-storiiies-manifest",
  });
});

Customisation

To customise of appearance of StoriiiesViewer you have a few options:

If you'd prefer to bring all your own styles, StoriiiesViewer can be styled from scratch without needing to include the default stylesheet
To 'theme' StoriiiesViewer, you may find the custom properties provided by the default stylesheet to be sufficient
Start with default stylesheet and expand or override these styles as you see fit

Supported manifest formats

StoriiiesViewer supports a subset of the IIIF presentation API v3. Specifically, we target annotationPages which are included directly in the manifest (like in this cookbook recipe).

Annotations themselves can either be text/plain or text/html denoted by the format field. For text/plain newline characters will be converted and output as <br> tags.

StoriiiesViewer has no required fields (aside from those required by the presentation API), but it will render certain values from the manifest if provided. These are:

A manifest label, which is required by the presentation API and will be shown on a "title slide", before any annotations
A manifest level summary, which will appear below the label if provided
A manifest level requiredStatement, which will appear below the summary if provided

[!NOTE] Certain features which aren't currently supported include:
Externally referenced annotationPages (as shown in this cookbook recipe)
Multiple images
Non-text based annotations (e.g. audio)
Full multi-lingual support
However, pathways exist to enable these features with further development.

[!WARNING] Manifest with a version lower than 3 may load images, but aren't guaranteed to work beyond this, and will display a warning in the console.

Local development

Installation

Pre-requisites

Node.js / npm

[!IMPORTANT] Although optional, we recommend using nvm to match the version of Node used in this project before running the install command, or the npm scripts described below.
If you encounter problems and aren't using the version of Node shown in the .nvmrc file, you should try aligning your node version to this first. This represents a known compatibility with the code here and our dependencies.

Setup

Install the dependencies in the project root with:

npm ci

Compiling and previewing changes

Running the tests

[!NOTE] npm run cypress:gui and npm run cypress will also do the same as the above without starting the dev server, if you already have it running.