Bh - Bootstrap Helpers
Bh provides a set of helpers that streamlines the use of Bootstrap components in Rails views.
The full documentation is available at rubydoc.info.
Bootstrap is a great framework, but requires to write many lines of HTML code even for simple components. For instance, you need to write the following HTML to show a dismissible alert:
<div class="alert alert-info alert-dismissible" role="alert">
<button type="button" class="close" data-dismiss="alert">
<span aria-hidden="true">×</span>
<span class="sr-only">Close</span>
</button>
You accepted the Terms of service.
</div>
Writing this for every dismissible alert in a web site is cumbersome, repetitive, and prone to errors.
Bh offers a solution to this problem by means of a set of helper methods. The example above can be rewritten with just one line of code:
<%= alert_box 'You accepted the Terms of service.', dismissible: true %>
alert_box is only of the helpers provided by Bh and described below.
You can use only the ones you need and even mix-and-match the "standard way"
of writing Bootstrap components (many HTML lines) with the "Bh way".
How to install
Bh is meant to be included in Rails apps by adding this line to the Gemfile:
gem 'bh', '~> 0.0.3'
Since the gem follows Semantic Versioning,
indicating the full version in your Gemfile (~> major.minor.patch)
guarantees that your project won’t occur in any error when you bundle update
and a new version of Bh is released.
Adding 'bh' to your Gemfile is all you need! From now on, you will be able to use any of the following Bh helpers in your Rails views.
AlertHelper
To include Boostrap alert boxes in your Rails views, you can use the alert_box helper. Here are some examples.
Basic alerts
<%= alert_box 'You accepted the Terms of service.' %>
will generate the HTML to render an "info" alert:
<div class="alert alert-info" role="alert">You accepted the Terms of service.</div>
Dismissible alerts
<%= alert_box 'You accepted the Terms of service.', dismissible: true %>
will generate the HTML to render an alert with an '×' to close it:
<div class="alert alert-info" role="alert">
<button class="close" data-dismiss="alert" type="button">
<span aria-hidden="true">×</span><span class="sr-only">Close</span>
</button>
You accepted the Terms of service.
</div>
Contextual alerts
<%= alert_box 'You accepted the Terms of service.', context: :success %>
will generate the HTML to render a "success" alert (green background):
<div class="alert alert-success" role="alert">You accepted the Terms of service.</div>
Available contexts are :success, :info (default), :warning, :danger.
Priority alerts
Since a common use of alert boxes in Rails applications is to display
flash messages,
the alert_box helper accepts the priority of the flash message as an option.
<%= alert_box 'You accepted the Terms of service.', priority: :notice %>
will generate the HTML to render a dismissible "success" alert (green background):
<div class="alert alert-success" role="alert">
<button class="close" data-dismiss="alert" type="button">
<span aria-hidden="true">×</span><span class="sr-only">Close</span>
</button>
You accepted the Terms of service.
</div>
Available priorities are :alert, :notice.
Complex alerts
<%= alert_box context: :success, dismissible: true do %>
<strong>Thanks!</strong> You accepted the <%= link_to 'Terms of service', '/terms' %>.
<% end %>
will generate the HTML to render a dismissible "success" alert that includes highlighted text and appropriately styled links:
<div class="alert alert-success" role="alert">
<button class="close" data-dismiss="alert" type="button">
<span aria-hidden="true">×</span><span class="sr-only">Close</span>
</button>
<strong>Thanks!</strong> You accepted the <a href="/terms" class="alert-link">Terms of service</a>.
</div>
CdnHelper
To load the CSS and JS files of Bootstrap from BootstrapCDN, you can use the bootstrap_css, bootstrap_theme_css and bootstrap_js helpers. Here are some examples.
Load the latest Bootstrap assets
<%= stylesheet_link_tag bootstrap_css, bootstrap_theme_css, :application %>
<%= javascript_include_tag bootstrap_js, :application %>
will generate the HTML to load the latest versions of Bootstrap CSS, Bootstrap Theme CSS and Bootstrap JS from MaxCDN, before your application assets:
<link href="//netdna.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
<link href="//netdna.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css" media="screen" rel="stylesheet" type="text/css" />
<link href="/assets/application.css" media="screen" rel="stylesheet" type="text/css" />
<script src="//netdna.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js" type="text/javascript"></script>
<script src="/assets/application.js" type="text/javascript"></script>
Load a specific version of a Bootstrap asset
<%= stylesheet_link_tag bootstrap_css(version: '3.1.0', minified: false, scheme: :http) %>
will generate the HTML to load the non-minified 3.1.0 versions of Bootstrap CSS over HTTP scheme:
<link href="http://netdna.bootstrapcdn.com/bootstrap/3.1.0/css/bootstrap.css" media="screen" rel="stylesheet" type="text/css" />
How to release new versions
If you are a manager of this project, remember to upgrade the Bh gem whenever a new feature is added or a bug gets fixed.
Make sure all the tests are passing on Travis CI, document the changes in CHANGELOG.md and README.md, bump the version, then run
rake release
Remember that the bh gem follows Semantic Versioning. Any new release that is fully backward-compatible should bump the patch version (0.0.x). Any new version that breaks compatibility should bump the minor version (0.x.0)
How to contribute
Bh needs your support!
If you find that a method is missing, fork the project, add the missing code, write the appropriate tests, then submit a pull request, and it will gladly be merged! If you need an inspiration, look at the TODO.
To run the tests, simply type rspec on the command line.
Don’t hesitate to send code comments, issues or pull requests through GitHub and to spread the love. Thanks! :)