Umlaut in Blacklight: Software designed for re-use and extension

One of the goals of Umlaut, for a while now, has been to serve as a piece of back-end library infrastructure, a provider “known item services” in other web applications.

We’ve had Umlaut integrated in our Horizon OPAC, and Xerxes metasearch, for a while now for those purposes.

Now it’s implemented in our demo (prototype, unfinished, very rough around the dges) Blacklight too.

Here’s an example Yes, it loads in via AJAX, a little bit slowly. Once it loads in, from Umlaut are: the book cover, the “limited excerpts” links (yes, these need some styling); and everything over in the left column; the Amazon “summary”.  (assuming we haven’t redesigned the Umlaut page before you read this).

Umlaut has, for a while,  provided some javascript libraries to make it easy to embed Umlaut content for a known item on a page. But for the Blacklight integration, I wrote a new one based on JQuery which is, if I say so un-humbly, very slick.

The new helper should make it awfully easy to embed Umlaut content via javascript on any page which: 1) has an OpenURL on it for your known item, which you can target with a JQuery selector, and 2) for which you can add an external Javascript file or three.

For instance, here’s the Javascript file that loads external Umlaut content onto the Blacklight page via AJAX. You have complete control of where each section of Umlaut content goes, with the full power of JQuery selectors.  And lots of callbacks; for instance here I add a spinner to the page, but take it away when Umlaut load is complete.

The Blacklight end

So how hard was it to get that in Blacklight? Not very. Thanks to lots of hard work, Blacklight is becoming better architected for flexible extension. Still a lot to do, but it’s getting there.

First, I had to get an OpenURL link on the page. (This could be in a hidden element or something, but I wanted to show it).   So how do you get an OpenURL from a Blacklight document?  BL comes with a very very basic OpenURL context-object output from Marc already; but it’s really really basic, just barely good enough for a COinS for Zotero, but not good enough for much else, like this.

So I needed a better Marc-to-OpenURL translator.  So first I wrote one  (not yet released publically, part of my overall Marc mapping/display plugin not yet released publically, but if you want it, I could share it;  it’s just not documented and test-covered yet, and I’m still trying it by fire).

Then adding it in to Umlaut is easy:

 # Setup and register extension to provide better Marc to OpenURL mapping,
 # from the MarcDisplay plugin
 SolrDocument.extension_parameters[:rfr_id] = ""
 SolrDocument.extension_parameters[:self_uri_prefix] = ""
 SolrDocument.use_extension(MarcDisplay::Blacklight::MarcToOpenUrlExtension) do |document|

Since I’ve hooked it into Umlaut in a standard way, now even the COinS for Zotero will use it to get a better OpenURL context object.

And I can easily use it in my custom view to stick an OpenURL link to Umlaut on the page, using some local config I set in a JHConfig singleton object in an initializer.   (Many BL deployers already use a custom ‘show’ view).

<% @sidebar_items << capture do %>
 <% if( JHConfig.params[:umlaut_base_url] &&
       document.export_formats.keys.include?(:openurl_ctx_kev)) %>
   <% link_to(JHConfig.params[:umlaut_base_url] +  "/resolve?#{document.export_as_openurl_ctx_kev}" , :rel=>"nofollow", :class=>"findit_link") do %>
     <img src="<%= JHConfig.params[:umlaut_base_url] %>/images/jhu_findit.gif" alt="Find It @ JH" />
   <% end %>      
 <% end %>
<% end %>

If we later index things in Blacklight that are not Marc, and thus don’t (yet) have an OpenURL export, no problem. No exceptions will be raised, the OpenURL link simply won’t show up on the page, and the subsequent Umlaut AJAX code won’t be triggered.  You want it, all you’ve got to do is write some code to translate the new format to OpenURL, and then package in an Umlaut document extension, and add in the extension in your initializers. Beautiful!

Once this OpenURL link is on the page, the rest is javascript. Include a few standard support JS files from Umlaut, and include the Javascript file I linked above for loading and mapping from Umlaut to your page DOM. That js file will have to be written for a local app, since it’s about mappings to the DOM that are going to be different for every app, since people like to re-write  their ‘show’ views.  But the JQuery helper makes it pretty straightforward to write the mapping, I think.

Here’s my code in an initializer which ensures the proper Javascript is injected into the Umlaut output.

if (JHConfig.params[:umlaut_base_url])
 setup_umlaut = lambda do |controller|
 # include Umlaut JQuery object for updating page with umlaut stuff
 controller.extra_head_content << "<script src=\"#{JHConfig.params[:umlaut_base_url]}/javascripts/jquery/umlaut/update_html.js\" type=\"text/javascript\"></script>"

 # Include Umlaut js object for loading Umlaut js behaviors
 controller.extra_head_content << "<script type=\"text/javascript\" src=\"#{JHConfig.params[:umlaut_base_url]}/js_helper/loader\"></script>"

 # Include our JS to actually update page with jquery stuff
 controller.javascript_includes << "umlaut_include"

 # local CSS for embedded Umlaut content
 controller.stylesheet_links << "umlaut_content"

 CatalogController.before_filter setup_umlaut, :only => :show

(If I had to do it over again, I think I’d put the worker method in an actual method that gets “include’d” into the CatalogController instead of an anonymous lambda, but it works.)

One more part

In our Horizon OPAC, Umlaut-OPAC integration is a two way street. Not only is Umlaut content embedded in the OPAC (done in Blacklight), but Umlaut _querries_ the OPAC for full text links and physical holdings to put on the Umlaut page. (and in fact it’s kind of circular — OPAC asks Umlaut for content, Umlaut querries OPAC and delivers content back to OPAC including some from external sources and some actually from the OPAC, possibly other records).

That part isn’t done yet, Umlaut needs a good ‘api’ to query Blacklight.  Half of that is the super neato Atom response I added to Blacklight, with alternate format (like Marc) discovery in the feed. The other half is the external client, like Umlaut, needs a way to specify queries — the queries Umlaut normally uses for that are too complex to fit in BL’s ordinary interface (or even in the prototype Blacklight ‘advanced search’), like ”  isbn = X OR (author = Y and title = T)”.

So for that half, I’m writing a CQL plugin to blacklight, that will let CQL querries be given to Blacklight, and result in HTML or Atom or what have you results.

Work in progress.


5 thoughts on “Umlaut in Blacklight: Software designed for re-use and extension”

  1. Hey Jonathan,

    This is maybe unrelated but I was looking at your blacklight instance and noticed that, in the example you posted, you’re giving a link to worldcat identities. But that link doesn’t show in, for example, this record . How are you determining where to add in the identities link? Are you only pulling identities when there’s a 100 field? Thanks!

  2. Hi Anna, it is indeed related, because that link is coming from Umlaut services. I don’t recall exactly how the Umlaut service looks, but I can look it up…

    The Umlaut plugin for worldcat identities uses: A) An OCLCnum OR B) An author name

    And then uses either or both to try and look up a match at

    And then my code that turns a Marc record into an OpenURL for Umlaut, I _think_ will only turn 1xx fields into OpenURL author.

    So if the record doesn’t have a 1xx or an OCLCnum, Umlaut won’t end up even trying to fetch a Worldcat Identities record. If it does, then Umlaut will contact Identities to try and find a match, but Identities in some cases won’t respond with a match, so the link won’t show up there either.

    I haven’t really looked into the details of how often this service works, but it might only work when there’s an OCLCnum in the record, perhaps my code is buggy with the author lookup. Only a minority of our records have OCLCnums in them.

    Hope that was enlightening. The links you seem to have meant to embed in your comment didn’t make it through, so I can’t tell you exactly why it does or doesn’t show up in the records you were looking at, not sure which ones you were looking at.

  3. Do you/can you get MHOLD information via Umlaut?

    This also makes me wonder if this will be a good route for us as we incorporate authority info (Worldcat identities being one such resource).

  4. I don’t know what “MHOLD” information is, sorry!

    The Umlaut stuff isn’t really based on authority info (except as reflected in the bib record), nor, in my opinion really a substitute for incorporation of authority info in the Solr indexes. I still plan/ hope to incorporate authority info in the solr indexes somewhere down the line, for instance to make sure authority record “see also” synonyms are incorporated in the index appropriately. Not in the current “phase 1” plan though.

    The Umlaut data flow is basically: 1) Construct an OpenURL out of the marc record (using code that’s not in Blacklight core, but is very easily shareable, and includable in your BL installation using the BL document extension framework). Send it to Umlaut. 2) Umlaut uses that OpenURL to consult a variety of external services and knowledge bases, including our local SFX as well as things like Amazon, Google, HathiTrust, etc. 3) Umlaut constructs some HTML out of that. 4) Sections of HTML are incorporated on the Blacklight item detail page via AJAX. (It would theoretically be possible to incorporate them on the search results page too, but Umlaut is kinda slow since it needs to call out to so many external web services, so not sure how well this would work out in practice for 10-at-a-time without destroying Umlaut.)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s