Skip to content

Customizing

Jump to bottom Edit New page
Ronan edited this page Nov 26, 2013 · 41 revisions

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.

Configuration

Umlaut's configuration generally lives in ./config/umlaut_services.yml (for service plugins) and ./app/controller/umlaut_controller.rb for other configuration key/values. See Installation 'configuration' section for an overview, or look in those files in your local app, generated there by umlaut installer.

Customize CSS

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

For instance, here's how to change the colors of the Umlaut header ( example works with Umlaut 3.1+ and later )

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.

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 {
        background-color: #002d73; /* hopkins blue */
        color: #DDD; /* slightly off white to be less bright */
      }

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.

For more information on the Rails Asset Pipeline, please see the Rails Guide.

Notes

  • Umlaut's CSS (included require umlaut) automatically includes Bootstrap too -- Umlaut's CSS is based on bootstrap. The exact version of bootstrap can be controlled locally by what version of the bootstrap-sass gem you are using, updated with bundler or specified in your Gemfile -- subject to any restrictions expressed by the Umlaut gem.
  • jrochkind has found that sometimes, in development mode, he needs to delete his browser's cache in order to refresh changes in assets, not sure why, it's not supposed to work this way, an idiosyncracy of the rails asset pipeline.
  • When running a rails app in production mode, you'll have to precompile your assets, and re-precompile them when there are changes. See the Rails Guide.

Customize CSS with SASS variables (Umlaut 3.1+ only)

Umlaut's CSS is written in Sass, compiled with the standard Rails asset pipeline. Umlaut also includes bootstrap in Sass via the bootstrap-sass ruby gem.

Rather than trying to over-ride styles already defined by Umlaut/Bootstrap in pure CSS, it can be more efficient and maintainable to actually redefine Sass variables in your local app.

To do that, you need to switch your app's asset pipeline to be importing Umlaut's styles via Sass @import. First, remove the //= require 'umlaut' from your application.css, and instead create a file in your local app ./app/assets/stylesheets/umlaut_local.scss, and add a line @import 'umlaut'; to it.

  • You probably already have a require_tree . in your application.css, which says to include all the files in your app/assets/stylesheets, including this new one you just added.
  • You've switched from a require to the Sass-specific @import so you can hook into the Sass compilation to define Sass variables used by Umlaut's styles, and/or use Sass rules defined by Umlaut's styles.
  • You can call the new file you create anything you want, but do not call it umlaut.scss, or it'll conflict with umlaut's own style assets.

Now in your new umlaut_local.scss, you can define variables from Umlaut's sass or Bootstrap's sass, before the import, or use the rules defined by Umlaut after the import.

// Over-ride Bootstrap variables
$linkColor: 	blue;

// Over-ride umlaut variables, eg
$umlautBorderColor:                         #ebb211;
$umlautBackgroundColor:                     #fffdea;
$umlautAltBackgroundColor:	            #fcf1d4;
$umlautHighlightedBackgroundColor:	    white;
$umlautHighlightedSectionBorderColor:       #dedede;
$umlautAvailableColor:                      #00CC33;
$umlautUnavailableColor:                    red;

@import 'umlaut';

// Here, you could define your own styles using Umlaut or Bootstrap Sass
// variables, or using Sass `@include` or `@import` of mixins or styles
// defined by Umlaut or Bootstrap.

You might also want to actually redefine or alter mixins or classes defined by Umlaut or Bootstrap -- sorry, we're not actually sure the best practices for doing that, but please feel free to experiment and let us know, including requesting any changes to how Umlaut does things that might make things easier.

Custom header and footer templates (Umlaut 3.1+)

To customize the header and footer more fully than through CSS alone, you can provide local custom Rails template partials for the header and footer sections.

Umlaut provides header and footer in ./app/views/umlaut/_header.html.erb and _footer.html.erb.

You can provide your own local overrides of these partials, just add a file in your local app at ./app/views/umlaut/_header.html.erb or _footer.html.erb. You might want to copy the original Umlaut source to start with, to see some Umlaut utility functions that may be useful to you.

Note The header and footer are used on 'resolve' menu pages, as well as search pages and other Umlaut pages. Any logic involving resolve-specific data or instance variables needs to be guarded by conditionals that recognize the iVars may not be there.

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. NOTE If localizing the header and footer template is sufficient, that is recommended over localizing the entire layout; localizing the layout may create larger forwards compatibility problems with future Umlaut upgrades.

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)

In addition, note that you can add a custom help section to the resolve page. To do this, simply overwrite the help view partial and remove the line visibility :responses_exist for the help section in UmlautConfigurable.

'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

Add a custom footer
Add a custom sidebar
Clone this wiki locally