Link: 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:
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.
Mirador 3 is a complete rewrite from Mirador 2 and is distributed and packaged in a different way. You can load the entirety of Mirador 3 as a single JavaScript file, which is much simpler than Mirador 2. This recipe follows this approach and is based on a pre-built JavaScript file. To load this version of Mirador 3:
There are other ways to access Mirador 3. For this recipe, we have built the Mirador package from source code. If you want to use a specific version of Mirador 3 or update the version in the future, you can build a single JavaScript version for yourself. Mirador is open-source software, and the project home is in their GitHub repository. To build Mirador, do the following:
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.
Another way to use Mirador 3 is to load it directly from a public CDN. A popular free CDN service called unkpg distributes a wide variety of open-source JavaScript projects. You can directly link to Mirador 3 in unkpg using this URL: https://unpkg.com/browse/mirador@latest/dist/mirador.min.js
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.
There is the main JavaScript file that pulls together the pieces of this recipe and makes them work. This main script does two things:
This main JavaScript file is called mirador3-cp.js and can be downloaded from the Cookbook recipe portal page. (The actual file name is appended with version numbers, such as mirador3-cp-1_2.js, which won’t affect the following steps if used consistently when you apply the recipe.)
If you have no other custom JavaScript running on your website, upload the mirador3-cp.js file in the Website Configuration Tool on the Custom > Custom Scripts dialog. If you already have a JavaScript file added on the Custom Scripts page, you will need to modify that JavaScript file and copy the entire contents of mirador3-cp.js into the main custom JS file for your CONTENTdm site. The code in mirador3-cp.js is contained in a single function so can safely live alongside other JavaScript code. If you are using the Load multiple JavaScript files recipe, you can add mirador-cp.js to your list of files to be loaded.
After you have uploaded mirador3-cp.js, Save and Publish in the Website Configuration Tool to complete the installation of the recipe.
To verify this recipe, open your browser and navigate to a CONTENTdm item on your website that you know has IIIF API support. This could be an image, or a PDF if your site is on Cantaloupe. 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 on the item page in CONTENTdm. Click the icon. A separate window will open with that record loaded inside the Mirador 3 viewer.