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 will 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-integration-omeka and the fork at https://github.com/digitalutsc/mirador-integration-omeka by the Digital Text unit of University of Toronto Scarborough.

Why rebuild?

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 textOverlayPlugin from 'mirador-textoverlay/es';

Check each plugin's README for precise instructions.

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

The config is defined by the Islandora Mirador Drupal module, allowing plugins to modify the configuration.

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;

Define the plugins array

In Drupal you need to make the plugins referenceable by adding them to the window object:

window.miradorPlugins = [
  ...miradorImageToolsPlugin,...textOverlayPlugin,
];

The ... is the Javascript spread operator. It just expands the iterable variables that reference each plugin into a series of individual object references.

Webpack configuration

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.

Webpack application splitting

By default, 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, it will be easier if we just have one application source file to deal with.

For that we need the Webpack chunk plugin:

Alter the webpack/webpack.config.js file to look like this:

const path = require('path');
const webpack = require('webpack');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist'),
  },
  mode: 'production',
  plugins: [
    new webpack.optimize.LimitChunkCountPlugin({
      maxChunks: 1,
    }),
  ],

};

Now you can compile a custom Mirador app to drop into your Drupal installation:

npm run webpack

The output file, called main.js will be in webpack/dist/

Drop this in to your Drupal installation at web/libraries/mirador/dist.

Altering the Drupal libraries definitions

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.