better_form 0.7.0 → 0.8.0

data/README.md

@@ -1,12 +1,19 @@
 better_form Readme
 ==================
 
-A Rails 3 gem to build DRY forms with Javascript validation.
+A better Rails 3 FormBuilder.
 
-* Javascript validates form fields as they are completed, using your `ActiveModel` validators
-* Well-placed validation output
-* Automatic label generation
-* Form field descriptions
+Features:
+
+* Uses partials to put you in control of templating your form fields
+* Free Javascript validation using the same validations you specify in your models
+* Out of the box support for common cases; fully customizeable if that's how you roll
+
+Why should I use `better_form` over `formtastic` or `simple_form`?
+
+* No DSL; just use the default Rails form helpers
+* No fixed ideas about what options or output you want for your fields
+* Less features, less code, less complexity; you get DRY fields with DRY validators and nothing more
 
 Links
 =====
@@ -18,44 +25,113 @@ Links
 Installation and Usage
 ======================
 
-Add `better_form` to your Gemfile:
+Add `better_form` to your Gemfile and run `bundle install`.
+
+Generate the required initializer and boilerplate form field partial:
+
+    rails generate better_form
+
+Use the `better_form_for` method to create a better form, and add fields using the default Rails form helpers.
+
+Customizing your form fields
+============================
+
+Modify the generated form field partial in `app/views/better_form/_field.html.erb`. Or, create your own from scratch using whatever templating engine you prefer - it's just a regular partial.
+
+A few ideas to get you in the mood:
+
+    # Epic error messages
+    <%= field[:field] %>
+    <%= error_messages.each do |message| %>
+      <h1 class="fail">OH NOES! <%= message %></h1>
+    <% end %>
+
+    # Floated field descriptions
+    <div class="form_field">
+      <%= field[:field] %>
+      <div class="description float-right"><%= field[:description] -%></div>
+    </div>
+
+    # All the bells and whistles
+    <div class="better_form_field <%= 'invalid' if error_messages %>">
+      <div class="field">
+        <% if field[:prefix] %>
+          <span class="field_prefix"><%= field[:prefix] %></span>
+        <% end %>
+        <%= field[:field] %>
+        <% if field[:suffix] %>
+          <span class="field_suffix"><%= field[:suffix] %></span>
+        <% end %>
+        <% if field[:description] %>
+          <br>
+          <span class="field_description"><%= field[:description] %></span>
+        <% end %>
+      </div>
+      <%= if error_messages %>
+        <span class="error_header">Oops!</span>
+        <div class="field_errors">
+          <%= error_messages.each do |message| %>
+            <p class="error_message">
+              <%= image_tag('warning_small') %>
+              <%= message %>
+            </p>
+          <% end %>
+        </div>
+      </div>
+    </div>
+
+Have a look at `app/views/better_form/_field.html.erb` to get started.
+
+Built-in options
+================
 
-    gem 'better_form'
+Validations
+-----------
 
-And run the usual `bundle install`.
+Fields can automatically have validation data generated for them using the validations defined in your models:
+
+    class User < ActiveRecord::Base
+      validates :name, :presence => true
+    end
 
-Use the `better_form_for` method to create a better form:
+    <%= f.text_field :name %>
 
-    = better_form_for @user do |f|
+    <label for='user_name'>What shall we call you?</label>
+    <input type='text' id='user_name' name='user[name]' data-validates-presence="Name is required" />
+
+Setting a custom error message will be reflected in the validation that is generated:
+
+    validates :name, :presence => { :message => 'Please enter your full name' }
+
+    <input type='text' id='user_name' name='user[name]' data-validates-presence="Please enter your full name" />
 
-Create fields using the usual Rails methods:
+Validations are enabled by default. They can be enabled or disabled for a form, or for particular fields:
 
-    = f.text_field :name
-    = f.email_field :email
-    = f.password_field :password
+    # Don't generate validations for this form, unless instructed to for specific fields
+    <%= better_form_for @user, :validate => false do |f| %>
+      <%= f.text_field :name %>
+      <%= f.text_field :password, :validate => true %>
 
 Labels
 ------
 
-Fields will automatically have labels generated for them, with the label text defaulting to the attribute that the field is for:
+Fields can automatically have label text generated for them, with the label text defaulting to the attribute that the field is for:
 
-    = f.text_field :name
+    <%= f.text_field :name %>
 
     <label for='user_name'>Name</label>
     <input type='text' id='user_name' name='user[name]' />
 
 To specify your own label text, pass a string as the `:label` option:
 
-    = f.text_field :name, :label => "What shall we call you?"
+    <%= f.text_field :name, :label => "What shall we call you?" %>
 
     <label for='user_name'>What shall we call you?</label>
     <input type='text' id='user_name' name='user[name]' />
 
 To skip label generation for a specific field, pass `false` as the `:label` option:
 
-    = f.text_field :name, :label => false
-
-    <input type='text' id='user_name' name='user[name]' />
+    <%= f.text_field :name, :label => false %>
 
 You can set the default for the entire form in the same way. Field-level `:label` options will override the default value. For example:
 
@@ -73,22 +149,10 @@ You can set the default for the entire form in the same way. Field-level `:label
     <label for='user_password'>Pick a strong password</label>
     <input type='password' id='user_password' name='user[password]' />
 
-Validations
------------
-
-Fields will automatically have validation data generated for them using the validations defined in your models:
-
-    class User < ActiveRecord::Base
-      validates :name, :presence => true
-    end
+Troubleshooting
+===============
 
-    = f.text_field :name
+If you get a `BetterForm::InstallationError`, you need to run `rails generate better_form`. This installs an initializer that overrides a method
+in `better_form` and lets you customize the handling of your field partial.
 
-    <label for='user_name'>What shall we call you?</label>
-    <input type='text' id='user_name' name='user[name]' data-validates-presence="Name is required" />
-
-Setting a custom error message will be reflected in the validation that is generated:
-
-    validates :name, :presence => { :message => 'Please enter your full name' }
-
-    <input type='text' id='user_name' name='user[name]' data-validates-presence="Please enter your full name" />
+You will need to restart WEBrick after running the generator so that the initializer is loaded.

data/lib/better_form/builder.rb

@@ -1,87 +1,53 @@
 module BetterForm
-  class Builder < ActionView::Helpers::FormBuilder
-    include ActionView::Helpers::UrlHelper
+  # Raised when the better_form initializer has not been installed
+  class InstallationError < StandardError
+  end
 
+  class Builder < ActionView::Helpers::FormBuilder
     helpers = field_helpers + %w(date_select datetime_select time_select collection_select select time_zone_select) - %w(label hidden_field fields_for)
     helpers.each do |field_type|
       define_method(field_type) do |field_name, *args|
         options = args.extract_options!
 
-        # Extract the prefix and suffix (if any), and make them html_safe
-        prefix = (options.delete(:prefix) || '').html_safe
-        suffix = (options.delete(:suffix) || '').html_safe
-        description = (options.delete(:description) || '').html_safe
-
-        # Extract the label argument and validate argument
-        label = options.delete(:label)
-        validate = options.delete(:validate)
-
-        error_message = ''.html_safe
+        error_messages = @object.errors[field_name]
 
         # If this field is explicitly validated, or this field and the whole form aren't explicitly *not* validated
+        validate = options.delete(:validate)
         if validate or (validate != false and @template.validate_all? != false)
           # Generate validations for the field
           validations = generate_validations(@object, field_name)
           options.merge!(validations)
-
-          # Add an 'invalid' class to it if it has errors
-          unless @object.errors[field_name].blank?
-            css_classes = options.delete(:class)
-            options.merge!({ :class => "#{css_classes} invalid" })
-            error_message = generate_error(field_name)
-          end
         end
 
-        # Generate a label if necessary
+        # Generate label_text if necessary, or set it to nil if we're not labelling this field
+        label = options.delete(:label)
         if (label == false) or (label == nil and @template.label_all? == false)
-          label = ''.html_safe
+          generated_label = nil
         else
-          label = generate_label(field_type, field_name, label)
+          generated_label = generate_label(field_name, label)
         end
 
         # Generate the field itself
-        field = super(field_name, *(args << options))
-
-        # Generate the field description
-        description = generate_description(description)
+        form_field = super(field_name, *(args << options))
 
         # Join all the parts together to make a better form field!
-        better_form_field(:label => label, :prefix => prefix, :field => field, :suffix => suffix, :description => description, :error_message => error_message)
-      end
-    end
-
-    def submit(options = {})
-      value = options.delete(:value)
-      cancel_url = options.delete(:cancel)
-      if cancel_url
-        super(value, options) + "<span class='cancel'>or #{link_to('Cancel', cancel_url)}</span>".html_safe
-      else
-        super(value, options)
+        better_form_field(form_field, field_type, generated_label, error_messages, options)
       end
     end
 
-    def better_form_field(field)
-      field[:label] + content_tag(:span, field[:prefix] + field[:field] + field[:suffix] + field[:description]) + field[:error_message]
+    def better_form_field(form_field, field_type, generated_label, error_messages, options)
+      raise BetterForm::InstallationError, "You need to run `rails generate better_form` and restart WEBrick before you can use better_form"
     end
 
   private
-    def generate_label(field_type, method, label)
+    def generate_label(field_name, label)
       if label == true
-        label_text = method.to_s.gsub(/_/, ' ').capitalize
+        label_text = field_name.to_s.humanize
       else
         label_text = label.to_s
       end
 
-      options = { :class => :inline } if %w(check_box radio_button).include?(field_type)
-      label(method, label_text, options ||= {})
-    end
-
-    def generate_description(description)
-      content_tag(:span, description, :class => 'field-desc') unless description.blank?
-    end
-
-    def generate_error(field_name)
-      content_tag(:span, @object.errors[field_name].join(tag(:br)).html_safe, :class => :error_message)
+      label(field_name, label_text)
     end
 
     def generate_validations(object, attribute)

data/lib/better_form/version.rb

@@ -1,3 +1,3 @@
 module BetterForm
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/generators/better_form/better_form_generator.rb

@@ -0,0 +1,12 @@
+require 'rails/generators'
+
+class BetterFormGenerator < Rails::Generators::Base
+  source_root File.join(File.dirname(__FILE__), "templates")
+
+  desc 'Install the default better_form initializer and partial'
+  def generate
+    copy_file "better_form.rb", "config/initializers/better_form.rb"
+    copy_file "field.html.erb", "app/views/better_form/_field.html.erb"
+    copy_file "inline_field.html.erb", "app/views/better_form/_inline_field.html.erb"
+  end
+end

data/lib/generators/better_form/templates/better_form.rb

@@ -0,0 +1,12 @@
+module BetterForm
+  class Builder
+    def better_form_field(form_field, field_type, generated_label, error_messages, options)
+      if [:radio_button, :check_box].include?(field_type.to_sym)
+        content = @template.render(:partial => 'better_form/inline_field', :locals => { :form_field => form_field, :field_type => field_type, :generated_label => generated_label, :error_messages => error_messages, :options => options })
+      else
+        content = @template.render(:partial => 'better_form/field', :locals => { :form_field => form_field, :field_type => field_type, :generated_label => generated_label, :error_messages => error_messages, :options => options })
+      end
+      content
+    end
+  end
+end

data/lib/generators/better_form/templates/field.html.erb

@@ -0,0 +1,31 @@
+<%#
+  This is the default partial created when you run `rails generate better_form`
+  Modify it as you see fit to support the functionality you need and generate
+  the markup you desire.
+
+  You can replace this partial entirely with your own HAML version.
+
+  Any options passed to the Rails form helper will be available in the
+  `options` local variable. For example, to set options[:prefix] and
+  options[:suffix]:
+
+  f.text_field :amount, :prefix => '$', :suffix => '/hour'
+
+  You can also edit the initializer in config/initializers/better_form.rb. You
+  might like to do this to render different partials based on the field type or
+  some other condition.
+%>
+
+<div class="form_field">
+  <%= generated_label %>
+  <span>
+    <span class="field_prefix"><%= options[:prefix] %></span>
+    <%= form_field %>
+    <span class="field_suffix"><%= options[:suffix] %></span>
+    <span class="field_description"><%= options[:description] %></span>
+  </span>
+  <% error_messages.each do |message| %>
+    <span class="error_message"><%= message %></span>
+    <br />
+  <% end %>
+</div>

data/lib/generators/better_form/templates/inline_field.html.erb

@@ -0,0 +1,11 @@
+<div class="form_field">
+  <%= form_field %>
+  <span>
+    <%= generated_label %>
+    <span class="field_description"><%= options[:description] %></span>
+  </span>
+  <% error_messages.each do |message| %>
+    <span class="error_message"><%= message %></span>
+    <br />
+  <% end %>
+</div>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_form
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-08-05 00:00:00.000000000 +10:00
-default_executable: 
+date: 2011-10-07 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -19,13 +18,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/generators/better_form/better_form_generator.rb
+- lib/generators/better_form/templates/inline_field.html.erb
+- lib/generators/better_form/templates/field.html.erb
+- lib/generators/better_form/templates/better_form.rb
 - lib/better_form.rb
 - lib/better_form/builder.rb
 - lib/better_form/view_helper.rb
 - lib/better_form/version.rb
 - LICENSE
 - README.md
-has_rdoc: true
 homepage: http://github.com/2suggestions/better_form
 licenses: []
 post_install_message: 
@@ -46,7 +48,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: A Better Rails 3 FormBuilder