Theming

Theming Blacklight

Bootswatches

The Blacklight 4.x styling is Twitter Bootstrap based. While there is some Blacklight-specific code for handling layouts and positions, most (if not all) the "styling" (colors, fonts, etc) are handled by Bootstrap.

There are many sources for Bootstrap themes. We'll look at bootswatches because they are fairly painless to integrate into a Rails application.

First, add the bootswatch-rails gem to your Gemfile (and run bundle install):

gem 'bootswatch-rails'

This will give you the set of themes from http://bootswatch.com/, converted to SASS and exposed to the Rails asset pipeline.

Out of the box, your application's blacklight stylesheet (generated by default to app/assets/stylesheets/blacklight.css.scss) looks something like:

@import 'bootstrap';
@import 'bootstrap-responsive';

@import 'blacklight/blacklight';

To add the one of the bootswatch themes ('cerulean' in this example):

@import "bootswatch/cerulean/variables";

@import "bootstrap";
@import "bootstrap-responsive";

@import "bootswatch/cerulean/bootswatch";

@import 'blacklight/blacklight'

The bootswatch-rails documentation provides similar directions, a list of available out-of-the-box themes, and more.

As of this writing, not all bootswatch-rails themes seem to be bootstrap 2.1.x compatible, or do weird things to the Blacklight navbar, etc. Your milage may vary.

Developing a Customized "Local" Theme

In most cases, you will want to develop your own theme within your Blacklight app, outside of the Bootswatch gem. To do this, you can do the following in your app/assets/stylesheets directory:

1. create your own _variables.scss and _bootswatch.scss files in stylesheets/ (easiest way to do this is to copy those files from the bootstrap-sass project or an existing theme and customize from there)
2. change application.css to application.css.scss
3. add the import statements given in the above "theming" example to application.css.scss
4. delete blacklight.css.scss

So, your application.css.scss should look like this:

@import "variables";

@import "bootstrap";
@import "bootstrap-responsive";

@import "bootswatch";

@import 'blacklight/blacklight'