Skip to content

Installation

Jump to bottom Edit New page
Eric Han Liu edited this page Aug 10, 2018 · 101 revisions
Contents
  1. Setting up IIIF
  2. Configuring the Diva.js viewer
    1. The HTML File
    2. The CSS
  3. Building From Source

Here you'll find instructions on how to install and set up the Diva.js document viewer and image server software on your own server. Diva can then be easily integrated into an existing website.

This guide assumes that you already have a website set up, and that the images you want to display can be stored on any IIIF-compatible image server (see a list of IIIF-compatible Image Servers). It is also possible to use Diva without installing your own image server if the images you want to view are accessible through an existing IIIF repository.

Setting up IIIF

In order to use your own images with IIIF and Diva, you'll need two components:

  1. a IIIF-compatible image server
  2. a IIIF Manifest (if you are using an external IIIF repository, simply skip to Configuring the Diva.js Viewer).
  • If you are using a IIIF-compatible image server, follow its setup instructions to get your images displaying. See this page for a list of recommended servers.

Configuring the Diva.js viewer

First, download the release package or install using npm (npm install diva.js).

Or, you may skip downloading and include diva.js and diva.css from CDNJS, replacing the local paths in the example configuration below with the paths on CDNJS.

The HTML file

Create an HTML file that will contain the document viewer. For an example, see index.html. Only the objectData setting is required, and should point to your IIIF manifest JSON file.

<head>
    <link rel="stylesheet" href="/build/diva.css" />
    <script src="/build/js/diva.js" type="text/javascript"></script>
    <script>
    document.addEventListener('DOMContentLoaded', function ()
        {
            let diva = new Diva('diva-wrapper', {
                objectData: "http://example.com/manifest.json"
            });
        }, false)
    </script>
</head>

With IIIF (with your own images or an existing external repository), you're only required to set objectData to the URL of the Manifest.

The body element should contain a block-level element, generally a div, with the ID specified above (diva-wrapper in this case, although any unique ID is valid, as long as the same one is used within the script tags above). For instance:

<body>
    <div id="diva-wrapper"></div>
</body>

The JavaScript

If you wish to include the Diva viewer component into your own JavaScript app, this can be done easily by just importing Diva beforehand.

import Diva from './path/to/source/diva.js';

let diva = new Diva('diva-wrapper', {
    objectData: "http://example.com/manifest.json"
    // possible settings
});

There are a large number of settings that can be enabled/disabled for any Diva instance. See Settings for a comprehensive list.

If you load up the HTML document, you should see Diva loaded with your images! If not, try opening your browser's Javascript console to display any errors.

At this point, you have completed the basic installation process. If you're having trouble, open an issue. To see the other options that can be set in the script tag, see the Settings page and the wiki sidebar. Such options include adjusting formatting, adding custom actions to hook into viewer events, changing the location of the toolbar to fit within your existing website or application, and more.

It is not recommended to use a DOCTYPE of strict for your HTML document, as that causes problems with support for Apple touch devices.

The CSS

If you wish to style the document viewer you can hand-edit the /build/diva.css file and include it in your <head>. If, however, you wish to perform more extensive modifications, it may be easier to instead edit the source /source/css/diva.scss (and linked files) and re-compile the CSS. More information on this is available in the section on development for Diva.

Building From Source

If you wish to install from source, you can check out the code from our GitHub repository or use npm (npm install diva.js).

If you retrieved the code from our GitHub repository and already have node.js and npm installed, run npm install to fetch all dependencies. You can now run the following development tasks from the command-line:

npm run develop          // Runs a server at localhost:9001 and automatically builds and reloads upon changes
npm run build:develop    // Compiles the Javascript and SASS source and places it in the build/ directory
npm run lint             // Lints the Javascript source with JSHint
npm test                 // Runs the unit tests and outputs a report to the console
npm run build:production // Builds the release package

The full installation gives you access to the un-minified JavaScript source, the plugins, the documentation, and our unit-tests. See the Code Documentation section of the wiki sidebar for more information about developing Diva.

Add a custom footer
Clone this wiki locally