README.textile in nofxx-formtastic-0.1.8 vs README.textile in nofxx-formtastic-0.1.9
- old
+ new
@@ -1,6 +1,6 @@
-h1. Formtastic 0.1.4
+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.
h2. Warning
@@ -87,12 +87,11 @@
And then add it as a dependency in your environment.rb file:
<pre>
config.gem "justinfrench-formtastic",
:lib => 'formtastic',
- :source => 'http://gems.github.com',
- :version => '0.1.4'
+ :source => 'http://gems.github.com'
</pre>
If you're a little more old school, install it as a plugin:
<pre>
@@ -101,11 +100,11 @@
h2. Usage
Forms are really boring to code... you want to get onto the good stuff as fast as possible.
-This renders a set of inputs (one for _most_ columns in the database table, and one for each ActiveRecord belongs_to, has_many or has_and_belongs_to_many association) and a submit button:
+This renders a set of inputs (one for _most_ columns in the database table, and one for each ActiveRecord belongs_to association), followed by a submit button:
<pre>
<% semantic_form_for @user do |form| %>
<%= form.inputs %>
<%= form.buttons %>
@@ -136,11 +135,11 @@
<%= form.commit_button %>
<% end %>
<% end %>
</pre>
-If you want to customize the label text, or render some hint text below the field, specify which fields are required/option, or break the form into two fieldsets, the DSL is pretty comprehensive:
+If you want to customize the label text, or render some hint text below the field, specify which fields are required/optional, or break the form into two fieldsets, the DSL is pretty comprehensive:
<pre>
<% semantic_form_for @post do |form| %>
<% form.inputs :name => "Basic", :id => "basic" do %>
<%= form.input :title %>
@@ -157,79 +156,99 @@
<%= form.commit_button %>
<% end %>
<% end %>
</pre>
-If you want to customize html elements for any non button inputs and the li
-wrapper you just need to specify the :input_html and :wrapper_html options hash.
-
-<pre>
- <% semantic_form_for @post do |form| %>
- <%= form.input :title, :input_html => {:size => 60} %>
- <%= form.input :body, :wrapper_html => { :class => 'body_wrapper' } %>
- <%= 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| %>
<%= form.inputs %>
<%= form.inputs :name => 'Category #%i', :for => :categories %>
<%= form.buttons %>
<% 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
+* :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. Configuration
@@ -271,10 +290,13 @@
# Formtastic by default renders inside li tags the input, hints and then
# errors messages. Sometimes you want the hints to be rendered first than
# 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"]
</pre>
h2. Internationalization (I18n)
@@ -300,10 +322,11 @@
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
h2. Compatibility
@@ -329,13 +352,11 @@
</pre>
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
* "Andy Pearson":http://github.com/andypearson
* "negonicrac":http://github.com/negonicrac