-
Notifications
You must be signed in to change notification settings - Fork 10
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.
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.
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.
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
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.
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;
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.
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.
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.
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.