Mirador 3 integration
See a live example.
Download: View and download source code from the Mirador 3 integration section.
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.
This recipe is for version 3 of Mirador, which is a significant upgrade from Mirador 2 and incorporates many usability and accessibility improvements. Mirador 3 also has a simpler architecture for integrating into CONTENTdm.
There are a few pieces needed to integrate Mirador 3. The overall process looks like this:
- Create an empty custom page, which serves as the container for Mirador 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 displays a loading animation while Mirador 3 loads up the first time. All of the files used in this recipe can be viewed and downloaded from the CONTENTdm Cookbook download portal under the Mirador 3 integration section. The mirador3.html file is the HTML page used in the live example.
Download the mirador3.html file for your Mirador 3 integration. You can modify this HTML file as you see fit. For example, if you would like to display a different page title for your Mirador 3 viewer, edit the title in the YAML header at the top of the HTML code.
Upload your mirador3.html file in the Website Configuration Tool on the Global Settings > Custom > Custom Pages dialog using the manage files tool. This recipe assumes the HTML file is uploaded at the top level of the file structure (not in a subdirectory) and the file is named mirador3.html.
Step 2 – Determine how to load Mirador3 to your site
- Download the file called mirador.min.js from the Cookbook recipe portal page.
- In the Website Configuration Tool, create a folder called js using the manage files tool on the Custom > Custom Pages dialog.
- Upload mirador.min.js to the js folder you created.
- Move on to step 3.
Other options for Step 2 – Advanced users
- Have npm configured on your computer and have some familiarity with running command-line scripts to build software.
- Download the source code files for the version of Mirador 3 you want to use from the Releases page.
- Uncompress the package of source files.
- In a shell window, change the directory into the Mirador directory that was created when the package was uncompressed.
- Run the following two commands:
npm run-script build
Those two commands can take several minutes to complete. You might see some errors and warnings along the way that can often be ignored. If the process was successful, you will see a new mirador.min.js file in a subdirectory named “dist”. The file should be somewhere around 2MB in size. Once you have generated this file, you can upload it in the Website Configuration Tool in the same way as described above for Step 2.
The “@latest” indicator will always grab the most recent release of Mirador. If you prefer to load a specific version, you can visit the unpkg site and use the version selector to get the URL of your preferred version: https://unpkg.com/browse/mirador@latest/
Once you know which version you want to use from unkpg, you only need to modify the path in the mirador3-cp.js script (described below) to point to the unkpg URL you have chosen. This approach is not the default in the recipe, so you will need to modify the code in mirador3-cp.js to make it work.
- Inserts a Mirador button on the item page of any records that have IIIF API support, and
- Loads Mirador 3 and renders it into the custom page container with the IIIF Manifest of the item.
After you have uploaded mirador3-cp.js, Save and Publish in the Website Configuration Tool to complete the installation of the recipe.