V3 - UniversalViewer/universalviewer GitHub Wiki

Deploying

Here is an example project to help you understand how to set up the UV: https://github.com/UniversalViewer/uv-hello-world

You can see a few dependencies being included:

  • uv/uv.css is just some simple styles for the div containing your UV instance to give it a black background with a "spinner".

  • uv/lib/offline.js is all of these dependencies concatenated (jQuery, CoreJS, and JSViews) You could use a CDN for these instead if you prefer. It's called 'offline' because it allows the UV to work using protocols like IPFS where you're loading everything over a different network to the web.

  • uv/helpers.js wraps up some boilerplate code for managing resizing, full screen, and UV event listeners/handlers.

  • uv/uv.js is the compiled UV code, in debug or distribution context depending on if grunt build or grunt build --dist were used respectively. Include this script at the bottom of your page to avoid problems around the uvLoaded event being fired too early.

All of these scripts are copied into your examples/uv folder on build.

Config

The UV's visual config editor has not been ported for v3 yet.

  • root: string

    The path to the uv directory. Use a relative path e.g. root: '../../uv'Don't start your path with a / otherwise requirejs will not append .js to dependencies and they won't load.

  • configUri: string

    The relative path to your config json

Supported content types

The UV looks at the first content annotation on the specified canvas index (using url hash params or defaulting to 0). First it checks the annotation body's format (mime type), then if none is supplied looks at the annotation's type.

Here are the supported formats: https://github.com/IIIF-Commons/vocabulary/blob/master/src/index.ts#L58

and types: https://github.com/IIIF-Commons/vocabulary/blob/master/src/index.ts#L35

(the types are being normalised as lowercase).

A type of canvas or image for example will load the OpenSeadragon extension.

Metrics

The UV has css media queries that respond to the width of the containing page. These are partitioned into four separate "metrics" which are defined both in css and js, so that they can be queried programmatically at runtime:

https://github.com/UniversalViewer/universalviewer/blob/master/src/modules/uv-shared-module/css/variables.less#L7 https://github.com/UniversalViewer/universalviewer/blob/master/src/extensions/uv-seadragon-extension/config/en-GB.json#L12

Extension development

UV extensions can be found in src/extensions.

Each extension deals with a given content type and is registered in UVComponent.ts https://github.com/UniversalViewer/universalviewer/blob/master/src/UVComponent.ts#L36

Extensions each require a specific set of dependencies. For example, here is the dependencies file for the OpenSeadragon extension: https://github.com/UniversalViewer/universalviewer/blob/master/src/extensions/uv-seadragon-extension/dependencies.ts

Dependencies are split into sync and async arrays. sync dependencies will load one at a time in the order specified. async will all load at the same time.

Using a ! before a dependency path forces requirejs to use that exact path, not prepend the base url e.g. uv/lib. This is useful when a requirejs config path is specified, e.g. https://github.com/UniversalViewer/universalviewer/blob/master/src/extensions/uv-pdf-extension/Extension.ts#L33 https://github.com/UniversalViewer/universalviewer/blob/master/src/extensions/uv-pdf-extension/dependencies.ts#L5

The file extension of each annotated media file on a given canvas is passed when loading dependencies. See https://github.com/UniversalViewer/universalviewer/blob/master/src/extensions/uv-av-extension/dependencies.ts#L51 for an example of returning different dependencies depending on whether dash, hls, etc are available.

Each extension has a config.js that defines a set of Grunt copy tasks in order to retrieve the dependencies from their respective node_modules source and copy to that extension's lib folder.

Each extension's lib folder is copied on build to the uv/lib folder. This is where the dependencies.ts paths are specified relative to.

This is where the node_modules source files are synced to each extension's lib folder: https://github.com/UniversalViewer/universalviewer/blob/master/Gruntfile.js#L212

This is where the extension/lib files are copied to the .build folder: https://github.com/UniversalViewer/universalviewer/blob/master/Gruntfile.js#L155

Distribution

Ensure you have git tagging on version disabled:

npm config set git-tag-version=false

In universalviewer

grunt build --dist
npm version major/minor/patch

(info.json is created in /dist and /examples/uv with the new version number) This only works on Windows at present. But you can change the npm script to use $npm_package_version instead of %npm_package_version%

cd examples

git add -A
git commit -m "build"
git push origin gh-pages

cd ..

git add -A
git commit -m "fixes #..."
git push origin master
npm publish --tag beta

Gotchas

UV not appearing in IE

If you have another file called uv.js it can result in this bug: https://github.com/requirejs/requirejs/issues/518