Developing Diva.js

This brief guide is meant as a supplement to the main wiki documentation and the other sections under 'Code Documentation'. The main 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 the source/js/utils/ folder and plugin source files in source/js/plugins/. The main object containing the state of the Diva viewer is located in source/js/viewer-core.js.

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.

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

Using the Diva object

To interact with the Diva instance, you'll need to make your diva variable global when initializing in the HTML file. This can be done by removing the let statement, so you have

diva = new Diva('diva-wrapper', {
    objectData: "manifest.json",
    plugins: [Diva.DownloadPlugin, Diva.ManipulationPlugin, Diva.MetadataPlugin]
});

From here, the Diva instance will be stored in the global diva variable. Try interacting with the exposed methods in the browser console on one of the demos.

Events system

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

Recent features

Removal of JQuery

Diva 6 is now free of external dependencies, the biggest removal being JQuery, in favour of vanilla JavaScript.

IIIF version 3 support

Support for the IIIF Presentation API 3.0 has been implemented in Diva 6.

Toolbar plugin hooks

New plugins can now be added as toolbar tools, instead of just page tools. See Writing Your Own Plugin for more information.

New unit testing framework

See below!

Unit tests

Unit tests are located in test/.

We use Karma with karma-chrome-launcher (headless) to load the Mocha test runner. The tests run via the command npm test or karma start.

The tests can also be debugged in the browser by running karma start --single-run=false, and navigating to localhost:9876/debug.html. The tests will run visibly in the browser, and each component will log its output to the browser console.

Note that the tests depend on the build/ directory existing, since it relies on the CSS files' styling for certain test suites. If the directory doesn't exist prior to testing, then to create it just run

npm run build:develop

Internal details

Releasing a new version

1. Create the release package
   • Run npm run build:production to create the compiled source files (under build/), and zip them.
   • Update the Diva version in package.json.
2. Create a new release with tag on Github, upload release packages to the release page
3. Update the website (see Website maintenance)
4. Update the npm package (https://docs.npmjs.com/getting-started/publishing-npm-packages)

The version on CDNjs will be updated automatically based on the git tag, but it will be necessary to change the links in readme.md and in the Installation instructions.

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 configuration in _data/release.json (update the version number and download URLs)

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.