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">&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 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.6'

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" />

GlyphiconHelper

To display glyphicons, you can use the glyphicon helper. Here are some examples.

Display the "zoom in" icon

<%= glyphicon :ok, title: 'Approved' %>

will generate the HTML to render an "ok" icon with the "Approved" title:

<span class="glyphicon glyphicon-ok" title="Approved"></span>

Available glyphicons are listed in Boostrap documentation.

PanelHelper

To include Boostrap panels in your Rails views, you can use the panel helper. Here are some examples.

Basic panel

<%= panel body: 'You accepted the Terms of service.' %>

will generate the HTML to render a basic panel:

<div class="panel panel-default">
  <div class="panel-body">You accepted the Terms of service.</div>
</div>

Panel with heading

<%= panel body: 'You accepted the Terms of service.', heading: 'Congratulations' %>

will generate the HTML to render a panel with a heading:

<div class="panel panel-default">
  <div class="panel-heading">Congratulations</div>
  <div class="panel-body">You accepted the Terms of service.</div>
</div>

Panel with title

<%= panel body: 'You accepted the Terms of service.', title: 'Congratulations' %>

will generate the HTML to render a panel with a title:

<div class="panel panel-default">
  <div class="panel-heading">
    <h3 class="panel-title">Congratulations</h3>
  </div>
  <div class="panel-body">You accepted the Terms of service.</div>
</div>

Contextual panel

<%= panel body: 'You accepted the Terms of service.', title: 'Congratulations', context: :success %>

will generate the HTML to render a success panel (green background):

<div class="panel panel-success">
  <div class="panel-heading">
    <h3 class="panel-title">Congratulations</h3>
  </div>
  <div class="panel-body">You accepted the Terms of service.</div>
</div>

Available contexts are :default (default), :primary, :success, :info, :warning and :danger.

Complex panels

<%= panel tag: :aside do %>
  <div class='panel-body'>You accepted the Terms of service. <%= glyphicon :ok %></div>
  <div class='panel-footer'><h4>Thanks</h4></div>
<% end %>

will generate the HTML to render an aside panel with HTML body and footer:

<aside class="panel panel-default">
  <div class="panel-body">
    You accepted the Terms of service.
    <span class="glyphicon glyphicon-ok"></span>
  </div>
  <div class="panel-footer"><h4>Thanks</h4></div>
</aside>

PanelRowHelper

To include a row of Boostrap panels in your Rails views, you can use the panel_row helper. Here are some examples.

Basic row of panels

<%= panel_row column_class: 'col-sm-4' do %>
  <%= panel body: 'Panel #1' %>
  <%= panel body: 'Panel #2' %>
  <%= panel body: 'Panel #3' %>
<% end %>

will generate the HTML to render a row of three basic panels:

<div class="row">
  <div class="col-sm-4">
    <div class="panel panel-default"><div class="panel-body">Panel #1</div></div>
  </div>
  <div class="col-sm-4">
    <div class="panel panel-default"><div class="panel-body">Panel #2</div></div>
  </div>
  <div class="col-sm-4">
    <div class="panel panel-default"><div class="panel-body">Panel #3</div></div>
  </div>
</div>

Complex row of panels

<%= panel_row column_class: 'col-sm-4' do %>
  <%= panel title: 'User', context: :info do %>
    <div class='panel-body'><%= glyphicon :user %> John Smith</div>
  <% end %>
  <%= panel title: 'Phone' do %>
    <div class='panel-body'><%= glyphicon :earphone %> 323-555-5555</div>
  <% end %>
  <%= panel title: 'City' do %>
    <div class='panel-body'><%= glyphicon :record %> Los Angeles, CA</div>
  <% end %>
<% end %>

will generate the HTML to render a row of three panels with title and HTML body:

<div class="row">
  <div class="col-sm-4"><div class="panel panel-info">
    <div class="panel-heading"><h3 class="panel-title">User</h3></div>
    <div class="panel-body"><span class="glyphicon glyphicon-user"></span> John Smith</div>
  </div></div>
  <div class="col-sm-4"><div class="panel panel-default">
    <div class="panel-heading"><h3 class="panel-title">Phone</h3></div>
    <div class="panel-body"><span class="glyphicon glyphicon-earphone"></span> 323-555-5555</div>
  </div></div>
  <div class="col-sm-4"><div class="panel panel-default">
    <div class="panel-heading"><h3 class="panel-title">City</h3></div>
    <div class="panel-body"><span class="glyphicon glyphicon-record"></span> Los Angeles, CA</div>
  </div></div>
</div>

ModalHelper

To include Boostrap modals in your Rails views, you can use the modal helper. Here are some examples.

Basic modal

<%= modal title: 'Terms of service', body: 'Do what you want!' %>

will generate the HTML to render a button that toggles a model when clicked:

<button class="btn btn-default" data-toggle="modal" data-target="#modal-8684506463">
  Terms of service
</button>
<div class="modal fade" id="modal-8684506463" tabindex="-1" role="dialog" aria-labelledby="label-modal-8684506463" aria-hidden="true" style="display: none;">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal">
          <span aria-hidden="true">×</span><span class="sr-only">Close</span>
        </button>
        <h4 class="modal-title" id="label-modal-8684506463">Terms of service</h4>
      </div>
      <div class="modal-body">Do what you want!</div>
    </div>
  </div>
</div>

Complex modal

<%= modal title: 'Terms of service', size: :small, button: {caption: 'Continue', size: :large, context: :info} do %>
  Please accept the Terms of service.
  <div class="modal-footer"><button type="button" class="btn btn-primary">Accept</button></div>
<% end %>

will generate the HTML to render a large, info button (blue background) with the caption "Continue" that toggles a small modal with a title and HTML content:

<button class="btn btn-info btn-lg" data-toggle="modal" data-target="#modal-8022670096">
  Continue
</button>
<div class="modal fade in" id="modal-8022670096" tabindex="-1" role="dialog" aria-labelledby="label-modal-8022670096" aria-hidden="false" style="display: block;">
  <div class="modal-dialog modal-sm">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal">
          <span aria-hidden="true">×</span><span class="sr-only">Close</span>
        </button>
        <h4 class="modal-title" id="label-modal-8022670096">Terms of service</h4>
      </div>
      Please accept the Terms of service.
      <div class="modal-footer"><button type="button" class="btn btn-primary">Accept</button></div>
    </div>
  </div>
</div>

FormForHelper

To include Boostrap forms in your Rails views, you can use the form_for helper.

By default, Bh does not override the form_for method provided by ActionView. To apply Bootstrap classes and attributes, you must set the :layout option to

• :basic, in order to get a Basic form
• :horizontal, in order to get a Horizontal form
• :inline, in order to get an Inline form

Here is how a form with a text field and a submit button looks like with each layout:

<%= form_for @user, layout: :basic do |f| %>
  <%= f.text_field :name %>
  <%= f.submit %>
<% end %>

<%= form_for @user, layout: :horizontal do |f| %>
  <%= f.text_field :name %>
  <%= f.submit %>
<% end %>

<%= form_for @user, layout: :inline do |f| %>
  <%= f.text_field :name %>
  <%= f.submit %>
<% end %>

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