Twitter Bootswatch Rails gem
- Integrates Twitter Bootstrap CSS & Font Awesome toolkit into the Rails 3.1+ Asset Pipeline
- Easy control over which javascript and less modules are loaded by default. Not every app needs a carousel
- Simple default less files for custom application themes ("[theme_name]/variables.less" and "[theme_name]/bootswatch.less")
- Easily apply different custom themes or bootswatches from a site like bootswatch.com
- Create several themed swatches for your project with theme_names, (e.g. an admin theme and a storefront theme using namespaced theme_names)
- Gem version semantics extend Twitter Bootstrap version semantics, making it simple to know what version of bootstrap the gem is using
Includes Twitter Bootstrap for Rails 3.1+ Asset Pipeline
Twitter Bootstrap is a toolkit from Twitter designed to kickstart development of webapps and sites. It includes base CSS and HTML for typography, forms, buttons, tables, grids, navigation, and more.
Includes Font Awesome for Rails 3.1+ Asset Pipeline
Font Awesome is a toolkit with iconic fonts designed for use with Twitter Bootstrap.
/*
*= require_self
*= require [theme_name]/loader
*= require font-awesome/font-awesome
*/
If you need the ie7 fix:
/*
*= require_self
*= require [theme_name]/loader
*= require font-awesome/font-awesome-ie7
*/
Demo
The demo will show you how this gem can be used in a rails 3.1+ application.
View Helpers
The gem twitter-bootswatch-rails-helpers provides rails view helpers for twitter bootstrap's breadcrumbs and alerts components.
Install
Include the Twitter Bootswatch Rails gem in Gemfile to install it from RubyGems.org:
group :assets do
# rails default gems
...
# just put after rails asset defaults
gem 'twitter-bootswatch-rails', '~= 2.3.1.1'
end
# View Helpers Gem can go outside the assets group
gem 'twitter-bootswatch-rails-helpers', '>= 2.3.1'
or you can install from latest build;
gem 'twitter-bootswatch-rails', :git => 'git://github.com/scottvrosenthal/twitter-bootswatch-rails.git'
Run bundle from command line
bundle
Installing to App (using Generators)
You can run the following generators to get started with Twitter Bootstrap & Font Awesome quickly.
If you don't provide a [theme_name] the value defaults to bootswatch and adds directives to your application.css and application.js files.
Usage:
rails g bootswatch:install [theme_name]
Example:
rails g bootswatch:install admin
rails g bootswatch:install storefront
Layout (generates a basic Twitter Bootstrap compatible layout) - (haml-rails gem supported)
Usage:
rails g bootswatch:layout [theme_name]
Example:
rails g bootswatch:layout admin
rails g bootswatch:layout storefront
Themed (generates Twitter Bootstrap compatible scaffold views.) - (simple_form and haml-rails gems supported)
Usage (model and table must already exist):
rails g bootswatch:themed [RESOURCE_NAME]
Example:
rails g scaffold Post title:string description:text
rake db:migrate
rails g bootswatch:themed Posts
Import a free bootswatch.com theme
Just follow these three steps in the following order :)
rails g bootswatch:install cyborg
rails g bootswatch:import cyborg
rails g bootswatch:layout cyborg
The above creates a namespaced theme under assets/javascript/cyborg assets/stylesheets/cyborg and a new layout file.
The import generator pulls directly from the bootswatch.com git repo cyborg directory.
- bootswatch.less
- variables.less
In your rails controllers just tell it to use the cyborg layout.
layout: 'cyborg'
You can also create an admin namespaced theme and import the cyborg bootswatch.less and variable.less files:
rails g bootswatch:install admin
rails g bootswatch:import admin/cyborg
rails g bootswatch:layout admin
Need more examples? Check out the demo
Using stylesheets with the less-rails gem
You have to require "[theme_name]/loader.css.less" in your application.css
/*
*= require_self
*= require [theme_name]/loader
*= require font-awesome/font-awesome
*/
"[theme_name]/loader.css.less" allows you to easily comment out less modules you don't need in your application.
For instance, as per the Twitter Bootstrap project we don't include the responsive styles by default. Uncomment @import "twitter/bootstrap/responsive";
in "[theme_name]/loader.css.less" to enable it.
"[theme_name]/variables.less" customize Twitter Bootstrap "variables.less" defaults in this file.
"[theme_name]/bootswatch.less" customize the style of Twitter Bootstrap base css and component style here.
Check out some of the swatches at bootswatch.com
Read up on the less-rails gem.
base.less
When importing a custom bootswatch.less file manually you'll need to include the following import directive at the top of the file:
@import "base";
The import base.less directive allows the importing less file to access and override inherited less variables.
Example:
@import "base";
// Cyborg 2.3.1
// bootswatch.less
Using Javascripts
You have to require the coffeescript file "[theme_name]/loader.coffee" in your application.js:
//= require jquery
//= require jquery_ujs
//= require [theme_name]/loader
"[theme_name]/loader.coffee" allows you to easily comment out modules you don't need in your application:
# [theme_name]/loader.coffee
#= require twitter/bootstrap/bootstrap-transition
#= require twitter/bootstrap/bootstrap-alert
#= require twitter/bootstrap/bootstrap-button
#= require twitter/bootstrap/bootstrap-carousel
#= require twitter/bootstrap/bootstrap-collapse
#= require twitter/bootstrap/bootstrap-dropdown
#= require twitter/bootstrap/bootstrap-modal
#= require twitter/bootstrap/bootstrap-tooltip
#= require twitter/bootstrap/bootstrap-popover
#= require twitter/bootstrap/bootstrap-scrollspy
#= require twitter/bootstrap/bootstrap-tab
#= require twitter/bootstrap/bootstrap-typeahead
#= require twitter/bootstrap/bootstrap-affix
#= require [theme_name]/bootswatch
"[theme_name]/bootswatch.coffee" allows you to easily add swatch customization to javascript modules loaded:
Check out some of the swatches at bootswatch.com
Responsive styling?
As per the Twitter Bootstrap project we don't include the responsive styles by default. Uncomment @import "twitter/bootstrap/responsive";
in "[theme_name]/loader.css.less" to enable it.
Local rails development assets not updating?
RAILS_ENV=development rake assets:clean
Versioning
Bootstrap claims to use SemVer, although this is for values of public API that don't seem to include selectively requiring CSS components (see breaking change 2.0.4 -> 2.1.0). Since many people using bootstrap-swatch-rails do selectively require CSS components and I consider it part of the public API we can't really follow SemVer without becoming wildly out of sync with the Bootstrap version number, which is confusing for everyone involved. Further releases to bootstrap-swatch-rails will therefore have version numbers of the form 2.x.x.y
, where 2.x.x
is the release of Bootstrap we should be compatible with, and y
is the patch version.
Changelog
- v2.3.1.0
- Updated to bootstrap 2.3.1
- v2.3.1.1
- Added theme_name functionality, if a theme_name isn't passed in you get the default install, i.e, uses bootswatch as theme_name
- Included bootstrap version number at the top of each asset file created by generators
- Added Font Awesome to the asset pipeline as an opt in using an asset directive
- Added import generator to dynamically pull in free bootswatch.com themes and add correct import directives
- v2.3.1.2
- Updated gemspec docs
- Updated import generator to allow importing bootswatch.com themes under existing namespaced themes
- rails g bootswatch:import admin/cyborg