UMD Lib Style

Gem containing the common UMD Libraries Rails application layout and styles. Built on Bootstrap 3.3.6.

Changelog

See CHANGELOG.md for information about changes to this gem.

Git Tagging

When a new version of this gem is created, be sure to update the version number in the lib/umd_style/version.rb to match the Git tag.

Usage

In your app's Gemfile:

gem 'umd_lib_style', github: 'umd-lib/umd_lib_style', branch: 'develop'

to use the "develop" branch version of the gem, or

gem 'umd_lib_style', github: 'umd-lib/umd_lib_style', ref: '<GIT_TAG>'

where <GIT_TAG> is the Git tag of the version to use. For example, to use the Git tagged "1.0.1" version, use:

gem 'umd_lib_style', github: 'umd-lib/umd_lib_style', ref: '1.0.1'

Then run the usual:

$ bundle install

Finally, edit your app's application files to use the scripts, styles, and layouts:

1. Add //= require umd_lib to app/assets/javascripts/application.js

2. Rename app/assets/stylesheets/application.css to application.scss

3. Add @import "umd_lib"; to app/assets/stylesheets/application.scss

4. Change the contents of app/views/layouts/application.html.erb to the following:

   <% provide :app_name, 'My UMD Libraries App' %>
   <%= render 'layouts/umd_lib' %>

Bootstrap Notes

This gem uses Bootstrap SASS version 3.3.6. The Bootstrap assets are copied directly into the vendor/assets directory.

If you are starting from an app that already loaded Bootstrap directly into your CSS or Javascript, you must replace the relevant require or @import statements with the ones to load umd_lib listed above.

In addition, your app will no longer need the bootstrap-sass gem and you can remove it from your Gemfile.

Scaffolding CSS

If you generated your app with Rails scaffolding, you should remove the app/assets/stylesheets/scaffold.css.scss file, to remove any potential conflicts with the Bootstrap styles.

content_for blocks

The "content_for" block allows for additions/customization of particular sections of the layout.

Additional "head" content - additional_head_content

Enables additional directives to be added into the "head" section of the HTML page.

Additional "head" content - Sample Usage

In Rails 5.2, an additional "csp_meta" tag is added into the "head" section of the layouts/application.html.erb file. To include this tag into a Rails application using this gem, add a content_for block to your app/views/layout/application.html.erb file

<% content_for :additional_head_content do %>
  <%= csp_meta_tag %>
<% end %>

Custom Navbar - navbar

This gem provides a fixed full page width navigation bar at the top of the page, containing the application name and a set of drop-down menus.

Custom Navbar - Sample Usage

The application name is set using a "app_name" block. To include your own custom markup in the navbar, add a content_for block to your app/views/layout/application.html.erb file.

<% provide :app_name, 'Autonumber Service' %>

<% content_for :navbar do %>
  <ul class="nav navbar-nav">
    <li><%= link_to 'Auto Numbers', auto_numbers_path %></li>
    <li><%= link_to 'Names', names_path %></li>
    <li><%= link_to 'Repositories', repositories_path %></li>
  </ul>
<% end %>

<%= render 'layouts/umd_lib' %>

Custom Nav Banner - "navbar_banner"

Displays a full page width banner directly below the navbar, which will not scroll off the screen. Used by the Annual Staffing Request application to show a banner when impersonating another user.

Custom Nav Banner - Sample Usage

<% content_for :navbar_banner do %>
  <%= render 'layouts/impersonate' %>
<% end %>

Environment Banner

In keeping with SSDR policy, an "environment banner" will be displayed at the top of each page when running on non-production servers.

By default, in the local development environment (determined by Rails.env.development? returning true), a "Local Environment" banner will be displayed.

On non-production servers, the environment banner can be configured using the following environment variables:

• ENVIRONMENT_BANNER - the text to display in the banner
• ENVIRONMENT_BANNER_FOREGROUND - the foreground color for the banner, as a CSS color
• ENVIRONMENT_BANNER_BACKGROUND - the background color for the banner, as a CSS color
• ENVIRONMENT_BANNER_ENABLED - (optional) "false" (case-sensitive) disables the banner. Anything else (including blank, or not providing the variable) enables the banner.

Page Content Container class

By default, the content of the page is placed in a <div> using the Bootstrap "container" class. Applications (such as Annual Staffing Request) may wish to override this setting to use some other class, such as "container-fluid". To do so, add the following "provide" line to your app/views/layout/application.html.erb file:

<% provide :container_class, "container-fluid" %>

Footer - "application_footer"

Per UMD policy, a footer containing a "Web Accessibility" link is provided by default. Applications wishing to override the default footer can do so by defining a "content_for" block to your app/views/layout/application.html.erb file.

Footer - Sample Usage

<% content_for :application_footer do %>
  <footer class="footer">
    <p>Custom footer</p>
  </footer>
<% end %>