formtastic 1.1.0 → 1.2.0.beta

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Justin French
+Copyright (c) 2008-2010 Justin French
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.textile

@@ -2,6 +2,8 @@ h1. Formtastic
 
 Formtastic is a Rails FormBuilder DSL (with some other goodies) to make it far easier to create beautiful, semantically rich, syntactically awesome, readily stylable and wonderfully accessible HTML forms in your Rails applications.
 
+<a href='http://www.pledgie.com/campaigns/2178'><img alt='Click here to lend your support to: formtastic and make a donation at www.pledgie.com !' src='http://www.pledgie.com/campaigns/2178.png?skin_name=chrome' border='0' /></a>
+
 h2. The Story
 
 One day, I finally had enough, so I opened up my text editor, and wrote a DSL for how I'd like to author forms:
@@ -44,7 +46,7 @@ h2. It's better than _SomeOtherFormBuilder_ because...
 
 * it can handle @belongs_to@ associations (like Post belongs_to :author), rendering a select or set of radio inputs with choices from the parent model.
 * it can handle @has_many@ and @has_and_belongs_to_many@ associations (like: Post has_many :tags), rendering a multi-select with choices from the child models.
-* it's Rails 2.3-ready (including nested forms).
+* it's Rails 2.x and 3.x compatible (including nested forms).
 * it has internationalization (I18n)!
 * it's _really_ quick to get started with a basic form in place (4 lines), then go back to add in more detail if you need it.
 * there's heaps of elements, id and class attributes for you to hook in your CSS and JS.
@@ -77,50 +79,30 @@ h2. Documentation
 RDoc documentation _should_ be automatically generated after each commit and made available on the "rdoc.info website":http://rdoc.info/projects/justinfrench/formtastic.
 
 
-h2. A Note About Rails 3 Support
-
-Formtastic 1.0 only supports the latest stable Rails 2.x. We're maintaining a rails3 branch which aims to provide both Rails 2.x and 3.x support, which is targeted for the 1.1 release around the same time Rails 3.0 final ships.
+h2. Installation
 
-A 1.1.0.beta gem is now available on RubyGems.org, so install that with the --pre option:
+Formtastic is now compatible with both Rails 2 and Rails 3, and the gem is "hosted":http://rubygems.org/gems/formtastic on RubyGems.org.
 
-<pre>
-  gem install formtastic --pre
-</pre>
+*You'll need to use Bundler (yes, even under Rails 2, due to the many ways gem dependencies suck). Follow "this tutorial":http://gembundler.com/rails23.html.*
 
-Or bundle it in your Gemfile:
+Simply add Formtastic to your Gemfile and bundle it up:
 
 <pre>
-  gem 'formtastic', '1.1.0.beta'
+  gem 'formtastic', '~> 1.1.0'
 </pre>
 
-You can also live on the edge and track our rails3 branch in your Gemfile with the :git and :branch options:
+Optionally, run the generator to copy some stylesheets and a configuration initializer into your application:
 
 <pre>
-  gem 'formtastic', :git => "git://github.com/justinfrench/formtastic.git", :branch => "rails3"
+  # Rails 3:
+  $ rails generate formtastic:install 
+  
+  # Or Rails 2:
+  $ ./script/generate formtastic 
 </pre>
 
-Please be aware that Rails 3 is still under heavy development (even in the RCs), as is Formtastic, so our beta gems and the rails3 branch is very much "on the edge", just like Rails. If you find compatibility issues with Rails 2 or 3, please report them on Github.
-
-
-h2. Installation under Rails 2.x
 
-Install the Formtastic gem:
-
-<pre>
-  sudo gem install formtastic
-</pre>
-
-And add it to your environment.rb configuration as a gem dependency:
-
-<pre>
-  config.gem 'formtastic'
-</pre>
-
-Optionally, run @./script/generate formtastic@ to copy the following files into your app:
-
-* @config/initializers/formtastic.rb@ - a commented out Formtastic config initializer
-* @public/stylesheets/formtastic.css@
-* @public/stylesheets/formtastic_changes.css@
+h2. Stylesheets
 
 A proof-of-concept stylesheet is provided which you can include in your layout. Customization is best achieved by overriding these styles in an additional stylesheet so that the Formtastic styles can be updated without clobbering your changes. If you want to use these stylesheets, add both to your layout with this helper:
 
@@ -183,7 +165,7 @@ If you want to customize the label text, or render some hint text below the fiel
     <% form.inputs :name => "Advanced Options", :id => "advanced" do %>
       <%= form.input :slug, :label => "URL Title", :hint => "Created automatically if left blank", :required => false %>
       <%= form.input :section, :as => :radio %>
-      <%= form.input :user, :label => "Author", :label_method => :full_name,  %>
+      <%= form.input :user, :label => "Author", :label_method => :full_name %>
       <%= form.input :categories, :required => false %>
       <%= form.input :created_at, :as => :string, :label => "Publication Date", :required => false %>
     <% end %>
@@ -193,7 +175,7 @@ If you want to customize the label text, or render some hint text below the fiel
   <% end %>
 </pre>
 
-Nested forms (Rails 2.3) are also supported (don't forget your models need to be setup correctly with accepts_nested_attributes_for – search the Rails docs). You can do it in the Rails way:
+Nested forms are also supported (don't forget your models need to be setup correctly with @accepts_nested_attributes_for@). You can do it in the Rails way:
 
 <pre>
   <% semantic_form_for @post do |form| %>
@@ -225,6 +207,17 @@ When working in has many association, you can even supply @"%i"@ in your fieldse
   <% end %>
 </pre>
 
+If you have more than one form on the same page, it may lead to HTML invalidation because of the way HTML element id attributes are assigned. You can provide
+a namespace for your form to ensure uniqueness of id attributes on form elements. The namespace attribute will be prefixed with underscore on the generate html id. For example:
+
+<pre>
+  <% semantic_form_for(@post, :namespace => 'cat_form') do |form| %>
+  <%= form.input :title %>        # id="cat_form_post_title"
+  <%= form.input :body %>         # id="cat_form_post_body"
+  <%= form.input :created_at %>   # id="cat_form_post_created_at"
+  <%= form.buttons %>
+  <% end %>
+</pre>
 
 Customize HTML attributes for any input using the @:input_html@ option. Typically this is used to disable the input, change the size of a text field, change the rows in a textarea, or even to add a special class to an input to attach special behavior like "autogrow":http://plugins.jquery.com/project/autogrow textareas:
 
@@ -248,7 +241,7 @@ The same can be done for buttons with the @:button_html@ option:
   <% end %>
 </pre>
 
-Customize the HTML attributes for the @<li>@ wrapper around every input with the @:wrapper_html@ option hash. There's one special key in the hash (@:class@), which will actually _append_ your string of classes to the existing classes provided by Formtastic (like @"required string error"@)
+Customize the HTML attributes for the @<li>@ wrapper around every input with the @:wrapper_html@ option hash. There's one special key in the hash (@:class@), which will actually _append_ your string of classes to the existing classes provided by Formtastic (like @"required string error"@).
 
 <pre>
   <% semantic_form_for @post do |form| %>
@@ -259,6 +252,14 @@ Customize the HTML attributes for the @<li>@ wrapper around every input with the
   <% end %>
 </pre>
 
+Customize the default class used for hints on each attribute or globally in the @config/formtastic.rb@ file. Similarly you can customize the error classes on an attribute level or globally.
+
+<pre>
+  <% semantic_form_for @post do |form| %>
+    <%= form.input :title, :hint_class => 'custom-html-class', :error_class => 'custom-error-class' %>
+  <% end %>
+</pre>
+
 Many inputs provide a collection of options to choose from (like @:select@, @:radio@, @:check_boxes@, @:boolean@). In many cases, Formtastic can find choices through the model associations, but if you want to use your own set of choices, the @:collection@ option is what you want.  You can pass in an Array of objects, an array of Strings, a Hash... Throw almost anything at it! Examples:
 
 <pre>
@@ -295,6 +296,10 @@ The Formtastic input types:
 * @:numeric@ - a text field (just like string). Default for  column types: @:integer@, @:float@, and @:decimal@.
 * @:file@ - a file field. Default for file-attachment attributes matching: "paperclip":http://github.com/thoughtbot/paperclip or "attachment_fu":http://github.com/technoweenie/attachment_fu.
 * @:country@ - a select menu of country names. Default for column types: :string with name @"country"@ - requires a *country_select* plugin to be installed.
+* @:email@ - a text field (just like string). Default for columns with name matching @"email"@. New in HTML5. Works on some mobile browsers already.
+* @:url@ - a text field (just like string). Default for columns with name matching @"url"@. New in HTML5. Works on some mobile browsers already.
+* @:phone@ - a text field (just like string). Default for columns with name matching @"phone"@ or @"fax"@. New in HTML5.
+* @:search@ - a text field (just like string). Default for columns with name matching @"search"@. New in HTML5. Works on Safari.
 * @:hidden@ - a hidden field. Creates a hidden field (added for compatibility).
 
 The comments in the code are pretty good for each of these (what it does, what the output is, what the options are, etc.) so go check it out.
@@ -481,51 +486,67 @@ If you have the "ValidationReflection":http://github.com/redinger/validation_ref
 
 h2. Configuration
 
-Run @./script/generate formtastic@ to copy a commented out config file into @config/initializers/formtastic.rb@. You can "view the configuration file on GitHub":http://github.com/justinfrench/formtastic/blob/master/generators/formtastic/templates/formtastic.rb
+Run @rails generate formtastic:install@ (Rails 3) or @./script/generate formtastic@ (Rails 2) to copy a commented out config file into @config/initializers/formtastic.rb@. You can "view the configuration file on GitHub":http://github.com/justinfrench/formtastic/blob/master/generators/formtastic/templates/formtastic.rb
 
 
 h2. Form Generator
 
-There's a Formtastic form code generator to make your transition to Formtastic easier. All you have to do is to *specify an existing model name*, and optionally specify view template framework (ERB/HAML), and you are good to go. *Note:* This won't overwrite any of you stuff. This is how you use it:
+There's a Formtastic form code generator to make your transition to Formtastic easier. All you have to do is to *specify an existing model name*, and optionally specify view template framework (ERB/HAML), and you are good to go. *Note:* This won't overwrite any of your stuff.
+
+h3. Basic usage
 
-*Alt. 1: Generate in terminal:*
+Rails 3:
 
 <pre>
-$ ./script/generate form Post
-# ---------------------------------------------------------
-#  GENERATED FORMTASTIC CODE
-# ---------------------------------------------------------
+  $ rails generate formtastic:form ModelName
+</pre>
 
-<% f.inputs do %>
-  <%= f.input :title, :label => 'Title' %>
-  <%= f.input :body, :label => 'Body' %>
-  <%= f.input :published, :label => 'Published' %>
-<% end %>
+Rails 2:
 
-# ---------------------------------------------------------
- Copied to clipboard - just paste it!
+<pre>
+  $ ./script/generate form ModelName
 </pre>
 
-*Alt. 2: Generate partial:*
+The results are something like this, with the ERB code printed out to the terminal 
 
 <pre>
-$ ./script/generate form Post --partial
+  $ rails generate formtastic:form Post
+  # ---------------------------------------------------------
+  #  GENERATED FORMTASTIC CODE
+  # ---------------------------------------------------------
+
+  <% f.inputs do %>
+    <%= f.input :title, :label => 'Title' %>
+    <%= f.input :body, :label => 'Body' %>
+    <%= f.input :published, :label => 'Published' %>
+  <% end %>
+
+  # ---------------------------------------------------------
+   Copied to clipboard - just paste it!
+</pre>
+
+h3. Generating a partial with @--partial@
+
+You can also ask Formtastic to *generate a partial* with the @--partial@ option, placing it in the correct location inside your @app/views@ directory:
+
+<pre>
+  $ rails generate formastic:form Post --partial
       exists  app/views/posts
       create  app/views/posts/_form.html.erb
 </pre>
 
-To generate *HAML* markup, just add the @--haml@ as argument:
+h3. Specifying HAML instead of ERB with @--haml@
 
 <pre>
-$ ./script/generate form Post --haml
+  $ rails generate formastic:form Post --haml
       exists  app/views/admin/posts
       create  app/views/admin/posts/_form.html.haml
 </pre>
 
-To specify the controller in a namespace (eg admin/posts instead of posts), use the --controller argument:
+h3. Specifying controller namespace with @--controller@
 
 <pre>
-$ ./script/generate form Post --partial --controller admin/posts
+  $ rails generate formastic:form Post --partial --controller admin/posts
       exists  app/views/admin/posts
       create  app/views/admin/posts/_form.html.erb
 </pre>
@@ -537,6 +558,7 @@ If you want to add your own input types to encapsulate your own logic or interfa
 
 @Formtastic::SemanticFormHelper.builder = MyCustomBuilder@
 
+
 h2. Security
 
 By default formtastic escapes html entities in both labels and hints unless a string is marked as html_safe. If you are using an older rails version which doesn't know html_safe, or you want to globally turn this feature off, you can set the following in your initializer:
@@ -544,13 +566,6 @@ By default formtastic escapes html entities in both labels and hints unless a st
 Formtastic::SemanticFormBuilder.escape_html_entities_in_hints_and_labels = false
 
 
-h2. Focus
-
-Formtastic 1.0 is compatible with Rails 2.x *only*. We've also been working hard on a Rails 2 *and* 3 compatible version in the rails3 branch, targeting a 1.1 release shortly after Rails 3.0 final ships.
-
-There's heaps more we want to do, but we have to do this first.
-
-
 h2. Dependencies
 
 There are none, but...
@@ -562,8 +577,7 @@ There are none, but...
 
 h2. Compatibility
 
-* We're only testing Formtastic with the latest Rails 2.x stable release. Patches are welcome to allow backwards compatibility with older versions of Rails, of course.
-* Development of a Rails 2 *and* 3 compatible version of Formtastic is underway in the rails3 branch, targeting a Formtastic 1.1 release shortly after Rails 3.0 ships.
+* We're only testing Formtastic with the latest Rails 2.x and 3.x stable releases. Patches are welcome to allow backwards compatibility with older versions of Rails, of course.
 * Formtastic, much like Rails 2, is very ActiveRecord-centric. Many people are using Formtastic (especially the rails3 branch) successfully with other ActiveModel-like ORMs and classes (DataMapper, MongoMapper, Mongoid, Authlogic, Devise...) but we're not guaranteeing anything at this stage. Patches are welcome, but it's not our core focus right now.
  
 
@@ -593,4 +607,4 @@ h2. Project Info
 Formtastic is hosted on Github: "http://github.com/justinfrench/formtastic":http://github.com/justinfrench/formtastic, where your contributions, forkings, comments and feedback are greatly welcomed.
 
 
-Copyright (c) 2007-2008 Justin French, released under the MIT license.
+Copyright (c) 2007-2010 Justin French, released under the MIT license.

data/generators/form/form_generator.rb

@@ -1,41 +1,27 @@
-# coding: utf-8
-# Get current OS - needed for clipboard functionality
-case RUBY_PLATFORM
-when /darwin/ then
-  CURRENT_OS = :osx
-when /win32/
-  CURRENT_OS = :win
-  begin
-    require 'win32/clipboard'
-  rescue LoadError
-    # Do nothing
-  end
-else
-  CURRENT_OS = :x
-end
+# encoding: utf-8
 
 class FormGenerator < Rails::Generator::NamedBase
-  
+
   default_options :haml => false,
                   :partial => false
-  
+
   VIEWS_PATH = File.join('app', 'views').freeze
   IGNORED_COLUMNS = [:updated_at, :created_at].freeze
-  
-  attr_reader   :controller_file_name,
-                :controller_class_path,
-                :controller_class_nesting,
-                :controller_class_nesting_depth,
-                :controller_class_name,
-                :template_type
-                
+
+  attr_reader :controller_file_name,
+              :controller_class_path,
+              :controller_class_nesting,
+              :controller_class_nesting_depth,
+              :controller_class_name,
+              :template_type
+
   def initialize(runtime_args, runtime_options = {})
     super
     base_name, @controller_class_path = extract_modules(@name.pluralize)
     controller_class_name_without_nesting, @controller_file_name = inflect_names(base_name)
     @template_type = options[:haml] ? :haml : :erb
   end
-  
+
   def manifest
     record do |m|
       if options[:partial]
@@ -43,13 +29,13 @@ class FormGenerator < Rails::Generator::NamedBase
         # Ensure directory exists.
         m.directory File.join(VIEWS_PATH, controller_and_view_path)
         # Create a form partial for the model as "_form" in it's views path.
-        m.template "view__form.html.#{template_type}", File.join(VIEWS_PATH, controller_and_view_path, "_form.html.#{template_type}")
+        m.template "_form.html.#{template_type}", File.join(VIEWS_PATH, controller_and_view_path, "_form.html.#{template_type}")
       else
         # Load template file, and render without saving to file
-        template = File.read(File.join(source_root, "view__form.html.#{template_type}"))
+        template = File.read(File.join(source_root, "_form.html.#{template_type}"))
         erb = ERB.new(template, nil, '-')
         generated_code = erb.result(binding).strip rescue nil
-        
+
         # Print the result, and copy to clipboard
         puts "# ---------------------------------------------------------"
         puts "#  GENERATED FORMTASTIC CODE"
@@ -58,63 +44,68 @@ class FormGenerator < Rails::Generator::NamedBase
         puts generated_code || " Nothing could be generated - model exists?"
         puts
         puts "# ---------------------------------------------------------"
-        puts " Copied to clipboard - just paste it!" if save_to_clipboard(generated_code)
+        puts "Copied to clipboard - just paste it!" if save_to_clipboard(generated_code)
       end
     end
   end
-  
+
   protected
-    
-    # Save to lipboard with multiple OS support.
+
     def save_to_clipboard(data)
       return unless data
+
       begin
-        case CURRENT_OS
-        when :osx
-          `echo "#{data}" | pbcopy`
-        when :win
+        case RUBY_PLATFORM
+        when /win32/
+          require 'win32/clipboard'
           ::Win32::Clipboard.data = data
-        else # :linux/:unix
+        when /darwin/ # mac
+          `echo "#{data}" | pbcopy`
+        else # linux/unix
           `echo "#{data}" | xsel --clipboard` || `echo "#{data}" | xclip`
         end
-      rescue
+      rescue LoadError
         false
       else
         true
       end
     end
-    
+
     # Add additional model attributes if specified in args - probably not that common scenario.
     def attributes
       # Get columns for the requested model.
       existing_attributes = @class_name.constantize.content_columns.reject { |column| IGNORED_COLUMNS.include?(column.name.to_sym) }
       @args = super + existing_attributes
     end
-    
+
     def add_options!(opt)
       opt.separator ''
       opt.separator 'Options:'
-      
+
       # Allow option to generate HAML views instead of ERB.
       opt.on('--haml',
         "Generate HAML output instead of the default ERB.") do |v|
         options[:haml] = v
       end
-      
+
       # Allow option to generate to partial in model's views path, instead of printing out in terminal.
       opt.on('--partial',
         "Save generated output directly to a form partial (app/views/{resource}/_form.html.*).") do |v|
         options[:partial] = v
       end
-      
+
       opt.on('--controller CONTROLLER_PATH',
         "Specify a non-standard controller for the specified model (e.g. admin/posts).") do |v|
         options[:controller] = v if v.present?
       end
     end
-    
+
     def banner
       "Usage: #{$0} form ExistingModelName [--haml] [--partial]"
     end
     
-end
+    def source_root
+      File.expand_path('../../../lib/generators/templates', __FILE__)
+    end
+
+end

data/generators/formtastic/formtastic_generator.rb

@@ -1,9 +1,7 @@
+# encoding: utf-8
+
 class FormtasticGenerator < Rails::Generator::Base
-  
-  def initialize(*runtime_args)
-    super
-  end
-  
+
   def manifest
     record do |m|
       m.directory File.join('config', 'initializers')
@@ -14,11 +12,15 @@ class FormtasticGenerator < Rails::Generator::Base
       m.template 'formtastic_changes.css',   File.join('public', 'stylesheets', 'formtastic_changes.css')
     end
   end
-    
+
   protected
-  
+
   def banner
     %{Usage: #{$0} #{spec.name}\nCopies formtastic.css and formtastic_changes.css to public/stylesheets/ and a config initializer to config/initializers/formtastic.rb}
   end
   
-end
+  def source_root
+    File.expand_path('../../../lib/generators/templates', __FILE__)
+  end
+
+end