Skip to content

Development notes

Jump to bottom Edit New page
Eric Han Liu edited this page Aug 9, 2018 · 38 revisions

This page contains information and notes on how some of the internal functions of Diva work. If you wish to get started with developing Diva, read on.

Table of Contents

Tools

Diva 5.0 brings with it Webpack which is used to generate an AMD and CommonJS compatible object, as well as making the 'Diva' object accessible as a global variable.

As of Diva 6, we are no longer using gulp as our build system. See Installation#building-from-source for the commands available for common development tasks, which run with npm scripts and Webpack.

Debugging setup

We've included source maps so that when the compiled Javascript and CSS are loaded into a browser with debugging capabilities, the original source is displayed in the elements panel and console.

Container IDs

In order to allow more than one document viewer on a single page, we generate different prefixes for the IDs of the elements of each document viewer instance. The first document viewer instantiated on the page will have an ID prefix of diva-1, the second diva-2, and so on.

To target all instances of a specific type of element using CSS, you can target elements using their classes. For example, to make the text within all title elements grey, you could do something like this:

.diva-title {
    color: #CCC;
}

Data received through AJAX request

The following data is returned through each AJAX request for the objectData IIIF manifest:

  • item_title: The title of the document, as given by the label key.

  • dims: An array holding information related to the dimensions of the document. Contains the following information: * a_hei: The average height of all the images. This is used for calculating the vertical padding if [[settings.adaptivePadding|Settings#adaptivepadding]] is enabled. * a_wid: The average width of all the images. This is used for calculating the horizontal padding if [[settings.adaptivePadding|Settings#adaptivepadding]] is enabled. * mx_h: The maximum height among all the images. Not actually used at the moment. * mx_w: The maximum width among all the images. Necessary for calculating left offsets for each page (i.e. left and right padding). * t_hei: The total height of all the images stacked together, vertically. Necessary for calculating the total height of the containing element. * t_wid: The total width of all the images stacked together, horizontally.

  • max_zoom: the lowest maximum zoom level among all the pages of the document. The usage of this variable is explained in the section below

  • pgs: An array holding the data for all the pages in the document. See the explanation for the pages array in the Settings documentation for more information.

The contents of the pgs array should be sorted according on their filename prior to the request, and returned in a sorted order, so that the user doesn't have to wait for it to be dynamically sorted.

Virtual rendering

The first versions of diva.js worked like this: all the pages were loaded initially, but as blank images, and were only replaced with the actual tiles once they entered the viewport. However, not only did this result in an initial load time of several seconds, it also made scrolling fairly slow, especially once a large portion of the document had been loaded in the browser's memory. In the search for alternatives, I came across SlickGrid, whose implementation of virtual rendering resulted in an extremely fast way to page through large datasets, and managed to implement a similar technique in diva.js, whereby pages that were scrolled out of the viewport are deleted from the DOM, and pages that should be visible in the viewport are appended to it. This considerably speeded up initial load time and scrolling speed, and resulted in improved memory handling within the browser. Although the use of this technique should not affect ordinary installation and usage, the knowledge that it is being used might be important should it be necessary to make any edits to the appending/deleting functions. See Private Functions for more.

As of Diva 5.0, image tiles are requested once they enter the viewport and are rendered on a canvas. Those images are cached, and can thus be reloaded from memory instead of creating a new server request to re-acquire them.

loadRow image sizing

When requesting images for grid mode within loadRow, images are requested at a particular height, and the full image is always returned, instead of disparate tiles (as in loadPage). However, the height of the images returned by IIPImage is often one or two pixels less than the requested height. This results in an unseemly white border along the bottom and right edges. To counter this, the requested height is 2 pixels greater than it should be, which should result in an image that may be cut off vertically by a few pixels but which will not be too short to fill the container. This appears to be an issue with IIPImage and the way image dimensions are calculated, so this workaround will have to do for now.

The above does not apply to versions of Diva >= 5.0.0, since there is no more loadRow and both the height and width of images tiles are specified in the requests.

Panel size changes

As noted in #235, the adjustBrowserDims/updatePanelSize function can not be called dynamically when an element is resized, as jQuery doesn't support that without creating a custom setTimeout and seeing if the size of the element has changed. Our workaround for this, as of f21c0c7, is to create a Diva event called PanelSizeDidChange that will serve as an automatic call to the private adjustBrowserDims/updatePanelSize function. This will force the panel size to update so that all internal functions relying on it will respond with correct values; external code can be hooked off this event as well.

Add a custom footer
Clone this wiki locally