The following notes refer to customizing the UI in a Sufia instance that utilizes the Sufia gem. This causes some challenges in that a Sufia install using the gem does not contain most of the files that generate the Sufia UI. Any customizations have to override the existing files. One generally does this by placing a copy of the file (with changes) in the same path within the Sufia app. Note that this does force a burden in terms of updating to later versions.

Note that the Sufia gem is likely saved in a variation of this location path: /usr/lib64/ruby/gems/2.3.0/gems/sufia-7.2.0 or in /home/vagrant/.bundle/ruby/2.3.0/sufia-*.

Adding a favicon to Sufia entails two actions. First, the .ico file should be placed in two locations: /sufia/public/ and /sufia/app/assets/images/. In general, the favicon will be serviced out of the assets path, but some testing suggests it may occasionally be expected to come from the other.

The next action is to copy the _head_tag_extras.html.erb from the SUFIA_GEM_PATH/app/views/ source into its equivalent location /sufia/app/views/. This partial is where you can include extra items for insertion into the head of all HTML pages. For our purposes, we will insert the code for including the favicon. The entire file contents will look like:

<%# Override this partial in your application to insert extra HEAD content into every page %>
<%= favicon_link_tag 'favicon.ico' %>

Note that this could be made a standard part of Sufia. The best approach would be to use a conditional that only inserts it if the /sufia/app/assets/images/favicon.ico file exists.

There are two parts to doing CSS management in Sufia. One is working with SASS variables and the other is inserting custom rules and selectors.

In order to be able to override variables and mix-ins used by Bootstrap and other SASS-enabled libraries in Sufia, we need to prepend our own local SCSS file into /sufia/app/assets/stylesheets/sufia.scss. Add the following line of code into sufia.scss before the rest of the @import statements:

@import 'local_variables';

You can now define and thereby override any SASS variables by entering them into /sufia/app/assets/stylesheets/local_variables.scss. Note the extension is an SCSS file.

This works because SASS sets a variable's value when it is first declared. This is why our local variables file should come before the other import statements.

For good style, one should only include variables, mixins, and other SASS statements in local_variables.scss. Actual rules should be placed in the file discussed in the next section.

Again, we're going to use a local file for our custom CSS, but this time we are going to put the import statement in /sufia/app/assets/stylesheets/application.css. The import statement is inserted at the end of the file simply as:

@import 'local_rules';

You will then put your CSS selectors and rules into local_rules.scss. Again, this is an SCSS file so that we can use variables, mixins, etc. You also need to include

@import 'sufia';

at the start of the file so that the variables will be loaded in.

Adding HTML elements to a page requires finding the relevant .html.erb file in the Sufia gem's source. These files will be found in SUFIA_GEM_PATH/app/views/. Once you've identified the file, you need to copy it into the same relative location in your Sufia application. For example, to add a <div> to the top of the header for UW Library branding, one needs to copy the file _masthead.html.erb over.

For easier management, it is recommended that changes to base Sufia files be minimal. Whenever possible, add a partial rendering. For example, the following code was added to _masthead.html.erb:

<%= render partial: '/local_masthead' %>

This means that Rails will insert the HTML in _local_masthead.html.erb into the page at that location within the masthead partial. Note that the leading underscore is how Rails knows a template file is a partial and not a full template.

To add JavaScript to all pages on Sufia, we turn to the files /sufia/app/assets/javascripts/application.js. This is a manifest file in that it dictates what files get loaded on all pages. Any files in that directory (or subdirectories) can be loaded via that manifest file. For example, if the file foobar.js is in /sufia/app/assets/javascripts/widgets/, you can make it load by adding the following line to application.js:

//= require widgets/foobar

Every Sufia page will then load that file.

• Whenever we have to copy a compiled file from the Sufia gem, we should copy it twice. Once to the original name and the other with a .orig file extension. We'll use diffs between the .orig file and the Gem file to see if it changed between pull requests from the Hydra Sufia repo.

Xray-rails is a development-only gem that helps you identify what parts of a Rails page are generated by which partial. It even digs into existing gems and reveals the file paths to those partials. Super helpful when trying to figure out what to edit.

Installation just has a few caveats beyond what is listed on the GitHub page for the gem:

1. For sanity's sake, add the code snippet before the flipflop gem in the Gemfile. This might not be 100% necessary but it avoids one of the many Hydra gem headaches.

2. When running bundle afterwards, you'll probably need to run bundle as sudo. Yes, this is generally not kosher and frowned upon, but this is only for a developer instance. The xray gem will never be used on production. So far, nothing bad appears to have happened.