Notes on developing more robust Mirador support in Drupal and Islandora

The following is a work in progress that represents my learning and documenting how to integrate Mirador with Islandora in a way that supports:

• Custom builds or a remote app
• Enabling and configuring Mirador plugins

I wil be creating issues in this project or other appropriate issue queues to represent tasks to accomplish this.

---

Using Mirador in Drupal with plugins support

Adapted from mirador-integratio-omeka and the fork at https://github.com/digitalutsc/mirador-integration-omeka by the Digital Text unit of University of Toronto Scarborough.

Why not fork?

I'd like to have a way to keep up with releases of Mirador. As of version 2.x of Islandora, the Mirador module links to a CDN that serves a release candidate of Mirador 3.0.0 which is a few years old now.

Also I'd like to support Islandora site builders being able to configure Mirador plugins from within Drupal's Admin interface. As well, to potentially import their own plugins and potentially develop new ones without having to fork the Islandora module.

I'd like this to serve as a documentation of how the whole process of bringing the Mirador React app in to Drupal works so it can be repeated and maintained without having to reverse engineer the code.

Import packages

Start with the standard Mirador Integration application hosted at https://github.com/ProjectMirador/mirador-integration

Then install the plugins you want, like:

npm install mirador-textoverlay

Import the module into the application source

In src/index.js, add the import statements for your plugins:

import miradorTextOverlay from 'mirador-textoverlay';

Check each plugin's README for precise instructions.

Delete the const config{} array declaration and the Mirador.viewer(config, [...]) function call.

The config will live in your Drupal module's own Javascript file.

Make Mirador identifier accessible to Drupal

The Mirador object needs to be attached to the window object so the Drupal-specific Javascript file can access it. Add the following line to your now nearly empty src/index.js:

window.Mirador = Mirador;

Declare the plugins

Webpack configuration

The only thing you may wish to change in the webpack config is to specify the 'production' directive:

in webpack/webpack.config.js, just before the last closing brace of the config array:

mode: 'production',

This can be changed to 'development' to get a non-minified version for debugging and development purposes.

'production' will minify the compiled application and optimize it for download by the browser.

Compile with Webpack

At this point you can resume following the instructions in mirador-integration.

$ npm run webpack

Webpack application splitting

Webpack will split large React applications to improve loading performance.

A compiled Mirador app ends up looking like this:

mirador-integration/webpack $ ls dist
0.main.js	2.main.js	4.main.js	6.main.js
1.main.js	3.main.js	5.main.js	main.js

A vanilla React app can find these chunks based on their having the same relative path as main.js. HOwever, since Drupal loads Javascript by attaching the .js files via the library service, we have to be explicit.

The folloowing is a working example with a development build of mirador-integration to show how you'd normally accomplish this in a Drupal module:

** islandora_mirador/islandora_mirador.libraries.yml** :

mirador:
  version: 3.3.0
  js:
    js/dist/main.js: { }
    js/dist/0.main.js: {  }
    js/dist/1.main.js: {  }
    js/dist/2.main.js: {  }
    js/dist/3.main.js: {  }
    js/dist/4.main.js: {  }
    js/dist/5.main.js: {  }
    js/dist/6.main.js: {  }
viewer:
  version: 1.x
  js:
    js/mirador_viewer.js: {preprocess: false}
  css:
    theme:
      css/mirador.css: {}
  dependencies:
    - core/drupalSettings
    - islandora_mirador/mirador

However, since we want to support an out-of-the-box experience for users who don't need to compile their own Mirador application, we must take advantage of the alter hook.

This way we can let the site builder specify whether to use a local or remote version of Mirador.