Developing Diva.js

Developing Diva.js

This brief guide is meant as a supplement to the official user documentation. The user documentation covers general usage, as well as non-core changes such as writing plugins or integrating Diva within the context of a web application (with Events).

Code structure

The main source file is located at source/js/diva.js. Utility libraries are located in utils.js and plugin source files in plugins.

The main source file

In source/js/diva.js, at the top of the source code, there are a number of settings and globals used for both configuration and for maintaining application state.

Some functions of interest:

Initialization - init() -> setupViewer() -> loadObjectData() -> loadViewer() -> loadDocument()

User input event listeners - handleEvents()

Scrolling callback - scrollFunction() -> adjustPages()

Zooming callback - handleDocumentDoubleClick() -> handleZoom() -> loadDocument()

Page loading/rendering - loadPage() -> loadPageTiles() -> loadTiles()

See the Code Documentation portion of the wiki sidebar for more details about all functions and settings.

Using the Diva object

Diva makes itself available via the data attribute of a DOM node, so you can fetch the instance from the DOM node it's attached to and interact with it. Try running the following in the browser console on one of the demos and interacting with the exposed methods.

var divaInstance = $('#diva-wrapper').data('diva');
var settings = dv.getSettings();

Events system

Diva uses an events system to transmit application state. See the events system documentation.

Recent features

IIIF support

Basic support for the IIIF Presentation API 2.0 has been implemented in parseObjectData(). The parsing will probably need to be made more robust to handle all IIIF Manifests thrown at it.

Smooth Zooming

Previously, zooming in on Diva resulted in clearing the viewer and reloading the images at a larger size. Smooth zooming was recently implemented, so that zooming results in the pages animating to their new size. This was implemented using CSS Transitions to animate transform:scale of diva-inner, the element inside the viewer pane which contains all the page elements.

A quick overview of what happens when the user zooms:

• User interaction (zoom buttons, touch gesture, or double-click)
• handleZoom is called
• Visible canvases are saved in settings.previousZoomLevelCanvases[]
• preloadPages() is called, which grabs the canvases from settings.previousZoomLevelCanvases and starts loading/drawing new images onto them
• loadDocument() is called, and the canvases from preloadPages() are placed into the DOM

Internal details

Releasing a new version

[ ] Run gulp release -v 5.0.0 to update the version in package.json and zip up the release package [ ] Create a new release/tag on Github (the version on CDNjs should be updated automatically), upload release packages to the release page [ ] Update the website (see Website maintenance) [ ] Update the npm package (https://docs.npmjs.com/getting-started/publishing-npm-packages)

Website maintenance

Generally, when a new version is released, the following must be modified to update the website on the gh-pages branch (shown by Github Pages on http://ddmal.github.io/diva.js/):

• Swap in the built files into /try/ (replace js, css, demo directories with those from the new release)
• Update the page in /download/ (find/replace all occurrences of the version number)

While modifying the website, use jekyll serve -w --baseurl / to run a local server that tracks changes.

The files in /_layouts/ include the <script> tags for some of the demo pages, since this was the quickest way to modify the header. This can (should...) be made more modularized using Jekyll includes.

Always test Diva version upgrades locally before pushing to the website.