The API and Plugins

Contents Plugins The download plugin The manipulation plugin The metadata plugin Disabling a plugin Tutorial: Writing your own plugin The Constructor The Methods The Setup

Diva.js has a modular plugin system that allows developers to easily add page (and now instance) level functionality. There are three included plugins that are enabled by default: the download plugin, the manipulation plugin, and the metadata plugin. This wiki page contains documentation on configuring or disabling the existing plugins as well as a tutorial on how to create a new plugin.

Starting from Diva version 6, plugins are enabled in the following way in the index.html file:
First, start by declaring the path

<script src="build/plugins/download.js"></script>
<script src="build/plugins/manipulation.js"></script>
<script src="build/plugins/metadata.js"></script>

Then, add each plugin when instantiating Diva

<script>
    document.addEventListener('DOMContentLoaded', function ()
    {
        let diva = new Diva('diva-wrapper', {
            objectData: "manifest.json",
            plugins: [Diva.DownloadPlugin, Diva.ManipulationPlugin, Diva.MetadataPlugin]
        });
    }, false)
</script>

Plugins

The download plugin

This plugin allows users to download the image for a page, in JPEG format, at the current resolution. The most basic version results in a new tab or window opened containing the image rather than the image actually being downloaded, due to limitations in client-side scripts. It is, however, possible to route it through another service, for instance a PHP script, which can send the Content-disposition header. This header tells the browser to download the file rather than displaying it, i.e. Content-Disposition: attachment; filename="<image.jpg>.

The Javascript part of the plugin does not need any configuration.

The manipulation plugin

This plugin allows users to adjust the settings for a page by applying and altering varying image filters, such as brightness and contrast, in a popup pane.

The metadata plugin

This plugin allows users to see the metadata of a IIIF manifest, by displaying it in a modal on top of the viewer. The modal can be dragged around to prevent it from obstructing the viewer while being open.

Disabling a plugin

To temporarily disable a plugin for testing or because you have no need of that functionality for a particular instance of Diva, simply exclude it from the list of plugins under the plugins setting when instantiating Diva.

Tutorial: Writing your own plugin

As of Diva 6, a plugin can either be instantiated as a page tool or as a toolbar tool. Determine which of these two your plugin would fit best as - does it integrate with each individual page, or rather with the entire Diva instance?

Plugins should be created as ES6 classes.

Constructor

Plugin constructors should take one argument called core, which is an instance of a ViewerCore object.

Page tool plugins must have an attribute called pageToolsIcon, while toolbar icons must have an attribute called toolbarIcon. These will define the icon that is displayed by the viewer, and should be set to the return value of the createIcon() method (see below). Additionally, toolbar plugins must have the toolbarSide attribute, a string which can be either 'left' or 'right'. This indicates which side of the toolbar the plugin will be rendered at.

constructor (core) {
    this.core = core;

    // page tool
    this.pageToolsIcon = this.createIcon();

    // toolbar tool
    this.toolbarIcon = this.createIcon();
    this.toolbarSide = 'right';
}

Methods

Plugins should have a minimum of two methods, the handleClick() method and the createIcon() method.

handleClick(event, settings, publicInstance, pageIndex) - Page Tool Plugin

This method will determine the behaviour of the plugin when the plugin icon is clicked. It takes in as arguments:

• event: The click event
• settings: The ViewerCore settings
  • eg. settings.objectData, settings.inGrid
• publicInstance: The Diva instance
• pageIndex: The page index at which this plugin was called

Here is an example from the Download plugin:

handleClick (event, settings, publicInstance, pageIndex)
    {
        let width = publicInstance.getPageDimensions(pageIndex).width;
        let url = publicInstance.getPageImageURL(pageIndex, { width: width });
        window.open(url);
    }

handleClick() - Toolbar Plugin

For toolbar plugins, the handleClick() method should take in no arguments. It is sufficient to interact with the this.core attribute.

createIcon()

This method creates the div that represents the icon, and should be implemented using SVG. It must return the div, and should be assigned to either pageToolsIcon or toolbarIcon (as shown in the constructor above).

Here is an example from the Download plugin:

createIcon ()
    {
        /*
        * See img/download.svg for the standalone source code for this.
        * */

        const pageToolsIcon = document.createElement('div');
        pageToolsIcon.classList.add('diva-download-icon');

        let root = document.createElementNS("http://www.w3.org/2000/svg", "svg");
        root.setAttribute("x", "0px");
        root.setAttribute("y", "0px");
        root.setAttribute("viewBox", "0 0 25 25");
        root.id = `${this.core.settings.selector}download-icon`;

        let g = document.createElementNS("http://www.w3.org/2000/svg", "g");
        g.id = `${this.core.settings.selector}download-icon-glyph`;
        g.setAttribute("transform", "matrix(1, 0, 0, 1, -11.5, -11.5)");
        g.setAttribute("class", "diva-pagetool-icon");

        let path = document.createElementNS("http://www.w3.org/2000/svg", "path");
        path.setAttribute("d", "M36.25,24c0,6.755-5.495,12.25-12.25,12.25S11.75,30.755,11.75,24S17.245,11.75,24,11.75S36.25,17.245,36.25,24z M33,24c0-4.963-4.037-9-9-9s-9,4.037-9,9s4.037,9,9,9S33,28.963,33,24z M29.823,23.414l-5.647,7.428c-0.118,0.152-0.311,0.117-0.428-0.035L18.1,23.433C17.982,23.28,18.043,23,18.235,23H21v-4.469c0-0.275,0.225-0.5,0.5-0.5h5c0.275,0,0.5,0.225,0.5,0.5V23h2.688C29.879,23,29.941,23.263,29.823,23.414z");

        g.appendChild(path);
        root.appendChild(g);

        pageToolsIcon.appendChild(root);

        return pageToolsIcon;
    }

Setup

The following must be added at the end of every plugin (outside the class).

export default class MyPlugin 
{
    // constructor
    // methods
}

MyPlugin.prototype.pluginName = "name of my plugin";
MyPlugin.prototype.isPageTool = true || false; // set to false if this is a toolbar plugin

/**
 * Make this plugin available in the global context
 * as part of the 'Diva' namespace.
 **/
(function (global)
{
    global.Diva.MyPlugin = MyPlugin;
})(window);

Instantiating

The plugin can now be instantiated by including it as a Diva plugin:

<script>
    document.addEventListener('DOMContentLoaded', function ()
    {
        let diva = new Diva('diva-wrapper', {
            objectData: "manifest.json",
            plugins: [Diva.MyPlugin]
        });
    }, false)
</script>

That's it!

Depending on what type of plugin your tool is, you will now see the icon either on top of every page or in the toolbar, and clicking it will trigger the handleClick() method, which will be where the functionality of your plugin takes place.

For a full example of a page tool plugin, see the Download Plugin. For a toolbar plugin, see the Metadata Plugin.