bootstrap_form 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dedc77d50059c56a37534d9f6d75389a738af46f
-  data.tar.gz: 9e1ee86b160a69cb40b1303f526106ba137b82b8
+  metadata.gz: 8742255adf9a08c30983097065574da44048f88e
+  data.tar.gz: 3b301bdd5e3c144a89151bb8b8f7eafb7a3a31e3
 SHA512:
-  metadata.gz: ea9bc3f9d89c3bc5a2bd8275abe8deea23f867998557eb24105b57805a696559e03bdea89c410152b443a0713e0d16d7411b24ee102cca8c795bfaa935c7b22a
-  data.tar.gz: 160591536c799d724da6d4f9afcb12ff0f1e89506084f77a6da702fd1f5ee615342b00bded0bfe83b82a6d77471c015b41ecbe29bf21218130db21ff9674a520
+  metadata.gz: 22c55ab50ba7ca0e6e7e9c5cd836d2461817d7a97036d87d13d52aa1cb62148d5e163fd1c68ca88806b76dd927cd30e1528dcbad8fbca8e502b9de1306875870
+  data.tar.gz: 2400158a438d1aed212116ccc6dc4c983b3ba0f8e5e02d0125e9971d747fafda44a38af10e2d6a9284eb4cb78bdab6d25330bccb62381c5e52820d1625a3f193

data/README.md

@@ -22,9 +22,13 @@ Then:
 
 `bundle`
 
-Then require the CSS on your `application.css` file:
+Then require the CSS in your `application.css` file:
 
-`//= require rails_bootstrap_forms`
+```css
+/*
+ *= require rails_bootstrap_forms
+ */
+```
 
 ## Usage
 
@@ -35,7 +39,7 @@ To get started, just use the `bootstrap_form_for` helper. Here's an example:
   <%= f.email_field :email %>
   <%= f.password_field :password %>
   <%= f.check_box :remember_me %>
-  <%= f.submit %>
+  <%= f.submit "Log In" %>
 <% end %>
 ```
 
@@ -64,7 +68,7 @@ This generates the following HTML:
 ### Nested Forms
 
 In order to active [nested_form](https://github.com/ryanb/nested_form) support,
-use `boostrap_nested_form_for` instead of `bootstrap_form_for`.
+use `bootstrap_nested_form_for` instead of `bootstrap_form_for`.
 
 ### bootstrap_form_tag
 
@@ -72,17 +76,17 @@ If your form is not backed by a model, use the `bootstrap_form_tag`. Usage of th
 
 ```erb
 <%= bootstrap_form_tag url: '/subscribe' do |f| %>
-  <%= f.email_field :email %>
+  <%= f.email_field :email, value: 'name@example.com' %>
   <%= f.submit %>
 <% end %>
 ```
 
-### Supported Form Helpers
+## Form Helpers
 
 This gem wraps the following Rails form helpers:
 
 * check_box
-* check_boxes_collection
+* collection_check_boxes
 * collection_select
 * color_field
 * date_field
@@ -99,7 +103,7 @@ This gem wraps the following Rails form helpers:
 * password_field
 * phone_field
 * radio_button
-* radio_buttons_collection
+* collection_radio_buttons
 * range_field
 * search_field
 * select
@@ -108,121 +112,109 @@ This gem wraps the following Rails form helpers:
 * text_field
 * time_field
 * time_select
+* time_zone_select
 * url_field
 * week_field
+ 
+These helpers accept the same options as the standard Rails form helpers, with
+a few extra options:
 
-### Default Form Style
+### Labels
 
-By default, your forms will stack labels on top of controls and your controls
-will grow to 100% of the available width.
+Use the `label` option if you want to specify the field's label text:
 
-### Inline Forms
+```erb
+<%= f.password_field :password_confirmation, label: "Confirm Password" %>
+```
 
-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.
+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.
 
 ```erb
-<%= 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 %>
+<%= f.text_area :comment, hide_label: :true, placeholder: "Leave a comment..." %>
 ```
 
-### Horizontal Forms
-
-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`).
+### Help Text
 
-In the example below, the checkbox and submit button have been wrapped in a
-`form_group` to keep them properly aligned.
+To add help text, use the `help` option:
 
 ```erb
-<%= 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 %>
+<%= f.password_field :password, help: "Must be at least 6 characters long" %>
 ```
 
-The `label_col` and `control_col` css classes can also be changed per control:
+This gem is also aware of help messages in locale translation files (i18n):
 
-```erb
-<%= 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 %>
+```yml
+en:
+  activerecord:
+    help:
+      user:
+        password: "A good password should be at least six characters long"
 ```
 
-### Custom Field Layout
+You can override help translations for a particular field by passing the `help`
+option or turn them off completely by passing `help: false`.
 
-The `layout` can be overriden per field:
+### Icons
+
+To add an icon to a field, use the `icon` option and pass the icon name
+*without* the 'glyphicon' prefix:
 
 ```erb
-<%= bootstrap_form_for(@user, layout: :horizontal) do |f| %>
-  <%= f.email_field :email %>
-  <%= f.text_field :feet, layout: :inline %>
-  <%= f.text_field :inches, layout: :inline %>
-  <%= f.form_group do %>
-    <%= f.submit %>
-  <% end %>
-<% end %>
+<%= f.text_field :login, icon: "user" %>
 ```
 
-### Labels
-
-Use the `label` option if you want to specify the field's label text:
+This automatically adds the `has-feedback` class to the `form-group`:
 
-```erb
-<%= f.password_field :password_confirmation, label: "Confirm Password" %>
+```html
+<div class="form-group has-feedback">
+  <label class="control-label" for="user_login">Login</label>
+  <input class="form-control" id="user_login" name="user[login]" type="text" />
+  <span class="glyphicon glyphicon-user form-control-feedback"></span>
+</div>
 ```
 
-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.
+### Prepending and Appending Inputs
+
+You can pass `prepend` and/or `append` options to input fields:
 
 ```erb
-<%= f.text_area :comment, hide_label: :true, placeholder: "Leave a comment..." %>
+<%= f.text_field :price, prepend: "$", append: ".00" %>
 ```
 
-### Help Text
-
-To add help text, use the `help` option:
+You can also prepend and append buttons. Note: The buttons must contain the
+`btn` class to generate the correct markup.
 
 ```erb
-<%= f.password_field :password, help: "Must be at least 6 characters long" %>
+<%= f.text_field :search, append: link_to("Go", "#", class: "btn btn-default") %>
 ```
 
-### Submit Buttons
+### Additional Form Group Attributes
 
-The `btn btn-default` css classes are automatically added to your submit
-buttons.
+If you want to add an additional css class or any other attribute to the form group div, you can use
+the `wrapper: { class: 'additional-class', data: { foo: 'bar' } }` option.
 
 ```erb
-<%= f.submit %>
+<%= f.text_field :name, wrapper: { class: 'has-warning', data: { foo: 'bar' } } %>
 ```
 
-You can also use the `primary` helper, which adds `btn btn-primary` to your
-submit button **(master branch only)**:
+Which produces the following output:
 
 ```erb
-<%= f.primary "Optional Label" %>
+<div class="form-group has-warning" data-foo="bar">
+  <label class="control-label" for="user_name">Id</label>
+  <input class="form-control" id="user_name" name="user[name]" type="text">
+</div>
 ```
 
-You can specify your own classes like this:
+You still can use `wrapper_class` option to set only a css class. This is just a short form of `wrapper: { class: 'additional-class' }`.
+
+### Selects
+
+Our select helper accepts the same arguments as the [default Rails helper](http://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-select). Here's an example of how you pass both options and html_options hashes:
 
 ```erb
-<%= f.submit "Log In", class: "btn btn-success" %>
+<%= f.select :product, [[1, "Apple"], [2, "Grape"]], { label: "Choose your favorite fruit:" }, { class: "selectpicker" } %>
 ```
 
 ### Checkboxes and Radios
@@ -265,29 +257,21 @@ To display checkboxes and radios inline, pass the `inline: true` option:
 
 #### Collections
 
-BootstrapForms also provide helpful helpers that automatically creates the
+BootstrapForms also provideshelpers that automatically creates the
 `form_group` and the `radio_button`s or `check_box`es for you:
 
 ```erb
-<%= f.radio_buttons_collection :skill_level, Skill.all, :id, :name %>
-<%= f.check_boxes_collection :skills, Skill.all, :id, :name %>
+<%= f.collection_radio_buttons :skill_level, Skill.all, :id, :name %>
+<%= f.collection_check_boxes :skills, Skill.all, :id, :name %>
 ```
 
 Collection methods accept these options:
-* `:label`: Customize the `form_group`'s label;
-* `:hide_label`: Pass true to hide the `form_group`'s label;
-* `:help`: Add a help span to the `form_group`;
-* Other options will be forwarded to the `radio_button`/`check_box` method;
+* `:label`: Customize the `form_group`'s label
+* `:hide_label`: Pass true to hide the `form_group`'s label
+* `:help`: Add a help span to the `form_group`
+* Other options will be forwarded to the `radio_button`/`check_box` method
 
-### Prepending and Appending Inputs
-
-You can pass `prepend` and/or `append` options to input fields:
-
-```erb
-<%= f.text_field :price, prepend: "$", append: ".00" %>
-```
-
-### Static Controls **(master branch only)**
+### Static Controls
 
 You can create a static control like this:
 
@@ -309,12 +293,12 @@ Here's the output:
 You can also create a static control that isn't based on a model attribute:
 
 ```erb
-<%= f.static_control nil, label: "Custom Static Control" do %>
+<%= f.static_control label: "Custom Static Control" do %>
   Content Here
 <% end %>
 ```
 
-### Date helpers
+### Date Helpers
 
 The multiple selects that the date and time helpers (`date_select`,
 `time_select`, `datetime_select`) generate are wrapped inside a
@@ -322,60 +306,199 @@ The multiple selects that the date and time helpers (`date_select`,
 Boostrap automatically stylizes ours controls as `block`s. This wrapper fix
 this defining these selects as `inline-block` and a width of `auto`.
 
-### Validation Errors
+### Submit Buttons
 
-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.
+The `btn btn-default` css classes are automatically added to your submit
+buttons.
 
-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.
+```erb
+<%= f.submit %>
+```
+
+You can also use the `primary` helper, which adds `btn btn-primary` to your
+submit button **(master branch only)**:
 
 ```erb
-<%= f.alert_message "Please fix the errors below." %>
+<%= f.primary "Optional Label" %>
 ```
 
-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.
+You can specify your own classes like this:
 
 ```erb
-<%= bootstrap_form_for(@user, inline_errors: false) do |f| %>
-  <%= f.alert_message "Please fix the following errors:" %>
+<%= f.submit "Log In", class: "btn btn-success" %>
+```
+
+### Accessing Rails Form Helpers
+
+If you want to use the original Rails form helpers for a particular field,
+append `_without_bootstrap` to the helper:
+
+```erb
+<%= f.text_field_without_bootstrap :email %>
+```
+
+## Form Styles
+
+By default, your forms will stack labels on top of controls and your controls
+will grow to 100% of the available width.
+
+### Inline Forms
+
+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.
+
+```erb
+<%= 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 %>
 ```
 
-If you don't want an error summary, just send the `error_summary: false` option
-to `alert_message`.
+### Horizontal Forms
+
+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.
 
 ```erb
-<%= bootstrap_form_for(@user, inline_errors: false) do |f| %>
-  <%= f.alert_message "Please fix the following errors", error_summary: false %>
+<%= 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 %>
 ```
 
-To output a simple unordered list of errors, use `error_summary`.
+The `label_col` and `control_col` css classes can also be changed per control:
+
+```erb
+<%= 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 %>
+```
+
+### Custom Field Layout
+
+The `layout` can be overriden per field:
+
+```erb
+<%= 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 %>
+```
+
+## Validation & Errors
+
+### Inline Errors
+
+By default, fields that have validation errors will outlined in red 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. Here's an example:
+
+```html
+<div class="form-group has-error">
+  <label class="control-label" for="user_email">Email</label>
+  <input class="form-control" id="user_email" name="user[email]" type="email" value="">
+  <span class="help-block">can't be blank</span>
+</div>
+```
+
+You can turn off inline errors for the entire form like this:
 
 ```erb
 <%= 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.
+### Alert Messages
+
+To display an error message with an error summary, you can use the
+`alert_message` helper. This won't output anything unless a model validation
+has failed.
+
+```erb
+<%= f.alert_message "Please fix the errors below." %>
+```
+
+Which outputs:
+
+```html
+<div class="alert alert-danger">
+  <p>Please fix the errors below.</p>
+  <ul class="rails-bootstrap-forms-error-summary">
+    <li>Email can't be blank</li>
+  </ul>
+</div>
+```
+
+You can turn off the error summary like this:
+
+```erb
+<%= f.alert_message "Please fix the errors below.", error_summary: false %>
+```
+
+To output a simple unordered list of errors, use the `error_summary` helper.
+
+```erb
+<%= f.error_summary %>
+```
+
+Which outputs:
+
+```html
+<ul class="rails-bootstrap-forms-error-summary">
+  <li>Email can't be blank</li>
+</ul>
+```
+
+### Errors On
+
+If you want to display a custom inline error for a specific attribute not
+represented by a form field, use the `errors_on` helper.
 
 ```erb
 <%= f.errors_on :tasks %>
 ```
 
-The error will be wrapped in a div with `.alert` and `.alert-danger`
-classes.
+Which outputs:
+
+```html
+<div class="alert alert-danger">Tasks can't be blank.</div>
+```
+
+You can hide the attribute name like this:
+
+```erb
+<%= f.errors_on :tasks, hide_attribute_name: true %>
+```
+
+Which outputs:
 
 ```html
-<div class="alert alert-danger">Tasks must be added (at least one).</div>
+<div class="alert alert-danger">can't be blank.</div>
 ```
 
-### Internationalization
+## Internationalization
 
 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