Tech Blog

Accessing Digital Resources with a Custom Viewer

In a previous blog post we showed how to integrate collections into an external application. We leveraged the Alma digital viewer to display digital materials stored in Alma. The Alma digital viewer is a good generic delivery interface which provides basic support for multi-file representations, metadata, and diverse file types such as images, audio, video, and PDF files.

In this post, we explore how to integrate a custom viewer to display digital objects stored in Alma for those scenarios which require a specific user experience.

Alma Digital Viewer

The Alma Digital Viewer shows the files in a particular representation. It includes a table of contents, metadata, and content pane. Below is an example of the viewer showing a bibliographic record with one representation and four files.

Custom Viewer

To integrate with a custom viewer, we’ll need to retrieve information about the files stored in a representation. To do that, we use the Get Representation Files API. In this example, we’ll display the files in the same representation shown above in an open source photo album viewer called Light Gallery.

In our web page, we include links to Light Gallery’s JavaScript and CSS files. When a user clicks on the link to access the material in a gallery view, we intercept the click with jQuery code. Then we make and AJAX call to the titles method of the collections controller in our Ruby on Rails application from the previous blog post.

$("#titles").on("click", ".lightgallery-dynamic", function(e){
   $.getJSON( $(this).data('url'), function( data ) {
   $(this).lightGallery({dynamic: true, dynamicEl: data});

The titles method provides a handler for JSON format which calls a method called get_files:

format.json {
   render json: get_files(params[:id])['representation_file'].map{|f|
      {src: f['url'], subHtml: "<h4>#{f['label']}</h4>"}

The get_files method first calls the Get Representations API for the specific bibliographic record. In our case, we use the first representation returned, although of course other logic could be employed. We then call the Get Files API for the desired representation.

def get_files(mms_id)
   reps = alma_api_get "/bibs/#{mms_id}/representations"
   files = alma_api_get 

Then we map the returned representation into the JSON expression which the Light Gallery expects including the file’s URL and file label. That JSON is returned back to the JavaScript on our page, and in turn fed into the Light Gallery method which uses the data to display the viewer.


While each viewer is different this example shows how digital files stored in Alma can be displayed in a custom viewer with a few lines of code.

The code used here is available in this Github repository.


Leave a Reply