Twitter Bootstrap is an insanely popular CSS framework that is used to quickly and easily throw together great looking websites. Many websites (including this one) are built on this framework, and with good reason; the power and ease of use rival that of most other frameworks.

In this tutorial we will show you how to add the framework using the bootstrap-sass gem. We will also show you how to override the bootstrap styles using the various scss variables provided by the bootstrap framework. Finally we will show you how to use the will_paginate-bootstrap gem to style your pagination using bootstrap's pagination styles.

Project Set Up

In an existing or new project, add the following line:

gem 'bootstrap-sass', '~> 2.3'

Run a bundle install and start your rails server. Now that the gem is installed you are ready to to start using bootstrap.

The first thing we will need to do is create a new SCSS file to store our bootstrap configuration. Create a file called bootstrap_config.scss in the app/assets/stylesheets folder. This file will be used to store bootstrap specific configuration. Next, we will need to tell Rails to actually include bootstrap in this file. Open app/assets/stylesheets/bootstrap_config.scss and add the following line:

@import "bootstrap";

If you want a responsive layout, also add the following line:

@import "bootstrap-responsive";

This will include bootstrap in your application. Now, any views you create will automatically include bootstrap as long as they use the main application layout. We aren't quite done yet though, if you are on Rails 4 (Rails 3.2 users don't need to do this) you will need to perform one more step. Open up the config/application.rb file and add the following line to your application's configuration:

config.assets.precompile += %w(*.png *.jpg *.jpeg *.gif)

This is due to rails no longer compiling images in vendor assets by default.

Now go ahead and create a controller and try it out. If you aren't familiar with the framework itself, the absolute best place to learn about it is at The Official Twitter Boostrap Site. That's all there is to setting it up!

Bootstrap Variables

The bootstrap-sass gem, much like it's official LESS-based cousin, has a number of variables that you can override to change the look and feel of various styles. Lets try it out. Suppose we want to change the background color of our website. To do this we just need to open up app/assets/stylesheets/bootstrap_config.scss and add the following line to the very top of the file:

$bodyBackground: #e0e0e0;

Now, if you refresh the page you will notice that the body background has changed to a light gray color. For a complete list of all of the variables you can use, visit this page. Every variable is defined there along with all of the defaults.

Will Paginate

One pitfall that rails users often run into is utilizing will_paginate in a twitter bootstrap project. Luckily the will_paginate-bootstrap gem makes this very easy. Add the following line to your gemfile and then run a bundle install and restart your rails server:

gem 'will_paginate-bootstrap'

Now, open up the view where you are using will_paginate, find any will_paginate lines and add , :renderer => BootstrapPagination::Rails to the end of them so they look like this:

<%= will_paginate @products, :renderer => BootstrapPagination::Rails %>

Now if you refresh the page, you'll see that that will_paginate is now styled using bootstrap. That's it! You are all set.