Skip to main content
OCLC Support

Mirador 2 integration

  1. Last updated
  2. Save as PDF

 View a recording: Embedding the Mirador Viewer.
 Note: This video demos an older method of integrating Mirador Viewer with primary and secondary scripts. Now we’ve simplified the recipe to use only one script as shown below.

See CONTENTdm training or the event announcement for more information.

 Link:  See a live example.

Download: View and download source code from Mirador 2 integration section.

Customization prepared in collaboration with the Huntington Library.

The Mirador viewer is a popular open-source image comparison and manuscript viewer that utilizes the IIIF Image and Presentation APIs to load digital images from digital repositories. Through CONTENTdm’s native support for IIIF, you can integrate Mirador into your website and give your end users another option for viewing your content. Because many modern digital repositories today support IIIF, other organizations’ content can be compared side-by-side with yours in the Mirador viewer.

Integrating Mirador is somewhat complicated due to the large number of files and scripts involved. The overall process looks like this:

  1. Create an empty custom page, which serves as the container for Mirador viewer.
  2. Download Mirador package from the project’s GitHub page and upload the files to CONTENTdm.
  3. Add JavaScript to CONTENTdm that inserts a Mirador button and loads the viewer.

Step 1 – Create the custom page container

The basis for Mirador integration will be a standard Custom Page which will be the container for Mirador viewer (see Create a custom page for more information). This HTML page has inline CSS styling to clear all margins and padding, and to create a clean slate for Mirador viewer to be loaded. Click the links below to view the sample HTML page that is used in the live example. You need to view the page source to see the HTML code.

 View:  View the HTML code.

View page source to see HTML code.

You may use this page for your customization. Download this HTML or copy the source code to create your own. If you would like to display a different page title for your Mirador viewer, modify the title in the YAML header at the top of the HTML. You can also view this custom page with the YAML syntax:

 View:  View the HTML under YAML syntax.

This shows the custom page with Mirador viewer loaded.

This HTML page should be uploaded in the Website Configuration Tool on the Custom > Custom Pages dialog using the manage files tool. This recipe assumes the page is uploaded at the top level and the file is named mirador.html.

Step 2 – Add the Mirador package to CONTENTdm

Mirador is open-source software and the project home is in the GitHub repository. You can download the Mirador package from the official release page.

The 2.7.0 version will be the last 2.x release of Mirador because all development effort has shifted to version 3. Download the 2.7.0 build.tar.gz or build.zip package, and then expand the file to your local disk. You will see a mirador directory containing a large number of files and subdirectories.

In the CONTENTdm Website Configuration Tool, go back to the Custom > Custom Pages > Manage Files dialog. Click the Upload icon, and then Add file(s) to open your local file browser. Locate the mirador directory you just created from the build.tar.gz or build.zip package and upload it, along with everything it contains. This recipe assumes that you have uploaded the mirador directory to the top level—the same place where mirador.html was added in Step 1.

Step 3 – Custom JavaScript files

There are two main goals for custom JavaScript as part of this recipe:

  1. inserting a Mirador button on the item page of any records that have IIIF API support (all image records), and
  2. loading all of the Mirador files into the custom page container.

For this recipe, these operations are handled by the JavaScript file which loads everything at the proper time in the page lifecycle, makes sure the button appears in the correct places, and to load Mirador in a new tab when the button is clicked. The JavaScript file should be added to your site on the Custom > Custom Scripts dialog in the Website Configuration Tool.

 View: View the script.

Verification

To verify this recipe, open your browser and navigate to a CONTENTdm item on your website that is an image file (to be certain it has IIIF API support). Clear your local browser cache (or use a private/incognito window) to make sure you have the most recent version of your custom JavaScript files. You should see the Mirador icon to the right of the Download or Print icons in CONTENTdm. Click the icon. A separate window will open with that record loaded inside the Mirador viewer.

Doing more with Mirador

This recipe gives you a way to integrate Mirador as a separate viewer within your existing CONTENTdm pages. There are many ways you could extend beyond this concept. Mirador has been designed to function based on a JavaScript object, which is built in this recipe by the .js file in Step 3. You can modify the settings in that object to change the initial appearance of Mirador or modify what is available to end users. Learn more about the flexibility of Mirador in the GitHub guide, Configuring Mirador.

Another potential application of Mirador would be to integrate it deep into your CONTENTdm page. This recipe builds on the concept that Mirador loads into a separate browser window or new tab, but there is no technical reason why Mirador could not be embedded directly in CONTENTdm, or even used to replace the OpenSeadragon viewer that is the default CONTENTdm image viewer. That type of customization is a little more complicated than this recipe, but is possible.

Another interesting idea is to create a Mirador link that opens a window with multiple records displaying in Mirador’s comparison mode. For example, you could display the front and back of a postcard in a single Mirador window, or display 4 or 6 or 8 images that relate to one another for visual comparison. These approaches would not be difficult to extend beyond this recipe by taking advantage of the configuration options described in the ProjectMirador GitHub guide, Configuring Mirador.

As with all CONTENTdm cookbook recipes, CONTENTdm staff are interested in working with you to do more. If you have any ideas and need guidance, contact OCLC Support. If you create an interesting new application of Mirador in your CONTENTdm site, please consider sharing that with the larger CONTENTdm community through this Advanced Customization Cookbook.