Extending Formtastic can be done by overriding the semantic_form_builder method

Signed-off-by: Justin French <[email protected]>

Author: markmansour

.gitignore

@@ -1,2 +1,3 @@
 .DS_Store
 coverage
+*~

README.textile

@@ -8,25 +8,25 @@ Hacked together forms were easy, but awesome forms with decent semantics, rich m
 
 <pre>
   <% semantic_form_for @article do |form| %>
-  
+
     <% form.inputs :name => "Basic" do %>
-      <%= form.input :title %>                               
-      <%= form.input :body %>                                
-      <%= form.input :section_id %>                          
-      <%= form.input :publication_state_id, :as => :radio %> 
-      <%= form.input :author_id, :as => :select %>                           
-      <%= form.input :allow_comments, :label => "Allow commenting on this article" %>                      
-    <% end %>                                                
-  
+      <%= form.input :title %>
+      <%= form.input :body %>
+      <%= form.input :section_id %>
+      <%= form.input :publication_state_id, :as => :radio %>
+      <%= form.input :author_id, :as => :select %>
+      <%= form.input :allow_comments, :label => "Allow commenting on this article" %>
+    <% end %>
+
     <% form.inputs :name => "Advanced" do %>
-      <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>        
+      <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
       <%= form.input :extract, :required => false %>
       <%= form.input :description, :required => false %>
-      <%= form.input :url_title, :required => false %>                           
+      <%= form.input :url_title, :required => false %>
     <% end %>
 
-    <% form.buttons do %>                                    
-      <%= form.commit_button %>                             
+    <% form.buttons do %>
+      <%= form.commit_button %>
     <% end %>
 
   <% end %>
@@ -191,6 +191,50 @@ You don't even have to specify the field list (Formtastic will simply render and
 
 Pretty soon we won't have to write any code at all ;)
 
+h2. Extending Formtastic
+
+Adding functionality to Formtastic can be done by extending SemanticFormHelper.
+
+<pre>
+module JustinFrench #:nodoc:
+  module Formtastic #:nodoc:
+    class FancySemanticFormBuilder < SemanticFormBuilder
+
+      # new method to be added allowing full control over the label and value
+      def label_and_value(label_text, value, options = {})
+        options[:label] = label_text
+        content = text_label(label_text, options)
+        content += @template.content_tag(:span, value)
+        @template.content_tag(:li, content)
+      end
+    end
+  end
+end
+</pre>
+
+To use this builder specify the builder name when defining the form.
+
+<pre>
+  form_for(@post, :builder => JustinFrench::Formtastic::FancySemanticFormBuilder))
+</pre>
+
+The extended form builder can be placed in the RAILS_ROOT/lib directory and can be required in a Rails initializer.
+
+If you want to make the extended form builder the default for the semantic_form_* methods then the SemanticFormBuilder can overridden to specify a new semantic_form_builder.
+
+<pre>
+module JustinFrench #:nodoc:
+  module Formtastic #:nodoc:
+    module TextEnabledSemanticFormHelper
+      def semantic_form_builder
+        JustinFrench::Formtastic::TextEnabledSemanticFormBuilder
+      end
+    end
+  end
+end
+
+ActionView::Base.send :include, JustinFrench::Formtastic::TextEnabledSemanticFormHelper
+</pre>
 
 h2. Conventions & Prerequisites
 

lib/justin_french/formtastic.rb

@@ -42,10 +42,10 @@ module Formtastic #:nodoc:
     # has too many dependencies on an ActiveRecord object being present.
     module SemanticFormHelper
       [:form_for, :fields_for, :form_remote_for, :remote_form_for].each do |meth|
-        src = <<-END_SRC   
+        src = <<-END_SRC
           def semantic_#{meth}(record_or_name_or_array, *args, &proc)
             options = args.extract_options!
-            options[:builder] =  JustinFrench::Formtastic::SemanticFormBuilder
+            options[:builder] = semantic_form_builder
             options[:html] ||= {}
 
             class_names = options[:html][:class] ? options[:html][:class].split(" ") : []
@@ -59,11 +59,15 @@ def semantic_#{meth}(record_or_name_or_array, *args, &proc)
 
             #{meth}(record_or_name_or_array, *(args << options), &proc)
           end
+
+          def semantic_form_builder
+            JustinFrench::Formtastic::SemanticFormBuilder
+          end
         END_SRC
         module_eval src, __FILE__, __LINE__
       end
     end
-    
+
     class SemanticFormBuilder < ActionView::Helpers::FormBuilder
 
       DEFAULT_TEXT_FIELD_SIZE = 50