bootstrap_form 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ca2f49082f337eb1dc61b216ffc2b0c29f2f432b
-  data.tar.gz: 2e33b7c8f7af22cc53df4a8638bee6ade8a51fe8
+  metadata.gz: 311b2d08aa1d52ca0c3dc819c1f061916aa59708
+  data.tar.gz: 05a500f081ca6e0cfe8f452120d50f564ef0c353
 SHA512:
-  metadata.gz: a84f353aba50af9ed2f66008b63d3ce286d441fe110fa0099c6e5e0b974b45af81b946971d823efdca1c69191c9cc7b52a60d9fec9429e25ab7cfcd7a3e9341d
-  data.tar.gz: c52e0ee82e6c94ca1f585990635723761c4d3e2a6e027af1701b108bdc89bfc69ed20754bcffe65af41dd7fe8d48117a00755785efd034a7d8612f51c5ad4350
+  metadata.gz: d2cafdbe6823b47db0a1ee71ad330d9086a1c37d5eeda88a3e4c6764b0c25d948886ab76f25ec7fb5b82f3927e9a4a0bc44a610cfd37e41ea9209491f015ca7a
+  data.tar.gz: 8cfc0f84c79178a5f9da7706d0a93397544213d8e69a7096aa9dffeefe154e472514a90644091907d7cf4c9a6749492cc9fdd932c273d69589dbbc04cd67eda5

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2012 YOURNAME
+Copyright 2012-2014 Stephen Potenza <potenza@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,14 +1,14 @@
-[![Build Status](https://travis-ci.org/potenza/bootstrap_form.png)](https://travis-ci.org/potenza/bootstrap_form) [![Code Climate](https://codeclimate.com/github/potenza/bootstrap_form.png)](https://codeclimate.com/github/potenza/bootstrap_form)
+[![Build Status](https://travis-ci.org/bootstrap-ruby/rails-bootstrap-forms.png)](https://travis-ci.org/bootstrap-ruby/rails-bootstrap-forms) [![Code Climate](https://codeclimate.com/github/bootstrap-ruby/rails-bootstrap-forms.png)](https://codeclimate.com/github/bootstrap-ruby/rails-bootstrap-forms)
 
-# BootstrapForm
+# Rails Bootstrap Forms
 
-**BootstrapForm** is a rails form builder that makes it super easy to integrate
+**Rails Bootstrap Forms** is a rails form builder that makes it super easy to integrate
 twitter bootstrap-style forms into your rails application.
 
 ## Requirements
 
 * Ruby 1.9+
-* Rails 3+
+* Rails 4.0+
 * Twitter Bootstrap 3.0+
 
 ## Installation
@@ -21,16 +21,20 @@ Then:
 
 `bundle`
 
+Then require the CSS on your `application.css` file:
+
+`//= require rails_bootstrap_forms`
+
 ## Usage
 
-To get started, just use the **BootstrapForm** form helper. Here's an example:
+To get started, just use the `bootstrap_form_for` helper. Here's an example:
 
 ```erb
 <%= bootstrap_form_for(@user) do |f| %>
   <%= f.email_field :email %>
   <%= f.password_field :password %>
   <%= f.check_box :remember_me %>
-  <%= f.submit "Log In" %>
+  <%= f.submit %>
 <% end %>
 ```
 
@@ -56,25 +60,50 @@ This generates the following HTML:
 </form>
 ```
 
+### bootstrap_form_tag
+
+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:
+
+```erb
+<%= bootstrap_form_tag url: '/subscribe' do |f| %>
+  <%= f.email_field :email %>
+  <%= f.submit %>
+<% end %>
+```
+
 ### Supported Form Helpers
 
 This gem wraps the following Rails form helpers:
 
-* text_field
-* password_field
-* text_area
-* file_field
-* number_field
-* email_field
-* telephone_field / phone_field
-* url_field
-* select
+* check_box
+* check_boxes_collection
 * collection_select
+* color_field
+* date_field
 * date_select
-* time_select
+* datetime_field
+* datetime_local_field
 * datetime_select
-* check_box
+* 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
+* url_field
+* week_field
 
 ### Default Form Style
 
@@ -83,48 +112,65 @@ will grow to 100% of the available width.
 
 ### Inline Forms
 
-To use an inline-style form, use the `style: :inline` option. To hide labels,
+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, style: :inline) do |f| %>
+<%= 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 "Log In" %>
+  <%= f.submit %>
 <% end %>
 ```
 
 ### Horizontal Forms
 
-To use a horizontal-style form with labels to the left of the inputs, use the
-`style: :horizontal` option. You should specify both `left` and `right` css
-classes as well (they default to `col-sm-2` and `col-sm-10`).
+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, style: :horizontal, left: "col-sm-2", right: "col-sm-10") do |f| %>
+<%= 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 "Log In" %>
+    <%= f.submit %>
   <% end %>
 <% end %>
 ```
 
-To create a static control in a horizontal form, use the following markup:
+The `label_col` and `control_col` css classes can also be changed per control:
 
 ```erb
-<%= f.form_group :nil, label: { text: "Foo" } do %>
-  <p class="form-control-static">
-    Bar
-  </p>
+<%= 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: :inline %>
+  <%= f.text_field :inches, layout: :inline %>
+  <%= f.form_group do %>
+    <%= f.submit %>
+  <% end %>
 <% end %>
 ```
 
@@ -157,13 +203,20 @@ The `btn btn-default` css classes are automatically added to your submit
 buttons.
 
 ```erb
-<%= f.submit "Log In" %>
+<%= f.submit %>
+```
+
+You can also use the `primary` helper, which adds `btn btn-primary` to your
+submit button **(master branch only)**:
+
+```erb
+<%= f.primary "Optional Label" %>
 ```
 
 You can specify your own classes like this:
 
 ```erb
-<%= f.submit "Log In", class: "btn btn-primary" %>
+<%= f.submit "Log In", class: "btn btn-success" %>
 ```
 
 ### Checkboxes and Radios
@@ -204,6 +257,22 @@ To display checkboxes and radios inline, pass the `inline: true` option:
 <% end %>
 ```
 
+#### Collections
+
+BootstrapForms also provide helpful helpers 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 %>
+```
+
+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;
+
 ### Prepending and Appending Inputs
 
 You can pass `prepend` and/or `append` options to input fields:
@@ -212,6 +281,41 @@ You can pass `prepend` and/or `append` options to input fields:
 <%= f.text_field :price, prepend: "$", append: ".00" %>
 ```
 
+### Static Controls **(master branch only)**
+
+You can create a static control like this:
+
+```erb
+<%= f.static_control :email %>
+```
+
+Here's the output:
+
+```html
+<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">test@email.com</p>
+  </div>
+</div>
+```
+
+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 %>
+  Content Here
+<% end %>
+```
+
+### Date helpers
+
+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`.
+
 ### Validation Errors
 
 When a validation error is triggered, the field will be outlined and the error
@@ -219,20 +323,88 @@ 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:
+classes, 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." %>
 ```
 
+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.
+
+```erb
+<%= 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`.
+
+```erb
+<%= 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`.
+
+```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.
+
+```erb
+<%= f.errors_on :tasks %>
+```
+
+The error will be wrapped in a div with `.alert` and `.alert-danger`
+classes.
+
+```html
+<div class="alert alert-danger">Tasks must be added (at least one).</div>
+```
+
+### 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
+
 ## Code Triage page
 
 http://www.codetriage.com/potenza/bootstrap_form
 
+## Contributing
+
+We love pull requests! Here's a quick guide for contributing:
+
+1. Fork the repo.
+
+2. Run the existing test suite:
+
+  `$ cd test/dummy && bundle exec rake db:create db:migrate RAILS_ENV=test && cd ../../`
+  `$ bundle exec rake`
+
+3. Add tests for your change.
+
+4. 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.
+
+5. Update the README if necessary.
+
+6. Add a line to the CHANGELOG for your bug fix or feature.
+
+7. Push to your fork and submit a pull request.
+
 ## Contributors
 
-https://github.com/potenza/bootstrap_form/graphs/contributors
+https://github.com/bootstrap-ruby/rails-bootstrap-forms/graphs/contributors
 
 ## License
 
-MIT License. Copyright 2012-2013 Stephen Potenza (https://github.com/potenza)
+MIT License. Copyright 2012-2014 Stephen Potenza (https://github.com/potenza)

data/app/assets/stylesheets/rails_bootstrap_forms.css

@@ -0,0 +1,10 @@
+.rails-bootstrap-forms-date-select select,
+.rails-bootstrap-forms-time-select select,
+.rails-bootstrap-forms-datetime-select select {
+  display: inline-block;
+  width: auto;
+}
+
+.rails-bootstrap-forms-error-summary {
+  margin-top: 10px;
+}

data/lib/bootstrap_form.rb

@@ -1,7 +1,12 @@
+require 'bootstrap_form/bootstrap_helpers'
 require 'bootstrap_form/form_builder'
 require 'bootstrap_form/helper'
 
 module BootstrapForm
+  module Rails
+    class Engine < ::Rails::Engine
+    end
+  end
 end
 
 ActionView::Base.send :include, BootstrapForm::Helper

data/lib/bootstrap_form/bootstrap_helpers.rb

@@ -0,0 +1,66 @@
+module BootstrapForm
+  module BootstrapHelpers
+    def submit(name = nil, options = {})
+      options.merge! class: "btn btn-default" unless options.has_key? :class
+      super(name, options)
+    end
+
+    def primary(name = nil, options = {})
+      options.merge! class: "btn btn-primary"
+      submit(name, options)
+    end
+
+    def alert_message(title, options = {})
+      css = options[:class] || "alert alert-danger"
+
+      if object.respond_to?(:errors) && object.errors.full_messages.any?
+        content_tag :div, class: css do
+          concat content_tag :p, title
+          concat error_summary unless inline_errors || options[:error_summary] == false
+        end
+      end
+    end
+
+    def error_summary
+      content_tag :ul, class: "rails-bootstrap-forms-error-summary" do
+        object.errors.full_messages.each do |error|
+          concat content_tag(:li, error)
+        end
+      end
+    end
+
+    def errors_on(name)
+      if has_error?(name)
+        content_tag :div, class: "alert alert-danger" do
+          object.errors.full_messages_for(name).join(", ")
+        end
+      end
+    end
+
+    def static_control(name, options = {}, &block)
+      html = if block_given?
+        capture(&block)
+      else
+        object.send(name)
+      end
+
+      form_group_builder(name, options) do
+        content_tag(:p, html, class: static_class)
+      end
+    end
+
+    def prepend_and_append_input(options, &block)
+      options = options.extract!(:prepend, :append)
+      input = capture(&block)
+
+      input = content_tag(:span, options[:prepend], class: "input-group-addon") + input if options[:prepend]
+      input << content_tag(:span, options[:append], class: "input-group-addon") if options[:append]
+      input = content_tag(:div, input, class: "input-group") if options[:prepend] || options[:append]
+      input
+    end
+
+    def static_class
+      "form-control-static"
+    end
+  end
+end