sul-dlss / mirador_rails

A gem for including Mirador 2 in Rails applications

MiradorRails

⚠️ mirador_rails is a Ruby gem for including Mirador 2 in Rails app. Please note that Mirador 2 is no longer under active development.

We recommend using Mirador 3 via the mirador npm package. Recommended approaches to embedding Mirador 3 are available on the Mirador wiki.

Installation

Add this line to your application's Gemfile:

gem 'mirador_rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mirador_rails

Mount the Engine

In your routes.rb file mount the MiradorRails::Engine

mount MiradorRails::Engine, at: MiradorRails::Engine.locales_mount_path

Usage

You can require the mirador js by requiring the following:

//= require mirador

And the css

/*
 *= require mirador
 */

You may not want to do this in your application.js, as the JavaScript by itself may add over 1.8MB to your application.js payload.

Initialize mirador in a view

<%= mirador_tag() %>

The mirador_tag method takes several arguments which allow for customization of the mirador view.

# @param [String] id
# @param [String] height
# @param [String] width
# @param [String] position
# @param [String] display
# @param [Hash] options Mirador settings

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Upgrading

From a new Mirador release build, run the rake task with the tag:

$ bundle exec rake update[v2.1.4]

Delete FontAwesome and MaterialIcons from mirador-combined.css. We include this in dependent gems instead.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sul-dlss/mirador_rails.

License

The gem is available as open source under the terms of the Apache 2.0.

mirador_rails's Issues

return 404 rather than 500 for missing locales

the problem is that Mirador is backing off on a 500 -- see https://github.com/i18next/i18next-xhr-backend/blob/master/i18nextXHRBackend.js#L148-L149

fix how to surface assets for mirador that works with a production asset pipeline

This code here -- https://github.com/sul-dlss/mirador_rails/blob/master/lib/mirador_rails.rb#L9
is not working during the precompilation stage in the production configuration (but on -stage).

We may be able to use ActionDispatch::Static to serve out the translation files, etc. but needs more investigation.

Add tests for view helper

Consider adding an option to enable an accessible instance of the viewer.

It is currently not possible to communicate with the Mirador instance created after initialisation. The instance variable can only be defined at the moment of initialisation, so this would need to be added here:

mirador_rails/lib/mirador_rails/view_helpers.rb

Lines 22 to 26 in 9bb9bda

	output << '<script type="text/javascript">' \
	' $(function() {' \
	" Mirador(#{config.to_json})" \
	' });' \
	'</script>'

Without this, it will not be possible for the containing application to interact with the instance, for instance, to read its state or fire events.

Usually the mirador tag is placed in an iframe, where it would be nice to expose the variable to the namespace, allowing the containing page to interact with it like so:

var miradorInstance = document.getElementById('mirador-iframe').contentWindow.innerMiradorInstance;

// Save the Mirador instance's state
myServer.post(miradorInstance.saveController.currentConfig);

Tinymce Assets

The Dependency for tinymce-rails must be set to < 5.0 because at that point they changed their themes to mobile and silver no longer modern!

Automate updating mirador

Manual process described here: https://github.com/sul-dlss/mirador_rails#upgrading