Customizing

There are a variety of ways to customize Umlaut look-and-feel and behavior in your local app.

In general, you should find the smallest, cleanest, most "surgical" way of specifying a desired customization. The less code you write, the less code you over-ride (or copy-and-paste or duplicate) from Umlaut, the better. This will make it more likely you'll be able to upgrade to future versions of Umlaut without problems, and it will minimize the amount of code you have to maintain locally in a local 'fork' of some part of umlaut's functionality.

You should never edit code in Umlaut gem source for purely local use, there should always be a way to customize Umlaut behavior in your local app using the standard distro un-modified gem. If there's not, we should fix/refactor Umlaut so there is. The only reason to edit Umlaut gem code is to write something to contribute back to Umlaut as a bug fix or new feature. Or to just generally experiment and see how Umlaut works. But we recommend running an app based on a locally modified version of Umlaut -- unless you really want to create a local fork.

Here are some ways Umlaut can be customized by your local app.

Customize CSS

A large amount of look and feel changes can actually be done purely with custom CSS, over-riding Umlaut's styles.

(The Umlaut CSS is unfortunately currently a bit messy. TODO is refactoring it to be neater, perhaps using SCSS for dynamicly generated CSS with variables for colors and such. But you can still over-ride it as is).

For instance here's how to replace the textual header with a local image. We will make use of the Rails 3.1 asset pipeline, which assembles our CSS. Assuming you have an ./app/assets/application.css with the line *= require_tree . in it.

Put your local image in, say, ./app/assets/images/my_header.png

Create a file in your local ./app/assets/stylesheets, any name you want but ending in css.erb, say umlaut_override.css.erb, containing:

      .umlaut .header h1 {
        /* hide text for visual browsers but leave readable by screen
           readers, we're going to provide a background img for visual
           instead */
         position:absolute;
         left:-10000px;
         top:auto;
         width:1px;
         height:1px;
         overflow:hidden;
      }
     
      .umlaut .header {
         background: url(<%= asset_path 'my_header.png' %>) no-repeat;
         height: 36px; /* height of your image, need to make room */
      }

The <%= %> business is ERB (note how the file ends in .erb), allowing us to call out to a ruby function to generate an inward-pointing url to your image.

You could use other CSS background position attributes and change the height if you want a bit of space around your image.

You could also turn off Umlaut stock CSS entirely by removing the require umlaut line from your local ./app/assets/stylesheets/application.css, but then you'd have to provide a lot of CSS yourself to have Umlaut elements display usably.

Local Rails layout

A Rails 'layout' is a wrapper template providing standard HTML wrapper markup, headers, footers, etc. By default, Umlaut pages use a built-in Umlaut layout inside Umlaut gem source at ./app/views/layouts/umlaut.html.erb.

If you need more customization than you can get from CSS alone (custom navbar, removing or altering layout of permalink url, etc), you can provide your own local layout file instead.

Your default Rails app already includes a helper at ./app/views/layouts/application.html.erb, you can start there, but you'll want to include a few things from the standard umlaut helper (see source) to get full functionality:

• Include render_umlaut_head_content in section to get some automatic umlaut functionality like OpenSearch auto-discovery links.
• Wrap the yield in a div with classes "umlaut container" for umlaut stock CSS to apply properly.
• Optionally include permalink as demonstrated in stock umlaut layout.
• Optionally set a header and html <title> using umlaut logic as demonstrated in the umlaut stock layout.
• Include a 'footer' div to make current CSS apply correctly; footer div can optionally include some standard umlaut functionality, such as a 'credits' line and some debugging links, as demonstrated in the stock umlaut layout.

To use a local layout, in your local ./app/controllers/umlaut_controller.rb, set:

layout "application"

Or any other named local layout.

Note that the default layout includes some debugging links in footer already, triggered by inclusion in your UmlautController config of:

• test_resolve_base ("[T]" link to configured test resolver for current page)
• sfx.sfx_base_url ("[S]" link to native SFX results for current page)

'Section' configuration

Umlaut uses it's own system for declaratively specifying HTML sections that appear on the resolve page. This is not a standard Rails thing, it's Umlaut's invention.

These sections are used for placing content on the HTML page, and are also used for returning content from Umlaut's APIs and the JQuery Content Utility.

You can customize the section configuration in UmlautController, by editing the default array to:

• Change section titles or short description prompts for a section, eg:

  fulltext = resolve_sections.find {|s| s[:div_id] == "fulltext"}
  fulltext[:section_title] = "Digital Fulltext"
  fulltext[:section_prompt] = "Available from various sources"

• Delete sections entirely (prob don't need to do this, you might want to change visibility logic instead)

• Re-order sections

  A method is provided on the resolve_sections array to re-order sections by :div id. For instance, to make the :document_delivery section come before the :holdings section:

  resolve_sections.ensure_order!("document_delivery", "holding")        

• Add new sections (advanced topic, probably only needed if you are writing custom service plugins, and maybe not even then)

• Change over configuration regarding visibility logic and others. For complete documentation of options available, see generated docs for SectionRenderer

Write custom local service plugin

Writing a custom local service plugin should be pretty much the same process as writing an official Umlaut distro service plugin, the source will just live in your local app instead of in shared Umlaut distro codebase. Unless you have a local service whose functionality is really quite unique to your environment, consider contributing it back to Umlaut.

See [Writing a Service Plugin] (tbd)