an approach on iteratively switching css frameworks while doing a major refactor

transitioning_to_twitter_bootstrap.md

An approach on iteratively switching css frameworks while doing a major refactor

Where I was coming from:

• Using a Rails app
• Had lots of custom css written on top of Blueprint / Compass
• Wanted to switch to use Twitter Bootstrap with Compass
• Wanted to take small steps

Prepare to run two sets of CSS

I created a separate folder for all the twitter bootstrap css and its own application.css file. In the application layout I chose which CSS to run based on a param

- if params[:which_css] == "tb"
  = stylesheet_link_tag "application_tb", :media => 'screen, projection'
-else
  = stylesheet_link_tag "application", :media => 'screen, projection'

Then edit the application layout markup to render correctly with either CSS (obviously while digging into the new css)

Make it easy to switch between CSS

In the application controller

def use_twitter_bootstrap
  params[:which_css] = 'tb'
end

Then you can just set a before filter

before_filter :use_twitter_bootstrap

Dig into the new CSS

• Write nice sparkly clean CSS for your application layout, make sure to match the look and feel 100% with the legacy version, so that users can't tell they are switching back and forth. (I found that I needed to write a little more css in this step, but just commented the areas that could be trimmed post transition)
• Start the conversation process with the easy elements first, for example static pages.
• Work through the app controller by controller or page by page, depending on your needs

The tricky things

Forms

Getting formtastic to work with two very different sets of CSS was a bit of a challenge. What I did was use the Formastic-Bootstrap gem and then on the transitioned views specified the form builder manually.

= semantic_form_for @something, :html => {:multipart => true, :class => "form-vertical"}, :builder => FormtasticBootstrap::FormBuilder do |f|

I've found this is kind of a lot to maintain and think in the long term moving over to simple form may be a better approach.

Shared Partials

I ran into a few instances of partials that were used in multiple views, some of which were using one version of CSS and some that were using the old.

I approached this a few different ways:

• Move over pages that have shared elements at the same time
• Edit the markup to work with either version
• Temporarily have two versions of the partial

Javascript

Since Twitter Bootstrap comes with some nice javascript add ons I also found myself in the midst of some JS decisions.

How I approached this:

• For JS that was called across the app, created a js helper that checked the :which_css param and then called the appropriate js.
• For page or controller specific js, I handled as I moved through the sections.
• For smaller items that were also site wide, like the tooltip, I used the old version through the transition and then looped back around at the end and switched over.

The Fun Part - DELETING

Once all the views are transitioned, go crazy deleting old css and making all the new files and builders the default.

The Important Part - REFACTORING

This process creates a lot of temporary code, you will have unneeded markup in the application layout, maybe a few duplicate files, and slightly bloated css (created while making sure old and new version matched exactly). I found myself making lot of comments in the code to remind myself where to go back and review post transition. Plus the new css will be shinny and new, so I'm sure you'll want to tinker with it :)