Leverage the Webpacker gem to incorporate Mirador Viewer into GeoBlacklight

5 min readMar 13, 2021

Mirador is an open-source, web-based, multi-window image viewing platform with the ability to zoom, display, compare and annotate images. It was built on the ReactJS framework. It is fully compatible with International Image Interoperability Framework(IIIF) specifications.

Webpack is a tool that lets you compile JavaScript modules. Given a large number of files, it generates a single file(or a few files), helps you manage the increasingly complicate dependency graph.

Webpacker is a Rails wrapper around the webpack build system that provides a standard webpack configuration and reasonable defaults.

To understand how it works, here is a brief example to install a Mirador viewer to a default rails project.

Install Mirador on a rails project

Since rails 6.x, webpacker comes in by default. With rails 5.x we need manually add it.

============

rails new testmirador

============

Run “rails server” and check if the server running properly from the browser:

Add “gem ‘webpacker’” in Gemfile, then run “bundle”:

Install it by “rails webpacker:install”. Can run “yarn upgrade” to fix the “unmet dependencies warning”. If successfully installed, a folder of “javascript” will be created under the app folder and a folder of “packs” under it. Basically, the javascript code we put in the “packs” folder is available to be included by the “javascript_pack_tag” in view files now.

Have a simple test:

Scaffold a test page: “rails g scaffold test content:text”

Change the routes in “config/routes.rb”: “root to: ‘tests#index’”

Migrate the database:”rake db:migrate”

Edit the “app/javascript/packs/application.js”, add a line of “console.log(‘Hello, Shawn greetings from Singapore’)”, then include this js file in “app/views/layouts/application.html” with “javascript_pack_tag”:

Run the server, if everything goes well, the webpacker will compile the application.js and log the string in the console:

Come to this step, the rest can be obvious.

Put mirador, react, react-dom in dependencies of package.json, then npm install them.

2. Import mirador in “app/javascript/packs/application”:

===========================

import Mirador from ‘mirador/dist/es/src/index.js’;

===========================

3. Instantiate the instance of mirador in “app/assets/javascript/application.js”:

===========================

window.onload = function(){
const config = {

id: ‘domid’,

windows: [{ manifestId: ‘https://Your.ManifestUrl/phillipinMani.json’,
}],

theme: { palette: { primary: { main: ‘#1967d2’, }, }, },

};

Mirador.viewer(config);
}

====================================

4. Put a dom element in view file “app/views/tests/index.html.erb”:

<div id=”domid”></div>

5. Compile and refresh the view page, if everything goes well, congratulations, you’ll have the mirador viewer on the test page now:

Install Mirador with plugins on Geoblacklight

Firstly, we create an instance of Geoblacklight with default template:

rails new gblMirador -m https://raw.githubusercontent.com/geoblacklight/geoblacklight/main/template.rb

Since the template will install the webpacker automatically, we don’t have to install it again. Seed some documents with “rake geocombine:index” then run the server “rake geoblacklight:server”, check from the browser if it running correctly:

If you encountered an error of “Webpacker::Manifest::MissingEntryError”, can just run “rails webpacker:install” again to fix it.

Secondly, import mirador with plugins:

Add dependencies in package.json, then “npm install”:

Include mirador and plugins in “app/javascript/packs/application.js”

====================================

import Mirador from ‘mirador/dist/es/src/index.js’;
import miradorImageToolsPlugin from ‘mirador-image-tools/es/plugins/miradorImageToolsPlugin.js’;

window.Mirador = Mirador;

window.miradorImageToolsPlugin = miradorImageToolsPlugin;

=====================================

Third step, add config file and override initializer:

Create a new file “iiif_manifest.js” under “app/assets/javascripts/geoblacklight/viewers”:

==================================

//= require geoblacklight/viewers/viewer

GeoBlacklight.Viewer.IiifManifest = GeoBlacklight.Viewer.extend({
  load: function() {
    var manifest_uri = document.getElementById('map').getAttribute('data-url');

    var miradorInstance = Mirador.viewer({
       id: 'map',
       themes: {
         light: {
           palette: {
             type: 'light',
             primary: {
               main: '#0088ce',
             },
           },
         },
       },
       windows: [{
         manifestId: manifest_uri,
         thumbnailNavigationPosition: 'far-bottom',
       }],
       window: {
         hideSearchPanel: false,
         hideWindowTitle: true,
         hideAnnotationsPanel: true,
         allowClose: false,
         allowMaximize: false,
         allowFullscreen: true,
       },
       workspace: {
         showZoomControls: true,
       },
       workspaceControlPanel: {
         enabled: false,
       }
     });
  }
});

==================================

Create a new file “item_viewer.rb” under “config/initializers” to override the geoblacklight ItemViewer:

==================================

module Geoblacklight
  class ItemViewer
    def initialize(references)
      @references = references
    end

    def viewer_protocol
      return 'map' if viewer_preference.nil?
      viewer_preference.keys.first.to_s
    end

    def viewer_endpoint
      return '' if viewer_preference.nil?
      viewer_preference.values.first.to_s
    end

    def wms
      @references.wms
    end

    def iiif
      @references.iiif
    end

    # HERE - Added viewer
    def iiif_manifest
      @references.iiif_manifest
    end

    def tiled_map_layer
      @references.tiled_map_layer
    end

    def dynamic_map_layer
      @references.dynamic_map_layer
    end

    def feature_layer
      @references.feature_layer
    end

    def image_map_layer
      @references.image_map_layer
    end

    def index_map
      @references.index_map
    end
    
    # HERE - also need to specify viewer preference
    def viewer_preference
      [index_map, wms, iiif, iiif_manifest, tiled_map_layer, dynamic_map_layer,
       image_map_layer, feature_layer].compact.map(&:to_hash).first
    end
  end
end

==================================

If everything goes well, we’ll have our mirador viewer embedded in the document detail view page now:

Fourth step, config plugins for mirador:

Edit the iiif_manifest.js file we created in the last step, at config field of “windows”, add setting “ imageToolsEnabled” as true; then put in the second parameter for the viewer() method to pass the plugin. (the first parameter of the viewer() method is the config hash).