Skip to main content
OCLC Support

Mirador 3 integration

  1. Last updated
  2. Save as PDF

 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:

  1. Create an empty custom page, which serves as the container for Mirador viewer.
  2. Upload Mirador 3 JavaScript file to your site (or link to it).
  3. Add custom 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 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

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:

  • 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

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:

  • 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 install
    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.

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.

Step 3 – Custom JavaScript file

There is the main JavaScript file that pulls together the pieces of this recipe and makes them work. This main script does two things:

  • 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.

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.

Verification

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.