Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

big update to the README

  • Loading branch information...
commit 2d4a72b4a3e391135d4c06edc22758d6118909b0 1 parent 686ff3c
@justinfrench authored
Showing with 67 additions and 74 deletions.
  1. +67 −74 README.textile
View
141 README.textile
@@ -4,7 +4,7 @@ Formtastic is a Rails FormBuilder DSL (with some other goodies) to make it far e
h2. The Story
-Hacked together forms were easy, but awesome forms with decent semantics, rich mark-up and plenty of CSS hooks were incredibly painful. I was discouraged from doing things properly because it was too much mark-up and code to write. 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:
+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:
<pre>
<% semantic_form_for @article do |form| %>
@@ -71,15 +71,7 @@ h2. The Available Inputs
The documentation is pretty good for each of these (what it does, what the output is, etc) so go check it out.
-h3. One day...
-
-* calendars and other more humanized date/time selections
-* flash-based multi-file selection
-* an interface for tagging and other has_many_through style associations
-
-In the meantime, there's nothing stopping you from mixing some old fashioned HTML and ERB for custom widgets in with the Formtastic DLS stuff in your views, and I'd love to hear what others are finding a need for.
-
-h3. Fields without database columns
+h3. Fields without database columns and non-ActiveRecord objects
Formtastic is pretty tightly coupled to ActiveRecord database columns, but it will at least _attempt_ to play nicely with your models other methods (like a virtual column 'full_name' which is split into first_name and last_name in a before save callback), and I'd like this to continue and improve.
@@ -89,39 +81,51 @@ h2. Configuration
If you wish, put something like this in config/initializers/formtastic_config.rb:
<pre>
+ # Should all fields be considered "required" by default
+ # Defaults to true, see ValidationReflection notes below
Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
+
+ # Set the string that will be appended to the labels/fieldsets which are required
+ # Default is '<abbr title="required">*</abbr>'
Formtastic::SemanticFormBuilder.required_string = "(required)"
+
+ # Set the string that will be appended to the labels/fieldsets which are optional
+ # Defaults to an empty string ("")
Formtastic::SemanticFormBuilder.optional_string = "(optional)"
- # Set the way inline errors will be displayed. Valid options are :sentence, :list and :none
- Formtastic::SemanticFormBuilder.inline_errors = :sentence
+ # Set the way inline errors will be displayed.
+ # Defaults to :string, valid options are :sentence, :list and :none
+ Formtastic::SemanticFormBuilder.inline_errors = :list
- # Set the method called on label text to determine its format (:titleize, :humanize, :to_s, etc)
+ # Set the method to call on label text to transform or format it for human-friendly reading
+ # Defaults to :titleize, but you might want :humanize, :to_s, etc
Formtastic::SemanticFormBuilder.label_str_method = :titleize
- # Set the possible methods to be called for label text
- # Whichever method is found first on the object will be used to set the text of the label for that object
- # So in the following object:
- # class User
- # def full_name; end
- # def title; end
- # end
- # The #full_name method will determine what shows up in the label
- Formtastic::SemanticFormBuilder.collection_label_methods = %w[to_label display_name full_name name title username login value to_s]
+ # Set the array of methods to try calling on parent objects in :select and :radio inputs
+ # for the text inside each @<option>@ tag or alongside each radio @<input>@. The first method
+ # that is found on the object will be used.
+ # Defaults to ["to_label", "display_name", "full_name", "name", "title", "username", "login", "value", "to_s"]
+ Formtastic::SemanticFormBuilder.collection_label_methods = ["title_and_author", "display_name", "login", "to_s"]
</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. Status
-*THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A BIT.*
+*THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A BIT BEFORE WE HIT 1.0.*
-It's incredibly opinionated, incomplete, a work in progress, messy around the edges, messy in the middle too, tightly coupled to the database, tightly coupled to "my way" of doing things and has an incomplete (but fast-growing) test suite, but I hope you try it and offer some suggestions and improvements any way.
+It's opinionated, incomplete, a work in progress and a bit rough around the edges stiull, but I hope you try it and offer some suggestions and improvements any way.
+
+On the plus side, it has a comprehensive spec suite and contributions from at least ten independent developers.
h2. Roadmap to 1.0
-"Wishlist":http://wiki.github.com/justinfrench/formtastic/wishlist on the GitHub wiki is serving as pretty good documentation for the roadmap to 1.0 and beyond right now, but I'll work on getting a real tracking system or something happening soon.
+"Wishlist":http://wiki.github.com/justinfrench/formtastic/wishlist on the wiki is serving as pretty good documentation for the roadmap to 1.0 and beyond right now, but I'll work on getting a real tracking system or something happening soon.
h2. Usage
@@ -141,7 +145,7 @@ The smallest example:
<% end %>
</pre>
-Yes, it'll even handle belongs_to associations, rendering a radio list or select box with the right set of choices! The output is something like:
+Yes, *it'll even handle belongs_to associations*, rendering a radio list or select box with the right set of choices! The output is something like:
<pre>
<form action="/posts" class="formtastic new_post" id="new_post" method="post">
@@ -205,6 +209,7 @@ 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. Nested forms (Rails 2.3+)
Nested forms are supported:
@@ -218,6 +223,7 @@ Nested forms are supported:
<% end %>
</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.
@@ -225,72 +231,60 @@ Supports I18n! ActiveRecord object names and attributes are, by default, taken f
Here is an example locale file:
<pre>
-en:
- formtastic:
- yes: 'Yes'
- no: 'No'
- create: 'Create'
- save: 'Save'
- year: 'Year'
- month: 'Month'
- day: 'Day'
- hour: 'Hour'
- minute: 'Minute'
- second: 'Second'
+ en:
+ formtastic:
+ yes: 'Yes'
+ no: 'No'
+ create: 'Create'
+ save: 'Save'
+ year: 'Year'
+ month: 'Month'
+ day: 'Day'
+ hour: 'Hour'
+ minute: 'Minute'
+ second: 'Second'
</pre>
+
h2. Extending Formtastic
Adding functionality to Formtastic can be done by extending SemanticFormBuilder and configuring formtastic's builder.
-To create a new form method that displayed a star rating define the new Formtastic form builder by subclassing SemanticFormBuilder:
+To create a new form method that displayed a star rating define the new builder by subclassing SemanticFormBuilder:
<pre>
-# RAILS_ROOT/lib/rating_semantic_form_builder.rb
-class RatingSemanticFormBuilder < Formtastic::SemanticFormBuilder
- # new method to be added allowing full control over the label and value
- def rating(stars, options = {})
- options[:label] ||= 'rating'
- content = input_label(options[:label], options)
- content += @template.content_tag(:span, '*' * stars.to_i, :id => "#{@object_name}_#{options[:label]}")
- @template.content_tag(:li, content)
+ # lib/rating_semantic_form_builder.rb
+ class RatingBuilder < Formtastic::SemanticFormBuilder
+ # new method to be added allowing full control over the label and value
+ def rating(stars, options = {})
+ options[:label] ||= 'rating'
+ content = input_label(options[:label], options)
+ content += @template.content_tag(:span, '*' * stars.to_i, :id => "#{@object_name}_#{options[:label]}")
+ @template.content_tag(:li, content)
+ end
end
-end
</pre>
-Set Formtastic's builder to your newly defined RatingSemanticFormBuilder
+Set Formtastic's builder to your newly defined RatingBuilder
<pre>
-# RAILS_ROOT/config/initializers/override_formtastic_builder.rb
-
-require 'rating_semantic_form_builder.rb'
-
-# set the formtastic builder to a customized version of the formtastic builder
-Formtastic::SemanticFormHelper.builder = RatingSemanticFormBuilder
+ # RAILS_ROOT/config/initializers/override_formtastic_builder.rb
+ require 'rating_semantic_form_builder.rb'
+
+ # set the formtastic builder to a customized version of the formtastic builder
+ Formtastic::SemanticFormHelper.builder = RatingBuilder
</pre>
-Use your newly created formtastic method
+Use @semantic_form_for@ just like you would with Formtastic.
<pre>
<% semantic_form_for Project.new do |form| %>
<% form.input_field_set :name => "ratings" do %>
<%= form.rating 5 %>
<%= form.rating 11, :label => 'awesomeness (out of 10)' %>
<% end %>
+ <%= form.buttons %>
<% end %>
</pre>
-h2. Conventions & Prerequisites
-
-In a few places (like radio or select widgets for belongs_to associations) Formtastic expects your ActiveRecord instances to respond to the <code>to_label</code> or <code>to_s</code> method (returning a String). You can easily add this to your models: For example, a User object might want to return the user's first name, last name and login:
-
-<pre>
-class User < ActiveRecord::Base
- #...
- def to_label
- "#{first_name} #{last_name} (#{login})"
- end
-end
-</pre>
-
h2. Dependencies
@@ -321,18 +315,16 @@ A proof-of-concept (very much a work-in-progress) stylesheet is provided which y
h2. Compatibility
-I'm only testing Formtastic with the latest Rails 2.2.x stable release.
+I'm only testing Formtastic with the latest Rails 2.2.x stable release, and it should be fine under Rails 2.3 as well (including nested forms).
h2. But it doesn't do that thing I really need!
-Oh noes! It might not ever do it either. We'll see. This is not a silver bullet. I want to make the usual stuff easy, and the unusual stuff possible. That might mean that some of the inputs on your form still have to be hard-coded, but some is better than all, right?
+It might not ever do it either, there are no silver bullets. I want to make the usual stuff easy, and the unusual stuff possible. That might mean that some of the inputs on your form still have to be hard-coded, but some is better than all, right?
-I really hope the plugin will soon be clean and extensible enough to invite others to contribute more complex input types (calendars, etc) to the core.
-
-h2. Contributors
+h2. Many thanks to Formtastic's contributors
* "Justin French":http://justinfrench.com
* "Xavier Shay":http://rhnh.net
@@ -346,6 +338,7 @@ h2. Contributors
* "Sascha Hoellger":http://github.com/mitnal
* "Jeff Smick":http://github.com/sprsquish
+
h2. Project Info
Formtastic is hosted on Github: http://github.com/justinfrench/formtastic/, where your contributions, forkings, comments and feedback are greatly welcomed.
Please sign in to comment.
Something went wrong with that request. Please try again.