bootstrap_form 0.2.4 → 0.3.0

data/README.md

@@ -1,45 +1,84 @@
-bootstrap_form
-==============
+# BootstrapForm
 
-bootstrap_form is a rails form builder that makes it super easy to create beautiful-looking forms using Twitter Bootstrap 2.0
+**BootstrapForm** is a form builder that makes it super easy to
+integrate Twitter Bootstrap-style forms into your Rails App.
 
-
-Requirements
-------------
+## Requirements
 
 * Ruby 1.9+
 * Rails 3.1+
 * Twitter Bootstrap 2.0+
 
+## Installation
+
+Add it to your Gemfile:
+
+`gem 'bootstrap_form'`
+
+Run the following command to install it:
+
+`bundle`
+
+Add this line to app/assets/stylesheets/application.css.scss:
+
+```css
+/*
+ *= require bootstrap_form
+*/
+```
+
+## Example
 
-Installation
-------------
+Here's a quick example to get you started:
 
-Add the gem to your Gemfile
+```erb
+<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }, help: :block) do |f| %>
+  <%= f.alert_message "Please fix the errors below." %>
 
-    gem 'bootstrap_form'
+  <%= 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 %>
 
-Install the gem
+  <%= f.actions do %>
+    <%= f.primary 'Create My Account', disable_with: 'Saving...' %>
+  <% end %>
+<% end %>
+```
 
-    bundle
+Screenshot:
 
-Add bootstrap_form to your application.css file
+![Example form](https://github.com/potenza/bootstrap_form/raw/master/examples/example_form.png)
 
-    /*
-     *= require bootstrap_form
-    */
+Screenshot with errors:
+
+![Example form with errors](https://github.com/potenza/bootstrap_form/raw/master/examples/example_form_errors.png)
     
-This brings in a couple of minor css classes that help format helper and
-error messages.
+## Usage
+
+To get started, just use the **BootstrapForm** form helper:
+
+```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:
 
-Usage
------
+```erb
+<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }) do |f| %>
+  ...
+<% end %>
+```
 
-    <%= bootstrap_form_for(@user) do |f| %>
-      ...
-    <% end %>
+### Form Helpers
 
-This plugin provides the following form helpers:
+This gem wraps the following Rails form helpers:
 
 * text_field
 * password_field
@@ -47,7 +86,7 @@ This plugin provides the following form helpers:
 * file_field
 * number_field
 * email_field
-* telephone_field (phone_field)
+* telephone_field / phone_field
 * url_field
 * select
 * collection_select
@@ -55,86 +94,160 @@ This plugin provides the following form helpers:
 * time_select
 * datetime_select
 * check_box
+* radio_button
 
-These form helpers accept the same options as the Rails form helpers with the
-addition of the options `label`, `help`, and `prepend`.  Here's an example form
-that also uses the `actions` helper for the submit button:
+You can use the helpers like you're used to:
 
-    <%= bootstrap_form_for(@user) do |f| %>
-      <%= f.alert_message "Please fix the errors below." %>
+```erb
+<%= bootstrap_form_for(@user) do |f| %>
+  <%= f.text_field :email %>
+  <%= f.password_field :password %>
+  <%= f.primary "Create My Account" %>
+<% end %>
+```
 
-      <%= f.text_field :email, autofocus: :true %>
-      <%= f.password_field :password, help: 'Must be at least 6 characters long' %>
-      <%= f.password_field :password_confirmation, label: 'Confirm Password' %>
-      <%= f.text_field :website, prepend: 'http://' %>
-      <%= f.check_box :terms, label: 'I agree to the Terms of Service' %>
+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:
 
-      <%= f.actions do %>
-        <%= f.primary 'Sign Up', disable_with: 'Saving...' %>
-      <% end %>
-    <% end %>
+```erb
+<%= f.control_group :skill_level, label: { text: 'Skill' } 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 %>
 
-![Example Form](https://github.com/potenza/bootstrap_form/raw/master/examples/example_form.png)
+<%= f.control_group :terms, label: { text: 'Terms' } do %>
+  <%= f.check_box :terms, label: 'I agree to the Terms of Service' %>
+<% end %>
+```
 
+You can display checkboxes and radios `inline` like this:
 
-Options
--------
+```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 %>
+<% end %>
+```
 
-To use a horizontal-style form with labels to the left of the inputs,
-add the `.form-horizontal` class:
+### Labels
 
-    <%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }) do |f| %>
+Use the `label` option if you want to specify the field's label text:
 
-To place helper text underneath the fields, pass the option `help:
-:block`:
+```erb
+<%= f.password_field :password_confirmation, label: 'Confirm Password' %>
+```
 
-    <%= bootstrap_form_for(@user, help: block) do |f| %>
+NOTE: To specify the label for a `control_group` you must do it like this:
 
-Here's an example of a horizontal-style form with block helpers:
+```erb
+<%= f.control_group :terms, label: { text: 'Terms' } do %>
+  <%= f.check_box :terms, label: 'I agree to the Terms of Service' %>
+<% end %>
+```
 
-![Example Form](https://github.com/potenza/bootstrap_form/raw/master/examples/example_horizontal_block_form.png)
+### Help text
 
+To add help text, use the `help` option, which will place it
+to the right of the field:
 
-Custom Controls
----------------
+```erb
+<%= f.password_field :password, help: 'Must be at least 6 characters long' %>
+```
 
-If you have a custom form control or content that you want to wrap 
-in Bootstrap-style form markup, you can do the following:
-  
-    <%= f.control_group "Custom Field" do %>
-      <span>My Custom Field</span>
-    <% end %>
+To place help text underneath a field, pass the option `help:
+:block` to the `bootstrap_form_for` helper:
 
-which will output the following:
+```erb
+<%= bootstrap_form_for(@user, help: :block) do |f| %>
+  <%= f.password_field :password, help: 'Must be at least 6 characters long' %>
+<% end %>
+```
 
-    <div class="control-group">
-      <label class="control-label">Custom Field</label>
-      <div class="controls">
-        <span>My Custom Field</span>
-      </div>
-    </div>
+### Prepending inputs
 
-You can also specify the label's for attribute like this:
+You can prepend an input file with the `prepend` option:
 
-    <%= f.control_group "Custom Field", for: 'custom-control' do %>
-      <span>My Custom Field</span>
-    <% end %>
-  
+```erb
+<%= f.text_field :twitter_username, prepend: '@' %>
+```
 
-Validation Errors
------------------
+### Submit buttons
 
-When a validation error is triggered, the field will be outlined and the
-error will be displayed next to the field. Rails normally wraps fields
-in a div (field_with_errors), but this behavior is suppressed when `bootstrap_form_for` is called.
+This gem provides a few different options for submit buttons.
+
+You can use the `actions` helper, which wraps your submit button in a
+`.form-actions` class.
+
+```erb
+<%= f.actions do %>
+  <%= f.primary 'Create My Account' %>
+<% end %>
+```
+
+Here's a simple `primary` button (this applies the `.btn` and `.btn-primary` classes):
+
+```erb
+<%= f.primary "Create My Account" %>
+```
+
+Here's a `secondary` submit button (applies just the `.btn` class):
+
+```erb
+<%= f.secondary "Create My Account" %>
+```
+
+And if you don't want to use the `actions` helper, here's how you might 
+style a `primary` button with horizontal-style forms:
 
-![Example form with errors](https://github.com/potenza/bootstrap_form/raw/master/examples/example_form_error.png)
+```erb
+<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }) do |f| %>
+  <%= f.control_group do %>
+    <%= f.primary "Create My Account" %>
+  <% end %>
+<% end %>
+```
+
+### Custom Control Groups
+
+Sometimes you need to wrap a custom control in Bootstrap-style markup.
+This is mostly needed when using horizontal-style forms. You can use the
+`control_group` helper to do this:
+
+```erb
+<%= bootstrap_form_for(@user, html: { class: 'form-horizontal' }) do |f| %>
+  <%= f.control_group do %>
+    <%= f.primary "Create My Account" %>
+  <% end %>
+<% end %>
+```
+
+To specify a label that isn't linked to an element you can do this:
+
+```erb
+<%= f.control_group :nil, label: { text: 'Foo' } do %>
+  <span>Bar</span>
+<% end %>
+```
+
+### Validation Errors
+
+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.
 
+To display an error message wrapped in `.alert` and `.alert-error`
+classes, you can use the `alert_message` helper:
 
-Credits
--------
+```erb
+  <%= f.alert_message "Please fix the errors below." %>
+```
 
-Inspired by Ryan Bates' [Form Builder
-Railscast](http://railscasts.com/episodes/311-form-builders)
+## Credits
 
-bootstrap_form is Copyright (c) 2012 Stephen Potenza and is distributed under the MIT license.
+bootstrap_form is Copyright (c) 2013 Stephen Potenza (https://github.com/potenza) and is distributed under the MIT license.

data/lib/bootstrap_form/form_builder.rb

@@ -18,45 +18,66 @@ module BootstrapForm
     FORM_HELPERS.each do |method_name|
       define_method(method_name) do |name, *args|
         options = args.extract_options!.symbolize_keys!
-        content_tag :div, class: "control-group#{(' error' if object.errors[name].any?)}"  do
-          label(name, options[:label], class: 'control-label') +
-          content_tag(:div, class: 'controls') do
-            help = object.errors[name].any? ? object.errors[name].join(', ') : options[:help]
-            help = content_tag(@help_tag, class: @help_css) { help } if help
-
-            args << options.except(:label, :help, :prepend)
-            element = super(name, *args) + help
-
-            if prepend = options.delete(:prepend)
-              element = content_tag(:div, class: 'input-prepend') do
-                content_tag(:span, prepend, class: 'add-on') + element
-              end
-            end
 
-            element
+        control_group(name, label: { text: options[:label] }) do
+          help = object.errors[name].any? ? object.errors[name].join(', ') : options[:help]
+          help = content_tag(@help_tag, class: @help_css) { help } if help
+
+          args << options.except(:label, :help, :prepend)
+          element = super(name, *args) + help
+
+          if prepend = options.delete(:prepend)
+            element = content_tag(:div, class: 'input-prepend') do
+              content_tag(:span, prepend, class: 'add-on') + element
+            end
           end
+
+          element
         end
       end
     end
 
     def check_box(name, *args)
       options = args.extract_options!.symbolize_keys!
-      content_tag :div, class: "control-group#{(' error' if object.errors[name].any?)}"  do
-        content_tag(:div, class: 'controls') do
-          args << options.except(:label, :help)
-          html = super(name, *args) + ' ' + options[:label]
-          label(name, html, class: 'checkbox')
-        end
-      end
+      args << options.except(:label, :help, :inline)
+
+      html = super(name, *args) + ' ' + options[:label]
+
+      css = 'checkbox'
+      css << ' inline' if options[:inline]
+      label(name, html, class: css)
+    end
+
+    def radio_button(name, value, *args)
+      options = args.extract_options!.symbolize_keys!
+      args << options.except(:label, :help, :inline)
+
+      html = super(name, value, *args) + ' ' + options[:label]
+
+      css = 'radio'
+      css << ' inline' if options[:inline]
+      label("#{name}_#{value}", html, class: css)
     end
 
-    def control_group(label_name, label_options = {}, &block)
-      content_tag :div, class: "control-group"  do
-        label_options[:class] = 'control-label'
-        content_tag(:label, label_name, label_options).html_safe +
-        content_tag(:div, class: 'controls') do
+    def control_group(name = nil, options = {}, &block)
+      options[:class] ||= 'control-group'
+      options[:class] << ' error' if name && object.errors[name].any?
+
+      content_tag(:div, options.except(:label)) do
+        html = ''
+
+        if attrs = options.delete(:label)
+          attrs[:class] ||= 'control-label'
+          attrs[:for] ||= '' if name.nil?
+
+          html << label(name, attrs[:text], attrs.except(:text))
+        end
+
+        html << content_tag(:div, class: 'controls') do
           block.call.html_safe
         end
+
+        html.html_safe
       end
     end
 
@@ -68,7 +89,11 @@ module BootstrapForm
 
     def primary(name, options = {})
       options.merge! class: 'btn btn-primary'
+      submit name, options
+    end
 
+    def secondary(name, options = {})
+      options.merge! class: 'btn'
       submit name, options
     end
 

data/lib/bootstrap_form/version.rb

@@ -1,3 +1,3 @@
 module BootstrapForm
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/test/bootstrap_form_test.rb

@@ -104,11 +104,26 @@ class BootstrapFormTest < ActionView::TestCase
     end
   end
 
-  test "check_boxes are wrapped correctly" do
-    expected = %{<div class=\"control-group\"><div class=\"controls\"><label class=\"checkbox\" for=\"user_misc\"><input name=\"user[misc]\" type=\"hidden\" value=\"0\" /><input id=\"user_misc\" name=\"user[misc]\" type=\"checkbox\" value=\"1\" /> This is a checkbox</label></div></div>}
+  test "check_box is wrapped correctly" do
+    expected = %{<label class=\"checkbox\" for=\"user_misc\"><input name=\"user[misc]\" type=\"hidden\" value=\"0\" /><input id=\"user_misc\" name=\"user[misc]\" type=\"checkbox\" value=\"1\" /> This is a checkbox</label>}
     assert_equal expected, @builder.check_box(:misc, label: 'This is a checkbox')
   end
 
+  test "check_box inline label is setted correctly" do
+    expected = %{<label class=\"checkbox inline\" for=\"user_misc\"><input name=\"user[misc]\" type=\"hidden\" value=\"0\" /><input id=\"user_misc\" name=\"user[misc]\" type=\"checkbox\" value=\"1\" /> This is a checkbox</label>}
+    assert_equal expected, @builder.check_box(:misc, label: 'This is a checkbox', inline: true)
+  end
+
+  test "radio_button is wrapped correctly" do
+    expected = %{<label class=\"radio\" for=\"user_misc_1\"><input id=\"user_misc_1\" name=\"user[misc]\" type=\"radio\" value=\"1\" /> This is a radio button</label>}
+    assert_equal expected, @builder.radio_button(:misc, '1', label: 'This is a radio button')
+  end
+
+  test "radio_button inline label is setted correctly" do
+    expected = %{<label class=\"radio inline\" for=\"user_misc_1\"><input id=\"user_misc_1\" name=\"user[misc]\" type=\"radio\" value=\"1\" /> This is a radio button</label>}
+    assert_equal expected, @builder.radio_button(:misc, '1', label: 'This is a radio button', inline: true)
+  end
+
   test "changing the label text" do
     expected = %{<div class=\"control-group\"><label class=\"control-label\" for=\"user_email\">Email Address</label><div class=\"controls\"><input id=\"user_email\" name=\"user[email]\" size=\"30\" type=\"text\" value=\"steve@example.com\" /></div></div>}
     assert_equal expected, @builder.text_field(:email, label: 'Email Address')
@@ -130,18 +145,68 @@ class BootstrapFormTest < ActionView::TestCase
   end
 
   test "control_group creates a valid structure and allows arbitrary html to be added via a block" do
-    output = @builder.control_group "Custom Control" do
+    output = @builder.control_group do
       '<span>custom control here</span>'
     end
-    expected = %{<div class="control-group"><label class="control-label">Custom Control</label><div class="controls"><span>custom control here</span></div></div>}
+
+    expected = %{<div class="control-group"><div class="controls"><span>custom control here</span></div></div>}
     assert_equal expected, output
   end
 
-  test "control_group allows for the label's 'for' attribute to be set" do
-    output = @builder.control_group "Custom Control", for: 'custom_control' do
+  test "control_group renders the options for div.control_group" do
+    output = @builder.control_group nil, id: 'foo' do
       '<span>custom control here</span>'
     end
-    expected = %{<div class="control-group"><label class="control-label" for="custom_control">Custom Control</label><div class="controls"><span>custom control here</span></div></div>}
+
+    expected = %{<div class="control-group" id="foo"><div class="controls"><span>custom control here</span></div></div>}
+    assert_equal expected, output
+  end
+
+  test "control_group overrides the control-group class if another is passed" do
+    output = @builder.control_group nil, class: 'foo' do
+      '<span>custom control here</span>'
+    end
+
+    expected = %{<div class="foo"><div class="controls"><span>custom control here</span></div></div>}
+    assert_equal expected, output
+  end
+
+  test "control_group renders the label correctly" do
+    output = @builder.control_group :email, label: { text: 'Custom Control' } do
+      '<span>custom control here</span>'
+    end
+
+    expected = %{<div class="control-group"><label class="control-label" for="user_email">Custom Control</label><div class="controls"><span>custom control here</span></div></div>}
+    assert_equal expected, output
+  end
+
+  test "control_group overrides the label's 'class' and 'for' attributes if others are passed" do
+    output = @builder.control_group nil, label: { text: 'Custom Control', class: 'foo', for: 'bar' } do
+      '<span>custom control here</span>'
+    end
+
+    expected = %{<div class="control-group"><label class="foo" for="bar">Custom Control</label><div class="controls"><span>custom control here</span></div></div>}
+    assert_equal expected, output
+  end
+
+  test "control_group label's 'for' attribute should be empty if no name was passed" do
+    output = @builder.control_group nil, label: { text: 'Custom Control' } do
+      '<span>custom control here</span>'
+    end
+
+    expected = %{<div class="control-group"><label class="control-label" for="">Custom Control</label><div class="controls"><span>custom control here</span></div></div>}
+    assert_equal expected, output
+  end
+
+  test 'control_group renders the "error" class corrrectly when object is invalid' do
+    @user.email = nil
+    @user.valid?
+
+    output = @builder.control_group :email do
+      '<span>custom control here</span>'
+    end
+
+    expected = %{<div class="control-group error"><div class="controls"><span>custom control here</span></div></div>}
     assert_equal expected, output
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bootstrap_form
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-04 00:00:00.000000000 Z
+date: 2013-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails