Bh - Bootstrap Helpers
======================
Bh provides a set of helpers that streamlines the use of
[Bootstrap components](http://getbootstrap.com/components) in Rails views.
The **full documentation** is available at [rubydoc.info](http://rubydoc.info/github/Fullscreen/bh/master/frames).
[](https://travis-ci.org/Fullscreen/bh)
[](https://coveralls.io/r/Fullscreen/bh)
[](https://gemnasium.com/Fullscreen/bh)
[](https://codeclimate.com/github/Fullscreen/bh)
[](http://rubydoc.info/github/Fullscreen/bh/master/frames)
[](http://rubygems.org/gems/bh)
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_:
```html
You accepted the Terms of service.
```
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:
```rhtml
<%= 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.7'
Since the gem follows [Semantic Versioning](http://semver.org),
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](http://getbootstrap.com/components/#alerts)
in your Rails views, you can use the [alert_box](http://rubydoc.info/github/Fullscreen/bh/master/Bh/AlertHelper) helper.
Here are some examples.
Basic alerts
------------
```rhtml
<%= alert_box 'You accepted the Terms of service.' %>
```
will generate the HTML to render an *info* alert:
```html
You accepted the Terms of service.
```
Dismissible alerts
------------------
```rhtml
<%= alert_box 'You accepted the Terms of service.', dismissible: true %>
```
will generate the HTML to render an alert with an `×` to close it:
```html
You accepted the Terms of service.
```
Contextual alerts
-----------------
```rhtml
<%= alert_box 'You accepted the Terms of service.', context: :success %>
```
will generate the HTML to render a *success* alert (green background):
```html
You accepted the Terms of service.
```
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](http://api.rubyonrails.org/classes/ActionDispatch/Flash/FlashHash.html),
the `alert_box` helper accepts the priority of the flash message as an option.
```rhtml
<%= alert_box 'You accepted the Terms of service.', priority: :notice %>
```
will generate the HTML to render a dismissible *success* alert (green background):
```html
You accepted the Terms of service.
```
Available priorities are `:alert`, `:notice`.
Complex alerts
--------------
```rhtml
<%= alert_box context: :success, dismissible: true do %>
Thanks! 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:
```html
```
CdnHelper
=========
To load the CSS and JS files of Bootstrap from
[BootstrapCDN](http://getbootstrap.com/getting-started/#download), you can use
the [bootstrap_css](http://rubydoc.info/github/Fullscreen/bh/master/Bh/CdnHelper),
[bootstrap_theme_css](http://rubydoc.info/github/Fullscreen/bh/master/Bh/CdnHelper) and
[bootstrap_js](http://rubydoc.info/github/Fullscreen/bh/master/Bh/CdnHelper) helpers.
Here are some examples.
Load the latest Bootstrap assets
--------------------------------
```rhtml
<%= 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:
```html
```
Load a specific version of a Bootstrap asset
--------------------------------------------
```rhtml
<%= 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:
```html
```
GlyphiconHelper
===============
To display [glyphicons](http://getbootstrap.com/components/#glyphicons),
you can use the
[glyphicon](http://rubydoc.info/github/Fullscreen/bh/master/Bh/GlyphiconHelper) helper.
Here are some examples.
Display the "zoom in" icon
--------------------------
```rhtml
<%= glyphicon :ok, title: 'Approved' %>
```
will generate the HTML to render an "ok" icon with the "Approved" title:
```html
```
Available glyphicons are listed in [Boostrap documentation](http://getbootstrap.com/components/#glyphicons).
PanelHelper
===========
To include [Boostrap panels](http://getbootstrap.com/components/#panels)
in your Rails views, you can use the
[panel](http://rubydoc.info/github/Fullscreen/bh/master/Bh/PanelHelper) helper.
Here are some examples.
Basic panel
-----------
```rhtml
<%= panel body: 'You accepted the Terms of service.' %>
```
will generate the HTML to render a basic panel:
```html
You accepted the Terms of service.
```
Panel with heading
------------------
```rhtml
<%= panel body: 'You accepted the Terms of service.', heading: 'Congratulations' %>
```
will generate the HTML to render a panel with a heading:
```html
Congratulations
You accepted the Terms of service.
```
Panel with title
----------------
```rhtml
<%= panel body: 'You accepted the Terms of service.', title: 'Congratulations' %>
```
will generate the HTML to render a panel with a title:
```html
Congratulations
You accepted the Terms of service.
```
Contextual panel
----------------
```rhtml
<%= panel body: 'You accepted the Terms of service.', title: 'Congratulations', context: :success %>
```
will generate the HTML to render a *success* panel (green background):
```html
Congratulations
You accepted the Terms of service.
```
Available contexts are `:default` (default), `:primary`, `:success`, `:info`,
`:warning` and `:danger`.
Complex panels
--------------
```rhtml
<%= panel tag: :aside do %>
You accepted the Terms of service. <%= glyphicon :ok %>
<% end %>
```
will generate the HTML to render an aside panel with HTML body and footer:
```html
```
PanelRowHelper
==============
To include a row of [Boostrap panels](http://getbootstrap.com/components/#panels)
in your Rails views, you can use the
[panel_row](http://rubydoc.info/github/Fullscreen/bh/master/Bh/PanelRowHelper) helper.
Here are some examples.
Basic row of panels
-------------------
```rhtml
<%= 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:
```html
Panel #1
Panel #2
Panel #3
```
Complex row of panels
---------------------
```rhtml
<%= panel_row column_class: 'col-sm-4' do %>
<%= panel title: 'User', context: :info do %>
<%= glyphicon :user %> John Smith
<% end %>
<%= panel title: 'Phone' do %>
<%= glyphicon :earphone %> 323-555-5555
<% end %>
<%= panel title: 'City' do %>
<%= glyphicon :record %> Los Angeles, CA
<% end %>
<% end %>
```
will generate the HTML to render a row of three panels with title and HTML body:
```html
User
John Smith
Phone
323-555-5555
City
Los Angeles, CA
```
ModalHelper
===========
To include [Boostrap modals](http://getbootstrap.com/javascript/#modals)
in your Rails views, you can use the
[modal](http://rubydoc.info/github/Fullscreen/bh/master/Bh/ModalHelper) helper.
Here are some examples.
Basic modal
-----------
```rhtml
<%= modal title: 'Terms of service', body: 'Do what you want!' %>
```
will generate the HTML to render a button that toggles a model when clicked:
```html
Terms of service
Do what you want!
```
Complex modal
-------------
```rhtml
<%= modal title: 'Terms of service', size: :small, button: {caption: 'Continue', size: :large, context: :info} do %>
Please accept the Terms of service.
<% 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:
```html
Terms of service
Please accept the Terms of service.
```
FormForHelper
=============
To include [Boostrap forms](http://getbootstrap.com/css/#forms)
in your Rails views, you can use the
[form_for](http://rubydoc.info/github/Fullscreen/bh/master/Bh/FormForHelper)
helper.
By default, Bh does not override the `form_for` method provided by [ActionView](http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_for).
To apply Bootstrap classes and attributes, you **must** set the `:layout` option to
* `:basic`, in order to get a [Basic form](http://getbootstrap.com/css/#forms-example)
* `:horizontal`, in order to get a [Horizontal form](http://getbootstrap.com/css/#forms-horizontal)
* `:inline`, in order to get an [Inline form](http://getbootstrap.com/css/#forms-inline)
Here is how a form with a text field and a submit button looks like with each layout:
```rhtml
<%= form_for @user, layout: :basic do |f| %>
<%= f.text_field :name %>
<%= f.submit %>
<% end %>
```
```rhtml
<%= form_for @user, layout: :horizontal do |f| %>
<%= f.text_field :name %>
<%= f.submit %>
<% end %>
```
```rhtml
<%= form_for @user, layout: :inline do |f| %>
<%= f.text_field :name %>
<%= f.submit %>
<% end %>
```
NavHelper
===========
To include [Boostrap navs](http://getbootstrap.com/components/#nav)
in your Rails views, you can use the
[nav](http://rubydoc.info/github/Fullscreen/bh/master/Bh/NavHelper) helper.
Here are some examples.
Justified tabs nav
------------------
```rhtml
<%= nav layout: :justified do %>
<%= link_to 'Home', root_path %>
<%= link_to 'Profile', profile_path %>
<% end %>
```
will generate the HTML to render a nav with two links (wrapped in the
appropriate list items, as specified by Bootstrap documentation):
```html
```
Stacked pills nav
-----------------
```rhtml
<%= nav as: :pills, layout: :stacked do %>
<%= link_to 'Home', root_path %>
<%= link_to 'Profile', profile_path %>
<% end %>
```
will generate the HTML to render a stacked *pills* nav:
```html
```
How to release new versions
===========================
If you are a manager of this project, remember to upgrade the [Bh gem](http://rubygems.org/gems/bh)
whenever a new feature is added or a bug gets fixed.
Make sure all the tests are passing on [Travis CI](https://travis-ci.org/Fullscreen/bh),
document the changes in CHANGELOG.md and README.md, bump the version, then run
rake release
Remember that the bh gem follows [Semantic Versioning](http://semver.org).
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](https://github.com/Fullscreen/bh/blob/master/TODO.md).
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! :)