ShadowBelmolve-formtastic 0.1.6 → 0.2.1

data/README.textile

@@ -1,7 +1,10 @@
-h1. Formtastic 0.1.3
+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.
 
+* This fork: http://github.com/ShadowBelmolve/formtastic
+* Forked from: http://github.com/justinfrench/formtastic/tree/master
+
 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:
@@ -72,6 +75,11 @@ h2. Opinions
 * make the common things we do easy, yet still ensure uncommon things are still possible
 
 
+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. Installation
 
 You can (and should) get it as a gem:
@@ -91,7 +99,7 @@ And then add it as a dependency in your environment.rb file:
 If you're a little more old school, install it as a plugin:
 
 <pre>
-  ./script/plugin install git://github.com/ShadowBelmolve/formtastic.git
+  ./script/plugin install git://github.com/justinfrench/formtastic.git
 </pre>
 
 
@@ -155,48 +163,30 @@ If you want to customize the label text, or render some hint text below the fiel
   <% end %>
 </pre>
 
-If you want to customize html elements for any non button inputs you just need
-to specify the :input_html options hash.
-
-<pre>
-    <% semantic_form_for @post do |form| %>
-      <%= form.input :title, :input_html => {:size => 60} %>
-      <%= form.input :body %>
-      <%= form.input :created_at, :input_html => {:disabled => true} %>
-      <%= form.buttons %>
-    <% end %>
-</pre>
-
-To customize buttons, :button_html is available.
 
 Nested forms (Rails 2.3) are also supported. You can do it in the Rails way:
 
 <pre>
   <% semantic_form_for @post do |form| %>
     <%= form.inputs :title, :body, :created_at %>
-
     <% form.semantic_fields_for :author do |author| %>
       <%= author.inputs :first_name, :last_name, :name => 'Author' %>
     <% end %>
-
     <%= form.buttons %>
   <% end %>
 </pre>
 
-Or in the formtastic way:
+Or the Formtastic way with the @:for@ option:
 
 <pre>
   <% semantic_form_for @post do |form| %>
     <%= form.inputs :title, :body, :created_at %>
-
     <%= form.inputs :first_name, :last_name, :for => :author, :name => "Author" %>
-
     <%= form.buttons %>
   <% end %>
 </pre>
 
-When working in has many association, you can even supply "%i" in your fieldset
-name that it will be properly interpolated with the child index. For example:
+When working in has many association, you can even supply "%i" in your fieldset name that it will be properly interpolated with the child index. For example:
 
 <pre>
   <% semantic_form_for @post do |form| %>
@@ -206,27 +196,180 @@ name that it will be properly interpolated with the child index. For example:
   <% end %>
 </pre>
 
-Each category will be wrapped in a fieldset with legend "Category #1",
-"Category #2" and so on. But please notice that this works only with Rails 2.3.
+
+Customize HTML attributes for any input using the @:input_html@ option.  Typically his 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:
+
+<pre>
+  <% semantic_form_for @post do |form| %>
+    <%= form.input :title,      :input_html => { :size => 60 } %>
+    <%= form.input :body,       :input_html => { :class => 'autogrow' } %>
+    <%= form.input :created_at, :input_html => { :disabled => true } %>
+    <%= form.buttons %>
+  <% end %>
+</pre>
+
+The same can be done for buttons with the @:button_html@ option:
+
+<pre>
+  <% semantic_form_for @post do |form| %>
+    ...
+    <% form.buttons do %>
+      <%= form.commit_button :button_html => { :class => "primary" } %>
+    <% end %>
+  <% 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")
+  
+<pre>
+  <% semantic_form_for @post do |form| %>
+    <%= form.input :title, :wrapper_html => { :class => "important" } %>
+    <%= form.input :body %>
+    <%= form.input :description, :wrapper_html => { :style => "display:none;" } %>
+    ...
+  <% end %>
+</pre>
+
+
 
 h2. The Available Inputs
 
 * :select (a select menu) - default for ActiveRecord associations (belongs_to, has_many, has_and_belongs_to_many)
+* :check_boxes (a set of check_box inputs) - alternative to :select has_many and has_and_belongs_to_many associations
 * :radio (a set of radio inputs) - alternative to :select for ActiveRecord belongs_to associations
+* :time_zone (a select input) - default for :string column types with 'time_zone' in the method name
 * :password (a password input) - default for :string column types with 'password' in the method name
 * :text (a textarea) - default for :text column types
 * :date (a date select) - default for :date column types
 * :datetime (a date and time select) - default for :datetime and :timestamp column types
 * :time (a time select) - default for :time column types
 * :boolean (a checkbox) - default for :boolean column types
-* :boolean_select (a yes/no select box)
 * :string (a text field) - default for :string column types
 * :numeric (a text field, like string) - default for :integer, :float and :decimal column types
 * :file (a file field) - default for paperclip or attachment_fu attributes
-* :check_boxes - alternative to :select when a model has_many :through other
+* :country (a select menu of country names) - default for :string columns named "country", requires a country_select plugin to be installed
+* :hidden (a hidden field) - creates a hidden field (added for compatibility)
+
 
 The documentation is pretty good for each of these (what it does, what the output is, what the options are, etc) so go check it out.
 
+h2. Internationalization (I18n)
+
+Formtastic got some neat I18n-features. ActiveRecord object names and attributes are, by default, taken from calling @object.human_name and @object.human_attribute_name(attr) respectively. There are a few words specific to Formtastic that can be translated. See lib/locale/en.yml for more information.
+
+h3. Label/Hint-localization
+
+Formtastic supports localized *labels* and *hints* using the I18n API for more advanced usage. Your forms can now be DRYer and more flexible than ever, and still fully localized. This is how:
+
+Basic localization (labels only):
+
+<pre>
+  <% semantic_form_for @post do |form| %>
+    <%= form.input :title %>        # => :label => I18n.t('activerecord.attributes.user.title')    or 'Title'
+    <%= form.input :body %>         # => :label => I18n.t('activerecord.attributes.user.body')     or 'Body'
+    <%= form.input :section %>      # => :label => I18n.t('activerecord.attributes.user.section')  or 'Section'
+  <% end %>
+</pre>
+
+*Note:* This is perfectly fine if you just want your labels to be translated using *ActiveRecord I18n attribute translations*, and you don't use input hints. But what if you do? And what if you don't want same labels in all forms?
+
+Enhanced localization (labels and hints):
+
+1. Enable I18n lookups by default (@config/initializers/formtastic.rb@):
+
+<pre>
+  Formtastic::SemanticFormBuilder.i18n_lookups_by_default = true
+</pre>
+
+2. Add some cool label-translations/variants (@config/locale/en.yml@):
+
+<pre>
+  en:
+    formtastic:
+      labels:
+        post:
+          title: "Choose a title..."
+          body: "Write something..."
+      hints:
+        post:
+          title: "Choose a good title for you post."
+          body: "Write something inspiring here."
+</pre>
+
+*Note:* We are using English here still, but you get the point.
+
+3. ...and now you'll get:
+
+<pre>
+  <% semantic_form_for @post do |form| %>
+    <%= form.input :title %>      # => :label => "Choose a title...", :hint => "Choose a good title for you post."
+    <%= form.input :body %>       # => :label => "Write something...", :hint => "Write something inspiring here."
+    <%= form.input :section %>    # => :label => I18n.t('activerecord.attributes.user.section')  or 'Section'
+  <% end %>
+</pre>
+
+4. Override I18n settings:
+
+<pre>
+  <% semantic_form_for @post do |form| %>
+    <%= form.input :title %>      # => :label => "Choose a title...", :hint => "Choose a good title for you post."
+    <%= form.input :body, :hint => false %>     # => :label => "Write something..."
+    <%= form.input :section %>    # => :label => I18n.t('activerecord.attributes.user.section')  or 'Section'
+  <% end %>
+</pre>
+
+If I18n-lookups is disabled, i.e.:
+
+<pre>
+  Formtastic::SemanticFormBuilder.i18n_lookups_by_default = false
+</pre>
+
+...then you can enable I18n within the forms instead:
+
+<pre>
+  <% semantic_form_for @post do |form| %>
+    <%= form.input :title, :label => true %>      # => :label => "Choose a title..."
+    <%= form.input :body, :label => true %>       # => :label => "Write something..."
+    <%= form.input :section, :label => true %>    # => :label => I18n.t('activerecord.attributes.user.section')  or 'Section'
+  <% end %>
+</pre>
+
+5. Advanced I18n lookups
+
+For more flexible forms; Formtastic find translations using a bottom-up approach taking the following variables in account:
+
+* @model@, e.g. "post"
+* @action@, e.g. "edit"
+* @attribute@, e.g. "title"
+
+...in the following order:
+
+1. @formtastic.{labels,hints}.MODEL.ACTION.ATTRIBUTE@       # By model and action
+2. @formtastic.{labels,hints}.MODEL.ATTRIBUTE@              # By model
+3. @formtastic.{labels,hints}.ATTRIBUTE@                    # Global default
+
+...which means that you can define translations like this:
+
+<pre>
+  en:
+    formtastic:
+      labels:
+        title: "Title"  # Default global value
+        article:
+          body: "Article content"
+        post:
+          new:
+            title: "Choose a title..."
+            body: "Write something..."
+          edit:
+            title: "Edit title"
+            body: "Edit body"
+      ...
+</pre>
+
+h2. ValidationReflection plugin
+
+If you have the "ValidationReflection":http://github.com/redinger/validation_reflection plugin installed, you won't have to specify the :required option (it checks the validations on the model instead).
 
 h2. Configuration
 
@@ -270,19 +413,16 @@ If you wish, put something like this in config/initializers/formtastic_config.rb
   # the input, in the following order: hints, input and errors. You can
   # customize it doing just as below:
   Formtastic::SemanticFormBuilder.inline_order = [:hints, :input, :errors]
+  
+  # Set the default "priority countries" to suit your user base when using :as => :country
+  Formtastic::SemanticFormBuilder.priority_countries = ["Australia", "New Zealand"]
+  
+  # Specifies if labels/hints for input fields automatically be looked up using I18n.
+  # Default value: false. Overridden for specific fields by setting value to true,
+  # i.e. :label => true, or :hint => true (or opposite depending on initialized value)
+  # Formtastic::SemanticFormBuilder.i18n_lookups_by_default = false
 </pre>
 
-
-h2. Internationalization (I18n)
-
-Supports I18n! ActiveRecord object names and attributes are, by default, taken from calling @object.human_name and @object.human_attribute_name(attr) respectively. There are a few words specific to Formtastic that can be translated.  See lib/locale/en.yml for more information.
-
-
-h2. ValidationReflection plugin
-
-If you have the "ValidationReflection":http://github.com/redinger/validation_reflection plugin installed, you won't have to specify the :required option (it checks the validations on the model instead).
-
-
 h2. Status
 
 *THINGS ARE GOING TO CHANGE A BIT BEFORE WE HIT 1.0.*
@@ -299,6 +439,7 @@ h2. Dependencies
 There are none, but...
 
 * if you have the "ValidationReflection":http://github.com/redinger/validation_reflection plugin is installed, you won't have to specify the :required option (it checks the validations on the model instead)
+* if you want to use the :country input, you'll need to install the "iso-3166-country-select plugin":http://github.com/rails/iso-3166-country-select (or any other country_select plugin with the same API)
 * rspec, rspec_hpricot_matchers and rcov gems (plus any of their own dependencies) are required for the test suite
 
 
@@ -328,10 +469,8 @@ A proof-of-concept (very much a work-in-progress) stylesheet is provided which y
 
 h2. Contributors
 
-Formtastic wouldn't be as awesome as it is today if it weren't for the wonderful contributions of these fine, fine coders.  An extra huge thanks goes out to "José Valim":http://github.com/josevalim for nearly 50 patches.
+Formtastic is maintained by "Justin French":http://justinfrench.com and "José Valim":http://github.com/josevalim, but it wouldn't be as awesome as it is today if it weren't for the wonderful contributions of these fine, fine coders.
 
-* "Justin French":http://justinfrench.com
-* "José Valim":http://github.com/josevalim
 * "Jeff Smick":http://github.com/sprsquish
 * "Tien Dung":http://github.com/tiendung
 * "Mark Mansour":http://stateofflux.com

data/Rakefile

@@ -20,7 +20,7 @@ begin
     
     s.require_path = 'lib'
     s.autorequire = GEM
-    s.files = %w(MIT-LICENSE README.textile Rakefile) + Dir.glob("{rails,lib,spec}/**/*")
+    s.files = %w(MIT-LICENSE README.textile Rakefile) + Dir.glob("{rails,lib,generators,spec}/**/*")
   end
 rescue LoadError
   puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"

data/generators/formtastic_stylesheets/formtastic_stylesheets_generator.rb

@@ -0,0 +1,21 @@
+class FormtasticStylesheetsGenerator < Rails::Generator::Base
+  
+  def initialize(*runtime_args)
+    super
+  end
+  
+  def manifest
+    record do |m|
+      m.directory File.join('public', 'stylesheets')
+      m.template 'formtastic.css',   File.join('public', 'stylesheets', 'formtastic.css')
+      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/}
+  end
+  
+end

data/generators/formtastic_stylesheets/templates/formtastic.css

@@ -0,0 +1,136 @@
+/* -------------------------------------------------------------------------------------------------
+
+It's *strongly* suggested that you don't modify this file.  Instead, load a new stylesheet after
+this one in your layouts (eg formtastic_changes.css) and override the styles to suit your needs.
+This will allow you to update formtastic.css with new releases without clobbering your own changes.
+
+This stylesheet forms part of the Formtastic Rails Plugin
+(c) 2008 Justin French
+
+--------------------------------------------------------------------------------------------------*/
+
+
+/* NORMALIZE AND RESET - obviously inspired by Yahoo's reset.css, but scoped to just form.formtastic
+--------------------------------------------------------------------------------------------------*/
+form.formtastic, form.formtastic ul, form.formtastic ol, form.formtastic li, form.formtastic fieldset, form.formtastic legend, form.formtastic input, form.formtastic textarea, form.formtastic select, form.formtastic p { margin:0; padding:0; }
+form.formtastic fieldset { border:0; }
+form.formtastic em, form.formtastic strong { font-style:normal; font-weight:normal; }
+form.formtastic ol, form.formtastic ul { list-style:none; }
+form.formtastic abbr, form.formtastic acronym { border:0; font-variant:normal; }
+form.formtastic input, form.formtastic textarea, form.formtastic select { font-family:inherit; font-size:inherit; font-weight:inherit; }
+form.formtastic input, form.formtastic textarea, form.formtastic select { font-size:100%; }
+form.formtastic legend { color:#000; }
+
+
+/* FIELDSETS & LISTS
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset { }
+form.formtastic fieldset.inputs { }
+form.formtastic fieldset.buttons { padding-left:25%; }
+form.formtastic fieldset ol { }
+form.formtastic fieldset.buttons li { float:left; padding-right:0.5em; }
+
+/* clearfixing the fieldsets */
+form.formtastic fieldset { display: inline-block; }
+form.formtastic fieldset:after { content: "."; display: block; height: 0; clear: both; visibility: hidden; }
+html[xmlns] form.formtastic fieldset { display: block; }
+* html form.formtastic fieldset { height: 1%; }
+
+
+/* INPUT LIs
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li { margin-bottom:1.5em; }
+
+/* clearfixing the li's */
+form.formtastic fieldset ol li { display: inline-block; }
+form.formtastic fieldset ol li:after { content: "."; display: block; height: 0; clear: both; visibility: hidden; }
+html[xmlns] form.formtastic fieldset ol li { display: block; }
+* html form.formtastic fieldset ol li { height: 1%; }
+
+form.formtastic fieldset ol li.required { }
+form.formtastic fieldset ol li.optional { }
+form.formtastic fieldset ol li.error { }
+  
+
+/* LABELS
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li label { display:block; width:25%; float:left; padding-top:.2em; }
+form.formtastic fieldset ol li li label { line-height:100%; padding-top:0; }
+form.formtastic fieldset ol li li label input { line-height:100%; vertical-align:middle; margin-top:-0.1em;}
+
+
+/* NESTED FIELDSETS AND LEGENDS (radio, check boxes and date/time inputs use nested fieldsets)
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li fieldset { position:relative; }
+form.formtastic fieldset ol li fieldset legend { position:absolute; width:25%; padding-top:0.1em; }
+form.formtastic fieldset ol li fieldset legend span { position:absolute; }
+form.formtastic fieldset ol li fieldset ol { float:left; width:74%; margin:0; padding:0 0 0 25%; }
+form.formtastic fieldset ol li fieldset ol li { padding:0; border:0; }
+
+
+/* INLINE HINTS
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li p.inline-hints { color:#666; margin:0.5em 0 0 25%; }
+
+
+/* INLINE ERRORS
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li p.inline-errors { color:#cc0000; margin:0.5em 0 0 25%; }
+form.formtastic fieldset ol li ul.errors { color:#cc0000; margin:0.5em 0 0 25%; list-style:square; }
+form.formtastic fieldset ol li ul.errors li { padding:0; border:none; display:list-item; }
+
+
+/* STRING & NUMERIC OVERRIDES
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li.string input { width:74%; }
+form.formtastic fieldset ol li.numeric input { width:74%; }
+
+
+/* TEXTAREA OVERRIDES
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li.text textarea { width:74%; }
+
+
+/* HIDDEN OVERRIDES
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li.hidden { display:none; }
+
+
+/* BOOLEAN OVERRIDES
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li.boolean label { padding-left:25%; width:auto; }
+form.formtastic fieldset ol li.boolean label input { margin:0 0.5em 0 0.2em; }
+
+
+/* RADIO OVERRIDES
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li.radio { }
+form.formtastic fieldset ol li.radio fieldset ol { margin-bottom:-0.6em; }
+form.formtastic fieldset ol li.radio fieldset ol li { margin:0.1em 0 0.5em 0; }
+form.formtastic fieldset ol li.radio fieldset ol li label { float:none; width:100%; }
+form.formtastic fieldset ol li.radio fieldset ol li label input { margin-right:0.2em; }
+
+
+/* CHECK BOXES (COLLECTION) OVERRIDES
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li.check_boxes { }
+form.formtastic fieldset ol li.check_boxes fieldset ol { margin-bottom:-0.6em; }
+form.formtastic fieldset ol li.check_boxes fieldset ol li { margin:0.1em 0 0.5em 0; }
+form.formtastic fieldset ol li.check_boxes fieldset ol li label { float:none; width:100%; }
+form.formtastic fieldset ol li.check_boxes fieldset ol li label input { margin-right:0.2em; }
+
+
+
+/* DATE & TIME OVERRIDES
+--------------------------------------------------------------------------------------------------*/
+form.formtastic fieldset ol li.date fieldset ol li,
+form.formtastic fieldset ol li.time fieldset ol li,
+form.formtastic fieldset ol li.datetime fieldset ol li { float:left; width:auto; margin:0 .3em 0 0; }
+
+form.formtastic fieldset ol li.date fieldset ol li label,
+form.formtastic fieldset ol li.time fieldset ol li label,
+form.formtastic fieldset ol li.datetime fieldset ol li label { display:none; }
+
+form.formtastic fieldset ol li.date fieldset ol li label input, 
+form.formtastic fieldset ol li.time fieldset ol li label input, 
+form.formtastic fieldset ol li.datetime fieldset ol li label input { display:inline; margin:0; padding:0;  }