Bh - Bootstrap Helpers

Bh provides a set of powerful helpers that streamlines the use of Bootstrap components in Rails views.

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">&times;</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 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.2'

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.

The alert_box helper

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>

alert-basic

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>

alert-dismissible

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.

alert-success

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.

alert-success-dismissible

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>

alert-complex

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.md file.

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! :)