bootstrap_form 1.0.0 → 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 78f6f16a42dc3bd71205a9474b10836f344c76c4
+  data.tar.gz: e5ef1c16c2c0fd3a5fc8d1a3ed484d05efcaa383
+SHA512:
+  metadata.gz: a877f20198877308837384bd79f1fe6aff438691aa9fda349c557d614ce685dbca69b8b618e39b6a4e486431d793d8a1621308d78ea7ac5daa02337704511b9d
+  data.tar.gz: 667fd4a3fc7b7aad50ceb5135590c5eae81ab1c6de25cca47af5904d199b1461b111c1a6ded6c588232db1b8416548fd14a0f150e75a83f206218fe1e9660769

data/README.md

@@ -2,90 +2,39 @@
 
 # BootstrapForm
 
-**BootstrapForm** is a form builder that makes it super easy to
-integrate Twitter Bootstrap-style forms into your Rails App.
+**BootstrapForm** 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 4.0+
-* Twitter Bootstrap 2.0+
+* Rails 3+
+* Twitter Bootstrap 3.0+
 
 ## Installation
 
 Add it to your Gemfile:
 
-### Rails 4.0+
-
 `gem 'bootstrap_form'`
 
-### Rails 3.1+
-
-`gem 'bootstrap_form', '~> 0.3.2'`
-
-
-Run the following command to install it:
+Then:
 
 `bundle`
 
-Add this line to app/assets/stylesheets/application.css.scss:
-
-```css
-/*
- *= require bootstrap_form
-*/
-```
-
-## Example
-
-Here's a quick example to get you started:
-
-```erb
-<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }, help: :block) do |f| %>
-  <%= f.alert_message "Please fix the errors below." %>
-
-  <%= f.text_field :twitter_username, prepend: '@', label: 'Twitter' %>
-  <%= f.text_field :email %>
-  <%= f.password_field :password, help: 'Must be at least 6 characters long' %>
-  <%= f.password_field :password_confirmation, label: 'Confirm Password' %>
-  <%= f.control_group :terms do %>
-    <%= f.check_box :terms, label: 'I agree to the Terms of Service' %>
-  <% end %>
-
-  <%= f.actions do %>
-    <%= f.primary 'Create My Account', disable_with: 'Saving...' %>
-  <% end %>
-<% end %>
-```
-
-Screenshot:
-
-![Example form](https://github.com/potenza/bootstrap_form/raw/master/examples/example_form.png)
-
-Screenshot with errors:
-
-![Example form with errors](https://github.com/potenza/bootstrap_form/raw/master/examples/example_form_errors.png)
-    
 ## Usage
 
-To get started, just use the **BootstrapForm** form helper:
+To get started, just use the **BootstrapForm** form helper. Here's an example:
 
 ```erb
 <%= bootstrap_form_for(@user) do |f| %>
-  ...
-<% end %>
-```
-
-To use a horizontal-style form with labels to the left of the inputs,
-add the `.form-horizontal` class:
-
-```erb
-<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }) do |f| %>
-  ...
+  <%= f.email_field :email %>
+  <%= f.password_field :password %>
+  <%= f.check_box :remember_me %>
+  <%= f.submit "Log In" %>
 <% end %>
 ```
 
-### Form Helpers
+### Supported Form Helpers
 
 This gem wraps the following Rails form helpers:
 
@@ -105,155 +54,140 @@ This gem wraps the following Rails form helpers:
 * check_box
 * radio_button
 
-You can use the helpers like you're used to:
+### Default Form Style
 
-```erb
-<%= bootstrap_form_for(@user) do |f| %>
-  <%= f.text_field :email %>
-  <%= f.password_field :password %>
-  <%= f.primary "Create My Account" %>
-<% end %>
-```
-
-This gem also wraps checkboxes and radios, which should be placed inside
-of a `control_group` to render correctly. The following example ensures
-that the entire control group will display an error if an associated 
-validations fails:
-
-```erb
-<%= f.control_group :skill_level, label: { text: 'Skill' }, help: 'This is optional' 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 %>
+By default, your forms will stack labels on top of controls and your controls
+will grow to 100% of the available width.
 
-<%= f.control_group :terms, label: { text: 'Terms' } do %>
-  <%= f.check_box :terms, label: 'I agree to the Terms of Service' %>
-<% end %>
-```
+### Inline Forms
 
-You can display checkboxes and radios `inline` like this:
+To use an inline-style form, use the `style: :inline` option. To hide labels,
+use the `hide_label: true` option, which keeps your labels accessible to those
+using screen readers.
 
 ```erb
-<%= f.control_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 %>
+<%= bootstrap_form_for(@user, style: :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" %>
 <% end %>
 ```
 
-### Labels
+### Horizontal Forms
 
-Use the `label` option if you want to specify the field's label text:
-
-```erb
-<%= f.password_field :password_confirmation, label: 'Confirm Password' %>
-```
+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`).
 
-If you don't want to render the field's label, pass `:none` to the option:
+In the example below, the checkbox and submit button have been wrapped in a
+`form_group` to keep them properly aligned.
 
 ```erb
-<%= f.text_area :comment, label: :none, placeholder: 'Leave a comment...' %>
+<%= bootstrap_form_for(@user, style: :horizontal, left: "col-sm-2", right: "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" %>
+  <% end %>
+<% end %>
 ```
 
-NOTE: To specify the label for a `control_group` you must do it like this:
+To create a static control in a horizontal form, use the following markup:
 
 ```erb
-<%= f.control_group :terms, label: { text: 'Terms' } do %>
-  <%= f.check_box :terms, label: 'I agree to the Terms of Service' %>
+<%= f.form_group :nil, label: { text: "Foo" } do %>
+  <p class="form-control-static">
+    Bar
+  </p>
 <% end %>
 ```
 
-### Help text
+### Labels
 
-To add help text, use the `help` option, which will place it
-to the right of the field:
+Use the `label` option if you want to specify the field's label text:
 
 ```erb
-<%= f.password_field :password, help: 'Must be at least 6 characters long' %>
+<%= f.password_field :password_confirmation, label: "Confirm Password" %>
 ```
 
-To place help text underneath a field, pass the option `help:
-:block` to the `bootstrap_form_for` helper:
+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, help: :block) do |f| %>
-  <%= f.password_field :password, help: 'Must be at least 6 characters long' %>
-<% end %>
+<%= f.text_area :comment, hide_label: :true, placeholder: "Leave a comment..." %>
 ```
 
-### Prepending inputs
+### Help Text
 
-You can prepend an input file with the `prepend` option:
+To add help text, use the `help` option:
 
 ```erb
-<%= f.text_field :twitter_username, prepend: '@' %>
+<%= f.password_field :password, help: "Must be at least 6 characters long" %>
 ```
 
-### Appending inputs
+### Submit Buttons
 
-You can append an input file with the `append` option:
+The `btn btn-default` css classes are automatically added to your submit
+buttons.
 
 ```erb
-<%= f.text_field :amount, append: '.00' %>
+<%= f.submit "Log In" %>
 ```
 
-### Submit buttons
-
-This gem provides a few different options for submit buttons.
-
-Here's a simple `primary` button (this applies the `.btn` and `.btn-primary` classes):
+You can specify your own classes like this:
 
 ```erb
-<%= f.primary "Create My Account" %>
+<%= f.submit "Log In", class: "btn btn-primary" %>
 ```
 
-Here's a `secondary` submit button (applies just the `.btn` class):
+### Checkboxes and Radios
 
-```erb
-<%= f.secondary "Create My Account" %>
-```
-
-You can use the `actions` helper, which wraps your submit button in a
-`.form-actions` class.
+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:
 
 ```erb
-<%= f.actions do %>
-  <%= f.primary 'Create My Account' %>
+<%= 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 %>
 ```
 
-And if you don't want to use the `actions` helper, here's how you might 
-style a `primary` button with horizontal-style forms:
+You can also create a checkbox using a block:
 
 ```erb
-<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }) do |f| %>
-  <%= f.control_group do %>
-    <%= f.primary "Create My Account" %>
+<%= 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 %>
 ```
 
-### Custom Control Groups
-
-Sometimes you need to wrap an element in Bootstrap-style markup.
-This is mostly needed to align submit buttons when using horizontal-style
-forms (also shown above):
+To display checkboxes and radios inline, pass the `inline: true` option:
 
 ```erb
-<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }) do |f| %>
-  <%= f.control_group do %>
-    <%= f.primary "Create My Account" %>
-  <% end %>
+<%= 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 %>
 ```
 
-To specify a label that isn't linked to an element you can do this:
+### Prepending and Appending Inputs
+
+Pass the `prepend` and/or `append` options to the input field:
 
 ```erb
-<%= f.control_group :nil, label: { text: 'Foo' } do %>
-  <span>Bar</span>
-<% end %>
+<%= f.text_field :price, prepend: "$", append: ".00" %>
 ```
 
 ### Validation Errors
@@ -262,9 +196,9 @@ When a validation error is triggered, the field will be outlined and the
 error will be displayed next to the field (or below it if you're using
 block-style help text). Rails normally wraps fields in a div
 (field_with_errors), but this behavior is suppressed when
-`bootstrap_form_for` is called.
+`bootstrap_form_for` is used.
 
-To display an error message wrapped in `.alert` and `.alert-error`
+To display an error message wrapped in `.alert` and `.alert-danger`
 classes, you can use the `alert_message` helper:
 
 ```erb

data/lib/bootstrap_form.rb

@@ -1,6 +1,5 @@
 require 'bootstrap_form/form_builder'
 require 'bootstrap_form/helper'
-require 'bootstrap_form/engine'
 
 module BootstrapForm
 end

data/lib/bootstrap_form/form_builder.rb

@@ -1,5 +1,7 @@
 module BootstrapForm
   class FormBuilder < ActionView::Helpers::FormBuilder
+    attr_reader :style, :left_class, :right_class, :has_error
+
     FORM_HELPERS = %w{text_field password_field text_area file_field
                      number_field email_field telephone_field phone_field url_field
                      select collection_select date_select time_select datetime_select}
@@ -8,9 +10,9 @@ module BootstrapForm
     delegate :capture, to: :@template
 
     def initialize(object_name, object, template, options, proc=nil)
-      help = options.fetch(:help, nil)
-      @help_class = help.eql?(:block) ? 'help-block' : 'help-inline'
-
+      @style = options[:style]
+      @left_class = (options[:left] || default_left_class) + " control-label"
+      @right_class = options[:right] || default_right_class
       super
     end
 
@@ -19,39 +21,31 @@ module BootstrapForm
         options = args.extract_options!.symbolize_keys!
 
         label = options.delete(:label)
-        help  = options.delete(:help)
-
-        control_group(name, label: { text: label }, help: help) do
+        label_class = hide_class if options.delete(:hide_label)
+        help = options.delete(:help)
 
+        form_group(name, label: { text: label, class: label_class }, help: help) do
+          options[:class] = "form-control #{options[:class]}".rstrip
           args << options.except(:prepend, :append)
-          element = super(name, *args)
-
-          if prepend = options.delete(:prepend)
-            element = content_tag(:div, class: 'input-prepend') do
-              content_tag(:span, prepend, class: 'add-on') + element
-            end
-          end
-
-          if append = options.delete(:append)
-            element = content_tag(:div, class: 'input-append') do
-              element + content_tag(:span, append, class: 'add-on')
-            end
-          end
-
-          element
+          input = super(name, *args)
+          prepend_and_append_input(input, options[:prepend], options[:append])
         end
       end
     end
 
-    def check_box(name, options = {}, checked_value = "1", unchecked_value = "0")
+    def check_box(name, options = {}, checked_value = '1', unchecked_value = '0')
       options = options.symbolize_keys!
 
-      html = super(name, options.except(:label, :help, :inline), checked_value, unchecked_value) 
-      html += ' ' + (options[:label] || name.to_s.humanize)
+      html = super(name, options.except(:label, :help, :inline), checked_value, unchecked_value)
+      html << ' ' + (options[:label] || name.to_s.humanize)
 
-      css = 'checkbox'
-      css << ' inline' if options[:inline]
-      label(name, html, class: css)
+      if options[:inline]
+        label(name, html, class: "checkbox-inline")
+      else
+        content_tag(:div, class: "checkbox") do
+          label(name, html)
+        end
+      end
     end
 
     def radio_button(name, value, *args)
@@ -61,67 +55,79 @@ module BootstrapForm
       html = super(name, value, *args) + ' ' + options[:label]
 
       css = 'radio'
-      css << ' inline' if options[:inline]
+      css << '-inline' if options[:inline]
       label("#{name}_#{value}", html, class: css)
     end
 
-    def control_group(name = nil, options = {}, &block)
-      errors_has_name = object.respond_to?(:errors) && !(name.nil? || object.errors[name].empty?)
+    def form_group(name = nil, options = {}, &block)
+      options[:class] = 'form-group'
+      options[:class] << ' has-error' if has_error?(name)
 
-      options[:class] ||= 'control-group'
-      options[:class] << ' error' if errors_has_name
+      html = capture(&block)
+      html << generate_help(name, options[:help])
+      html = content_tag(:div, html, class: right_class) if horizontal?
 
-      label = options.delete(:label)
-      _help = options.delete(:help)
-
-      content_tag(:div, options) do
-        html = ''
+      content_tag(:div, options.except(:label, :help)) do
+        "#{generate_label(name, options[:label])}#{html}".html_safe
+      end
+    end
 
-        if label && label[:text] != :none
-          label[:class] ||= 'control-label'
-          label[:for] ||= '' if name.nil?
+    def submit(name, options = {})
+      options.merge! class: 'btn btn-default' unless options.has_key? :class
+      super name, options
+    end
 
-          html << label(name, label[:text], label.except(:text))
-        end
+    def alert_message(title, *args)
+      options = args.extract_options!
+      css = options[:class] || 'alert alert-danger'
 
-        html << content_tag(:div, class: 'controls') do
-          controls = capture(&block)
+      if object.respond_to?(:errors) && object.errors.full_messages.any?
+        content_tag :div, title, class: css
+      end
+    end
 
-          help = errors_has_name ? object.errors[name].join(', ') : _help
-          controls << content_tag(:span, help, class: @help_class) if help
+    private
 
-          controls.html_safe
-        end
+    def horizontal?
+      style == :horizontal
+    end
 
-        html.html_safe
-      end
+    def default_left_class
+      "col-sm-2"
     end
 
-    def actions(&block)
-      content_tag :div, class: "form-actions" do
-        capture(&block)
-      end
+    def default_right_class
+      "col-sm-10"
     end
 
-    def primary(name, options = {})
-      options.merge! class: 'btn btn-primary'
-      submit name, options
+    def hide_class
+      "sr-only" # still accessible for screen readers
     end
 
-    def secondary(name, options = {})
-      options.merge! class: 'btn'
-      submit name, options
+    def has_error?(name)
+      object.respond_to?(:errors) && !(name.nil? || object.errors[name].empty?)
     end
 
-    def alert_message(title, *args)
-      options = args.extract_options!
-      css = options[:class] || "alert alert-error"
+    def prepend_and_append_input(input, prepend, append)
+      input = content_tag(:span, prepend, class: 'input-group-addon') + input if prepend
+      input << content_tag(:span, append, class: 'input-group-addon') if append
+      input = content_tag(:div, input, class: 'input-group') if prepend || append
+      input
+    end
 
-      if object.respond_to?(:errors) && object.errors.full_messages.any?
-        content_tag :div, class: css do
-          title
-        end
+    def generate_label(name, options)
+      if options
+        options[:class] = "#{options[:class]} #{left_class}".lstrip if horizontal?
+        label(name, options[:text], options.except(:text))
+      elsif horizontal?
+        # no label. create an empty one to keep proper form alignment.
+        content_tag(:label, "", class: left_class)
       end
     end
+
+    def generate_help(name, help_text)
+      help_text = object.errors[name].join(', ') if has_error?(name)
+      content_tag(:span, help_text, class: 'help-block') if help_text
+    end
   end
 end