Tech Blog

Exposing Collections in External Applications

by Josh Weisman Ex Libris April 24, 2016 (Updated: December 18, 2018)

Collections in Alma can be used to group bibliographic records into a hierarchical structure. While any bibliographic records can be added to collection, a primary use case is to organize digital resources. As such, records which have digital inventory must be associated with a collection.

Alma can be configured to publish collection information to Primo, and Primo has built-in functionality to allow users to discover and browse collections managed in Alma. Some institutions may want to expose collections in external applications, such as a university or library portal. For example, the library may wish to provide a custom home page for a collection which represents a special exhibit.

In this post, we’ll use the collection APIs to provide the following functionality:

Lobby with a list of top level collections
Collection home page which includes sub-collections and collection members

We’ll add this functionality to the My Alma Library sample app that we’ve used in the past. The application is written in Ruby on Rails.

Collection Lobby

One possible entry point for our collection interface is a lobby which lists the top level collections. To build this list, we’ll use the Get Collections API. The Get Collections API returns a list of collections, and takes a parameter which indicates how many levels in the hierarchy to provide. Since we only want to display the top level collections, we’ll use the default of 1 for the level parameter. So in our collection controller, we’ll use a helper method to call the Get Collections API:

def index
   @collections = alma_api_get "/bibs/collections"
end

Then in our collection index view, we’ll loop through all of the top level collections and display the collection name, description and thumbnail using the appropriate properties. From each top level collection we’ll provide a link to view the collection’s home page.

Collection Home Page

The collection home page will need to support the display of both sub-collections and collection titles. In the controller, we first use the Get Collection API to retrieve the collection details with a level parameter of 2, indicating that we’d like sub-collections that are direct descendants of our collection. We also retrieve the first page of titles using the Get Collection Titles API.

def show
   @collection = alma_api_get "/bibs/collections/#{params[:id]}?level=2"
   @titles = get_titles params[:id]
end

def get_titles(collection_id)
   start = params["start"] || 0
   @limit = params["limit"] || 6
   alma_api_get "/bibs/collections/#{collection_id}/bibs?offset=#{start}&limit=#{@limit}"
end

Sub Collections

In the show collection view, we again display the thumbnail, name, and full description. If the collection array is populated, we loop through it displaying the name and thumbnail for each sub-collection.

Titles

If the collection contains titles, we include a titles partial view. The titles partial view loops through each title and shows the bibliographic record’s thumbnail and title field. We then make use of a helper method to display some paging control based on the total number of titles in the collection and the current page being displayed.

Displaying the titles in a partial view allows us to perform paging without refreshing the entire screen by updating the titles panel with subsequent AJAX calls. When a user clicks on the page number or the next/previous buttons, we use some jQuery magic to show a loading icon and call the titles path.

$("#titles").on("click", "a.paging-link", function(e) {
   $("#titles").html('<%= image_tag "loading.gif" %>');
   var url='<%= collection_titles_path(@collection["pid"]["value"])%>';
   $("#titles").load(url + '?' + (this.href.split('?')[1] || ''));
   return false;
});

Rails returns the titles HTML without any layout, and jQuery populates the titles div with the response. This allows for a seamless paging experience for the users.

Integrating with the View It

In order to allow the user to access the resources contained in the collection, we want to integrate with the fulfillment mash-up. Assuming the material is available online, there are two ways we can display the view-it. First, we can show the view-it in a pop up window and the user will see all of the delivery options available for the selected resource.

Alternatively, we can have Alma open the digital viewer directly over our collection interface in a lightbox. This is an idea solution if we expect the bibliographic records to be primarily digital resources. This requires that we configure direct linking for digital resources in Alma and that we include the Alma delivery JavaScript and CSS files in our page.

To accomplish this we create a hidden iFrame:

<iframe style="display: none" id="delivery"></iframe>

When a user clicks the View link, we intercept the click with some jQuery and populate the iFrame with the view-it:

$("#titles").on("click", "a.popup", function(e){
   e.preventDefault();
   var url = $(this).attr('href');

   // hidden iFrame method (requires automatic open setting in Alma)
   $("#delivery").attr('src', url);
}

Alma will then open the viewer in the delivery lightbox:

Further Exploration

We’ve described here how to allow access to collection information either from a top level lobby, or from an individual collection. Additionally, you can configure Alma to enrich bibliographic records with collection details during publishing. Then from your 3^rd party discovery tool, you can provide a link from a particular item record to its related collections.

All of the code used in this blog entry is available in this GitHub repository. Good luck and leave a comment with your experience in exposing your collections to external applications.