Leverage the Webpacker gem to incorporate Mirador Viewer into GeoBlacklight
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).
Refresh the view page, we have the image tool plugin enabled in our embedded mirador viewer now!
Happy coding!
Special thanks to Jack Reed
Demo1 repo on Github
Demo2 repo on Github