Skip to main content
OCLC Support

Universal Viewer integration

Universal Viewer is a community-developed, IIIF-based viewer that has similar functionality to Mirador. Any IIIF content can be loaded and displayed in Universal Viewer. This recipe uses version 4 of Universal Viewer and integrates it into CONTENTdm in the same way as the other IIIF-based viewer recipes.

The design of this recipe is simpler than the Mirador recipe because it loads the Universal Viewer application from a public content delivery network called jsDelivr rather than serving it directly from CONTENTdm. The files used in this recipe can be viewed and downloaded from the CONTENTdm Cookbook download portal under the Universal Viewer section.

There are two pieces needed to integrate Universal Viewer. The overall process looks like this:

  1. Create an empty custom page, which serves as the container for Universal Viewer.
  2. Upload the custom JavaScript file that inserts a Universal Viewer button and loads the viewer.

Step 1: Create the custom page container

The basis for this recipe will be a standard Custom Page which will be the container for Universal Viewer (see Create a custom page for more information). This HTML page has inline CSS styling to clear all margins and padding.

Download the uv.html custom page file for this integration. You can modify this HTML file as you see fit. For example, if you would like to display a different page title when Universal Viewer loads, edit the title in the YAML header at the top of the HTML code.

Upload your uv.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 uv.html. If you rename the file you will also need to modify the JavaScript file used in step 2.

Step 2: Add the custom JS file

This recipe requires only a single JavaScript file that is used in conjunction with the uv.html file above. This script does two things:

  • Inserts a Universal Viewer button on the item page of any records that have IIIF API support, and
  • Loads Universal Viewer and renders it into the custom page container with the IIIF Manifest of the item.

This JavaScript file is called uv-cp.js and can be downloaded from the Universal Viewer section of the Cookbook recipe portal. Note that this file’s name may change in the future to include a version number if there are updates to the script code.

If you have no other custom JavaScript running on your website, upload the uv-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 uv-cp.js into the main custom JS file for your CONTENTdm site. The code in uv-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 uv-cp.js to your list of files to be loaded.

After you have uploaded uv-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 running 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 Universal Viewer icon (the letters “UV”) to the right of the Download or Print icons on the item page in CONTENTdm. Click the button and a separate window will open with that record loaded inside Universal Viewer.