Fingertips-form-san 0.4.0 → 0.5.0

data/lib/form_san.rb

@@ -1,25 +1,74 @@
 require 'action_view/helpers'
 
 module FormSan
+  # = FormSan::FormBuilder
+  # 
+  # FormSan has two goals:
+  # * Make it easier for the developer to write out a form
+  # * Make the resulting form more usable
+  #
+  # You can use the form builder by specifying it in the <tt>:builder</tt> option in <tt>form_for</tt>.
+  #
+  #   form_for(@post, :builder => FormSan::FormBuilder)
+  #
+  # You can also make it the default form builder by specifying it in an initializer or <tt>environment.rb</tt>.
+  #
+  #   ActionView::Base.default_form_builder = FormSan::FormBuilder
   class FormBuilder < ActionView::Helpers::FormBuilder
+    attr_reader :template
+    delegate :concat, :content_tag, :to => :template
+    
+    # Wraps its content in a div with a fieldset class. You use it to group sets of fields.
+    #
+    #   <% f.fieldset do %>
+    #     <p>Please complete the form.</p>
+    #     …
+    #   <% end %>
+    #
+    # Generates
+    #
+    #   <div class="fieldset">
+    #     <p>Please complete the form.</p>
+    #     …
+    #   </div>
     def fieldset(&block)
-      @template.content_tag(:div, :class => 'fieldset', &block)
+      content_tag(:div, :class => 'fieldset', &block)
     end
     
+    # Wraps its content in a div with a fields class. You use it to group fields.
+    #
+    #   <% f.fields do %>
+    #     <h4>Personal information</h4>
+    #     …
+    #   <% end %>
+    #
+    # Generates
+    #
+    #   <div class="fields">
+    #     <h4>Personal information</h4>
+    #     …
+    #   </div>
     def fields(&block)
-      @template.content_tag(:div, :class => 'fields', &block)
+      content_tag(:div, :class => 'fields', &block)
     end
     
+    # Generates a short sentence in a paragraph describing which attributes have validation errors.
+    #
+    #   <%= f.error_messages %>
+    #
+    # Generates something like
+    #
+    #   <p class="errors">Sorry, there were problems with the title, published date, and description.</p>
     def error_messages
       unless @object.errors.count.zero?
         attributes_with_errors =  @object.errors.map { |attribute, _| attribute } - ['base']
-        @template.content_tag(:p, :class => 'errors') do
+        content_tag(:p, :class => 'errors') do
           if attributes_with_errors.size > 1
-            @template.concat "Sorry, there were problems with the #{attributes_with_errors.to_sentence}."
+            concat "Sorry, there were problems with the #{attributes_with_errors.to_sentence}."
           elsif attributes_with_errors.size == 1
-            @template.concat "Sorry, there was a problem with the #{attributes_with_errors.first}."
+            concat "Sorry, there was a problem with the #{attributes_with_errors.first}."
           else
-            @template.concat "#{@object.class} #{@object.errors.on(:base)}."
+            concat "#{@object.class} #{@object.errors.on(:base)}."
           end
         end
       else
@@ -27,52 +76,125 @@ module FormSan
       end
     end
     
+    # Generates a short in a paragraph with the validation error of a specific attribute.
+    #
+    #   <%= f.error_message(:title) %>
+    #
+    # Generates something like
+    #
+    #   <p class="notice">Can't be blank</p>
     def error_message(attribute)
       unless @object.errors.on(attribute).blank?
-        @template.content_tag(:p, :class => 'notice') do
-          @template.concat ERB::Util.html_escape(@object.errors.on(attribute).mb_chars.capitalize)
+        content_tag(:p, :class => 'notice') do
+          concat ERB::Util.html_escape(@object.errors.on(attribute).mb_chars.capitalize)
         end
       else
         ''
       end
     end
     
-    def field_without_block(attribute, extra_content=nil, *args)
+    # Generates a label for an attribute wrapped in a div. It allows you to specify an alternative
+    # humanized form of the attribute name and whether the associated field is optional or not.
+    #
+    #   <%= f.label(:title) %>
+    #   <div class="label"><label for="book_title">Title</label></div>
+    #
+    #   <%= f.label(:title, 'Book title') %>
+    #   <div class="label"><label for="book_title">Book title</label></div>
+    #
+    #   <%= f.label(:title, :optional => true) %>
+    #   <div class="label"><label for="book_title">Title <span>(optional)</span></label></div>
+    #
+    # When there is a validation error on the attribute, this will also be reflected in the HTML.
+    #
+    #   <%= f.label(:title) %>
+    #   <div class="label">
+    #     <label for="book_title">Title <span>(optional)</span></label>
+    #     <p class="notice">Can't be blank.</p>
+    #   </div>
+    def wrapped_label(attribute, *args)
+      options = args.extract_options!
+      
+      label_text = args.first || attribute.to_s.humanize
+      label_text << ' <span>(optional)</span>' if options[:optional]
+      
+      content_tag(:div, :class => 'label') do
+        concat label(attribute, label_text)
+        concat error_message(attribute)
+      end
+    end
+    
+    def field_with_extra_content(attribute, extra_content=nil, *args) #:nodoc:
       options = args.extract_options!
       classes = @object.errors.on(attribute) ? 'invalid field' : 'field'
       
-      @template.content_tag(:div, :class => classes) do
-        @template.concat(@template.content_tag(:div, :class => 'label') do
-          label_text = args.first || attribute.to_s.humanize
-          label_text << ' <span>(optional)</span>' if options.delete(:optional)
-          @template.concat self.label(attribute, label_text)
-        end)
+      content_tag(:div, :class => classes) do
+        concat wrapped_label(attribute, args.first, :optional => options.delete(:optional))
         
         case input_type = options.delete(:type).to_s
         when 'textarea'
-          @template.concat ActionView::Helpers::InstanceTag.new(@object_name, attribute, self, @object).to_text_area_tag(options)
+          concat ActionView::Helpers::InstanceTag.new(@object_name, attribute, self, @object).to_text_area_tag(options)
         else
-          @template.concat ActionView::Helpers::InstanceTag.new(@object_name, attribute, self, @object).to_input_field_tag(input_type, options)
+          concat ActionView::Helpers::InstanceTag.new(@object_name, attribute, self, @object).to_input_field_tag(input_type, options)
         end
         
-        @template.concat error_message(attribute)
-        @template.concat extra_content unless extra_content.blank?
+        concat extra_content unless extra_content.blank?
         @template.output_buffer # The block needs to return the current buffer
       end
     end
     
+    # Generates a field of a certain type wrapped in all sorts of HTML.
+    #
+    #   <%= f.field(:title, :type => :text) %>
+    #   <div class="field">
+    #     <div class="label"><label for="book_title">Title</label></div>
+    #     <input id="book_title" type="text" name="book[title]" value="Empire of the Sun" />
+    #   </div>
+    #
+    # When there is a validation error on the attribute, this will also be reflected in the HTML.
+    #
+    #   <div class="invalid field">
+    #     <div class="label"><label for="book_title">Title</label></div>
+    #     <input id="book_title" type="text" name="book[title]" value="" />
+    #     <p class="notice">Can't be blank.</p>
+    #   </div>
+    #
+    # You can also pass a block to field, that way you can include more HTML into the div.
+    #
+    #   <% f.field(:title, :type => :text) do %>
+    #     <p class="note">This will be shown on the overview page as the book title.</p>
+    #   <% end %>
+    #
+    #   <div class="field">
+    #     <div class="label"><label for="book_title">Title</label></div>
+    #     <input id="book_title" type="text" name="book[title]" value="Empire of the Sun" />
+    #     <p class="note">This will be shown on the overview page as the book title.</p>
+    #   </div>
+    #
+    # All options except <tt>:type</tt> are passed to the input.
+    #
+    #   <%= f.field(:title, :type => :text, :class => 'small') %>
+    #
+    #   <div class="field">
+    #     <div class="label"><label for="book_title">Title</label></div>
+    #     <input id="book_title" type="text" name="book[title]" value="Empire of the Sun" class="small" />
+    #   </div>
     def field(attribute, *args, &block)
       if block_given?
-        @template.concat field_without_block(attribute, @template.capture(&block), *args)
+        concat field_with_extra_content(attribute, @template.capture(&block), *args)
       else
-        field_without_block(attribute, nil, *args)
+        field_with_extra_content(attribute, nil, *args)
       end
     end
   end
 end
 
-class ActionView::Helpers::InstanceTag
-  def error_wrapping(html_tag, has_error)
-    html_tag
+module ActionView #:nodoc:
+  module Helpers #:nodoc:
+    class InstanceTag #:nodoc:
+      def error_wrapping(html_tag, has_error)
+        html_tag
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: Fingertips-form-san
 version: !ruby/object:Gem::Version 
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors: 
 - Manfred Stienstra
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-25 00:00:00 -07:00
+date: 2009-03-26 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -19,14 +19,11 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: 
-- README.rdoc
-- LICENSE
+extra_rdoc_files: []
+
 files: 
 - lib/form_san.rb
 - rails/init.rb
-- README.rdoc
-- LICENSE
 has_rdoc: true
 homepage: http://github.com/Fingertips/form-san
 post_install_message: 

data/LICENSE

@@ -1,20 +0,0 @@
-Copyright © 2009 Fingertips, Manfred Stienstra
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,27 +0,0 @@
-= Form-San
-
-Form-San is a lean extension for the Rails form builder.
-
-  <% form_for(@member, :builder => FormSan::FormBuilder) do |f| %>
-    <% f.fieldset do %>
-      <% f.fields do %>
-        <%= f.error_messages %>
-        
-        <% f.field(:email, :type => :text, :class => 'medium') do %>
-          <p class="hint">You’ll log in using your email address.</p>
-        <% end %>
-        <%= f.field(:password, :type => :password) %>
-      
-        <% f.fields_for(@member.artist) do |a| %>
-          <% a.field(:name, :type => :text, :class => 'medium') do %>
-            <p class="hint">Shown on the site.</p>
-          <% end %>
-        <% end %>
-      <% end %>
-    <% end %>
-    
-    <div class="submit">
-      <%= f.submit 'Sign up' %>
-      <%= link_to 'Cancel', root_path, :class => 'cancel' %>
-    </div>
-  <% end %>