Rails Bootstrap Forms is a rails form builder that makes it super easy to integrate twitter bootstrap-style forms into your rails application.
- Ruby 1.9+
- Rails 4.0+
- Twitter Bootstrap 3.0+
Add it to your Gemfile:
gem 'bootstrap_form'
Then:
bundle
Then require the CSS in your application.css
file:
/*
*= require rails_bootstrap_forms
*/
To get started, just use the bootstrap_form_for
helper. Here's an example:
<%= bootstrap_form_for(@user) do |f| %>
<%= f.email_field :email %>
<%= f.password_field :password %>
<%= f.check_box :remember_me %>
<%= f.submit %>
<% end %>
This generates the following HTML:
<form accept-charset="UTF-8" action="/users" class="new_user" id="new_user" method="post">
<div class="form-group">
<label for="user_email">Email</label>
<input class="form-control" id="user_email" name="user[email]" type="email">
</div>
<div class="form-group">
<label for="user_password">Password</label>
<input class="form-control" id="user_password" name="user[password]" type="password">
</div>
<div class="checkbox">
<label for="user_remember_me">
<input name="user[remember_me]" type="hidden" value="0">
<input id="user_remember_me" name="user[remember_me]" type="checkbox" value="1"> Remember me
</label>
</div>
<input class="btn btn-default" name="commit" type="submit" value="Log In">
</form>
In order to active nested_form support,
use bootstrap_nested_form_for
instead of bootstrap_form_for
.
If your form is not backed by a model, use the bootstrap_form_tag
. Usage of this helper is the same as bootstrap_form_for
, except no model object is passed in as the first argument. Here's an example:
<%= bootstrap_form_tag url: '/subscribe' do |f| %>
<%= f.email_field :email, value: '[email protected]' %>
<%= f.submit %>
<% end %>
This gem wraps the following Rails form helpers:
- check_box
- check_boxes_collection
- collection_select
- color_field
- date_field
- date_select
- datetime_field
- datetime_local_field
- datetime_select
- email_field
- file_field
- grouped_collection_select
- hidden_field (not wrapped, but supported)
- month_field
- number_field
- password_field
- phone_field
- radio_button
- radio_buttons_collection
- range_field
- search_field
- select
- telephone_field
- text_area
- text_field
- time_field
- time_select
- time_zone_select
- url_field
- week_field
By default, your forms will stack labels on top of controls and your controls will grow to 100% of the available width.
To use an inline-layout form, use the layout: :inline
option. To hide labels,
use the hide_label: true
option, which keeps your labels accessible to those
using screen readers.
<%= bootstrap_form_for(@user, layout: :inline) do |f| %>
<%= f.email_field :email, hide_label: true %>
<%= f.password_field :password, hide_label: true %>
<%= f.check_box :remember_me %>
<%= f.submit %>
<% end %>
To use a horizontal-layout form with labels to the left of the control, use the
layout: :horizontal
option. You should specify both label_col
and
control_col
css classes as well (they default to col-sm-2
and col-sm-10
).
In the example below, the checkbox and submit button have been wrapped in a
form_group
to keep them properly aligned.
<%= bootstrap_form_for(@user, layout: :horizontal, label_col: "col-sm-2", control_col: "col-sm-10") do |f| %>
<%= f.email_field :email %>
<%= f.password_field :password %>
<%= f.form_group do %>
<%= f.check_box :remember_me %>
<% end %>
<%= f.form_group do %>
<%= f.submit %>
<% end %>
<% end %>
The label_col
and control_col
css classes can also be changed per control:
<%= bootstrap_form_for(@user, layout: :horizontal) do |f| %>
<%= f.email_field :email %>
<%= f.text_field :age, control_col: "col-sm-3" %>
<%= f.form_group do %>
<%= f.submit %>
<% end %>
<% end %>
The layout
can be overriden per field:
<%= bootstrap_form_for(@user, layout: :horizontal) do |f| %>
<%= f.email_field :email %>
<%= f.text_field :feet, layout: :default %>
<%= f.text_field :inches, layout: :default %>
<%= f.form_group do %>
<%= f.submit %>
<% end %>
<% end %>
Use the label
option if you want to specify the field's label text:
<%= f.password_field :password_confirmation, label: "Confirm Password" %>
To hide a label, use the hide_label: true
option. This adds the sr-only
class, which keeps your labels accessible to those using screen readers.
<%= f.text_area :comment, hide_label: :true, placeholder: "Leave a comment..." %>
To add help text, use the help
option:
<%= f.password_field :password, help: "Must be at least 6 characters long" %>
The btn btn-default
css classes are automatically added to your submit
buttons.
<%= f.submit %>
You can also use the primary
helper, which adds btn btn-primary
to your
submit button (master branch only):
<%= f.primary "Optional Label" %>
You can specify your own classes like this:
<%= f.submit "Log In", class: "btn btn-success" %>
Checkboxes and radios should be placed inside of a form_group
to render
properly. The following example ensures that the entire form group will display
an error if an associated validations fails:
<%= f.form_group :skill_level, label: { text: "Skill" }, help: "Optional Help Text" do %>
<%= f.radio_button :skill_level, 0, label: "Novice", checked: true %>
<%= f.radio_button :skill_level, 1, label: "Intermediate" %>
<%= f.radio_button :skill_level, 2, label: "Advanced" %>
<% end %>
<%= f.form_group :terms do %>
<%= f.check_box :terms, label: "I agree to the Terms of Service" %>
<% end %>
You can also create a checkbox using a block:
<%= f.form_group :terms, label: { text: "Optional Label" } do %>
<%= f.check_box :terms do %>
You need to check this box to accept our terms of service and privacy policy
<% end %>
<% end %>
To display checkboxes and radios inline, pass the inline: true
option:
<%= f.form_group :skill_level, label: { text: "Skill" } do %>
<%= f.radio_button :skill_level, 0, label: "Novice", inline: true %>
<%= f.radio_button :skill_level, 1, label: "Intermediate", inline: true %>
<%= f.radio_button :skill_level, 2, label: "Advanced", inline: true %>
<% end %>
BootstrapForms also provide helpful helpers that automatically creates the
form_group
and the radio_button
s or check_box
es for you:
<%= f.radio_buttons_collection :skill_level, Skill.all, :id, :name %>
<%= f.check_boxes_collection :skills, Skill.all, :id, :name %>
Collection methods accept these options:
:label
: Customize theform_group
's label;:hide_label
: Pass true to hide theform_group
's label;:help
: Add a help span to theform_group
;- Other options will be forwarded to the
radio_button
/check_box
method;
You can pass prepend
and/or append
options to input fields:
<%= f.text_field :price, prepend: "$", append: ".00" %>
You can also prepend and append buttons. Note: The buttons must contain the
btn
class to generate the correct markup.
<%= f.text_field :search, append: link_to("Go", "#", class: "btn btn-default") %>
You can create a static control like this:
<%= f.static_control :email %>
Here's the output:
<div class="form-group">
<label class="col-sm-2 control-label" for="user_email">Email</label>
<div class="col-sm-10">
<p class="form-control-static">[email protected]</p>
</div>
</div>
You can also create a static control that isn't based on a model attribute:
<%= f.static_control nil, label: "Custom Static Control" do %>
Content Here
<% end %>
The multiple selects that the date and time helpers (date_select
,
time_select
, datetime_select
) generate are wrapped inside a
div.rails-bootstrap-forms-[date|time|datetime]-select
tag. This is because
Boostrap automatically stylizes ours controls as block
s. This wrapper fix
this defining these selects as inline-block
and a width of auto
.
When a validation error is triggered, the field will be outlined and the error will be displayed below the field. Rails normally wraps the fields in a div (field_with_errors), but this behavior is suppressed.
To display an error message wrapped in .alert
and .alert-danger
classes, you can use the alert_message
helper. This won't output anything
unless a model validation has failed.
<%= f.alert_message "Please fix the errors below." %>
You can turn off inline errors with the option inline_errors: false
. Combine
this with alert_message
to display an alert message with an error summary.
<%= bootstrap_form_for(@user, inline_errors: false) do |f| %>
<%= f.alert_message "Please fix the following errors:" %>
<% end %>
If you don't want an error summary, just send the error_summary: false
option
to alert_message
.
<%= bootstrap_form_for(@user, inline_errors: false) do |f| %>
<%= f.alert_message "Please fix the following errors", error_summary: false %>
<% end %>
To output a simple unordered list of errors, use error_summary
.
<%= bootstrap_form_for(@user, inline_errors: false) do |f| %>
<%= f.error_summary %>
<% end %>
If you want to display a custom inline error for a specific attribute not represented by a form field, use the errors_on
helper.
<%= f.errors_on :tasks %>
The error will be wrapped in a div with .alert
and .alert-danger
classes.
<div class="alert alert-danger">Tasks must be added (at least one).</div>
bootstrap_form follows standard rails conventions so it's i18n-ready. See more here: http://guides.rubyonrails.org/i18n.html#translations-for-active-record-models
http://www.codetriage.com/potenza/bootstrap_form
We love pull requests! Here's a quick guide for contributing:
-
Fork the repo.
-
Run the existing test suite:
$ cd test/dummy && bundle exec rake db:create db:migrate RAILS_ENV=test && cd ../../
$ bundle exec rake
-
Add tests for your change.
-
Add your changes and make your test(s) pass. Following the conventions you see used in the source will increase the chance that your pull request is accepted right away.
-
Update the README if necessary.
-
Add a line to the CHANGELOG for your bug fix or feature.
-
Push to your fork and submit a pull request.
https://github.com/bootstrap-ruby/rails-bootstrap-forms/graphs/contributors
MIT License. Copyright 2012-2014 Stephen Potenza (https://github.com/potenza)