simple_form 1.5.2 → 2.0.0.rc

data/CHANGELOG.md

@@ -0,0 +1,224 @@
+## 2.0.0.rc
+
+### enhancements
+  * Add `button_class` configuration to change the class of buttons. ([@sryche](https://github.com/sryche))
+  * Add `disabled` class to a disabled input.
+  * Generate configuration file with `browser_validations` disabled.
+  * Add option and configuration to specify the collection wrapper class. ([@mfila](https://github.com/mfila))
+  * Add proc support to `collection` option. ([@jeffkreeftmeijer](https://github.com/jeffkreeftmeijer))
+  * `simple_form_for` allows default options for its inputs `:defaults => {}`.
+  * Add `readonly` as option of input method. ([@Untainted123](https://github.com/Untainted123))
+  * `simple_fields_for` for inherits wrapper option form the form builder. ([@nashby](https://github.com/nashby))
+  * Deprecated part of the old configuration API in favor of the wrapper API which allows you to customize your inputs
+    in a more flexible way. See [this guide](https://github.com/plataformatec/simple_form/wiki/Upgrading-to-Simple-Form-2.0)
+    to know how upgrade.
+  * Use action prefix in the form css class. Closes [#360](https://github.com/plataformatec/simple_form/issues/360).
+    This is not backward compatible with the previous versions of SimpleForm.
+    For more informations see [this comment](https://github.com/plataformatec/simple_form/issues/360#issuecomment-3000780).
+    ([@nashby](https://github.com/nashby))
+  * Add a readonly component that does automatically readonly lookup from object
+  * Add support for proc or lambda as option for format validator ([@nashby](https://github.com/nashby))
+  * Handle validates_length_of :is option in maxlength ([@nashby](https://github.com/nashby))
+  * Add field_with_hint css class to the wrapper when the input has a hint, similar to field_with_errors ([@nashby](https://github.com/nashby))
+  * Add :grouped_select input type, mapping to Rails grouped_collection_select helper ([@semaperepelitsa](https://github.com/semaperepelitsa))
+  * Add automatic translation of options for collection inputs given a collection of symbols ([@klobuczek](https://github.com/klobuczek))
+  * Add `:boolean_style` config to change how check boxes and radios will be displayed.
+    Options are `:inline = input + label` (default) and `:nested = label > input`.
+  * Add possibility to give a block to `collection_radio` and `collection_check_boxes`,
+    to generate custom label and input structure. It is used internally with the :nested
+    option for `:boolean_style`, and is useful to allow some more customization if required.
+  * Do not generate hidden check box field when using nested boolean style, as it is considered
+    invalid markup in HTML5. This will work by default in Rails > 3.2.1 (not released at this time),
+    and is backported inside SimpleForm builder extensions.
+    More info in [#215](https://github.com/plataformatec/simple_form/issues/215)
+  * Add `item_wrapper_class` configuration option for collection radio buttons / check boxes inputs.
+
+### deprecation
+  * Deprecate the `translate` configuration in favor of `translate_labels`
+  * Deprecate the `html5` configuration in favor of a new `html5` component
+  * Deprecate `:radio` input type in favor of `:radio_buttons`
+  * Deprecate `collection_radio` form helper in favor of `collection_radio_buttons`
+    (the label class has changed as well)
+
+### bug fix
+  * Fix i18n lookup with attributes with same name of models.
+    Closes [#149](https://github.com/plataformatec/simple_form/issues/149)
+    and [#364](https://github.com/plataformatec/simple_form/issues/364).
+    ([@nashby](https://github.com/nashby) and [@MarceloCajueiro](https://github.com/MarceloCajueiro))
+  * Do not generate `for` attribute for the collection label when it is a checkbox or radio.
+    Closes [#344](https://github.com/plataformatec/simple_form/issues/344).
+    ([@nashby](https://github.com/nashby) and [@mfila](https://github.com/mfila))
+  * Select can have required option when the `:include_blank` option is passed.
+    Closes [#340](https://github.com/plataformatec/simple_form/issues/340). ([@nashby](https://github.com/nashby))
+  * `:checked` option should override the existing associations on `collection_check_boxes`.
+    Closes [#341](https://github.com/plataformatec/simple_form/issues/341). ([@nashby](https://github.com/nashby))
+  * Move default attribute translations out of root - use "defaults" key instead
+    Closes [#384](https://github.com/plataformatec/simple_form/issues/384). ([@fringd](https://github.com/fringd))
+
+## 1.5.2
+
+### bug fix
+  * Remove the internal usage of deprecated `:components`
+
+## 1.5.1
+
+### deprecation
+  * `:components` options is now deprecated
+
+### bug fix
+  * Fallback to default label when block is provided. ([@pivotal-casebook](https://github.com/pivotal-casebook))
+  * Do not override default selection through attribute value in collection select when label/value methods are lambdas.
+
+## 1.5.0
+
+### enhancements
+  * Simplified generator by using directory action. ([@rupert654](https://github.com/rupert654))
+  * Support for `maxlength` on string inputs inferred from validation. ([@srbartlett](https://github.com/srbartlett))
+  * Change form css class handling to only add the dom class when one is not given to the form call.
+    ([@patrick99e99](https://github.com/patrick99e99))
+  * Support for required attributes when action validations are present. ([@csegura](http://github.com/csegura))
+  * Do not generate `size` attribute for numeric input. ([@csegura](https://github.com/jasonmp85))
+  * Support for `maxlength` on text area inputs inferred from validation.
+  * Support for `pattern` on text field inferred from validation when `:pattern` is true.
+  * Break Text, Password and File into their own inputs.
+  * Support easy enabling and disabling of components for specific inputs.
+  * Add HTML5 range input.
+
+### bug fix
+  * Fix bug when `simple_fields_for` is used with a hash like models and Rails 3.1.
+  * Fix bug that does not remove the `:item_wrapper_tag` or the `:collection_wrapper_tag` on collection
+    inputs when nil or false value is passed to these options. ([@dw2](https://gitbub.com/dw2))
+  * Fix bug that disable the entire select and wrapper when `disabled` option is a string or array.
+  * Fix bug when using label/value methods as procs together with disabled/selected options as procs for select inputs.
+
+## 1.4.2
+
+### enhancements
+  * Rails 3.1 support.
+
+## 1.4.1
+
+### enhancements
+  * ignore required attribute when conditional validations are present.
+
+### bug fix
+  * Do not use `required='required'` when browser validations are turned off.
+  * Sanitize HMTL attributes in error and hint helpers when options are present.
+  * Improve i18n lookup by ignoring explicit child index given to form builder.
+    (tests by [@rywall](https://github.com/rywall))
+  * Fixes the form specific validation option if specified on the form itself. ([@medihack](https://github.com/medihack))
+
+## 1.4.0
+
+### enhancements
+  * Add label class configuration option. ([@reu](http://github.com/reu))
+  * Improve i18n lookup (labels/hints/placeholders) for nested models.
+  * Use the given custom builder with `simple_fields_for`. ([@giniedp](https://github.com/giniedp))
+  * Add slim form generator. ([@fagiani](https://github.com/fagiani))
+  * Add `form_class` configuration option. ([@fagiani](https://github.com/fagiani))
+  * Default step of `any` for number input with non integer attributes. ([@fedesoria](https://github.com/fedesoria))
+  * Add option to disable HTML5 browser validations on all forms. ([@coryschires](https://github.com/coryschires))
+  * Add option to disable all HTML5 extensions. ([@wolframarnold](https://github.com/wolframarnold))
+  * Add `input_field` helper to form builder. ([@jeroenhouben](https://github.com/jeroenhouben))
+  * Allow inputs to be discovered on demand by placing them at app/inputs (a la formtastic).
+  * Add `full_error` on that shows the error with the attribute name.
+
+### bug fix
+  * Fix for file attributes automatic detection, to work with virtual attributes.
+  * Fix for numeric fields validation options using symbols and procs.
+  * Fix password attributes to add `size` and `maxlength` options the same way as string. ([@fedesoria](https://github.com/fedesoria))
+  * Fix bug with custom form builders and new mappings being added to the superclass builder. ([@rdvdijk](https://github.com/rdvdijk))
+  * Fix HTML validation issue with `collection_check_boxes`.
+
+## 1.3.1
+
+### enhancements
+  * Add `:autofocus` HTML5 attribute support. ([@jpzwarte](https://github.com/jpzwarte))
+  * Add possibility to specify custom builder and inherit mappings. ([@rejeep](https://github.com/rejeep))
+  * Make custom mappings work with all attributes types. ([@rafaelfranca](https://github.com/rafaelfranca))
+  * Add support for procs/lambdas in text/value methods for `collection_select`.
+
+### deprecation
+  * removed the deprecated `:remote_form_for`
+
+### bug fix
+  * Only add the `required` HTML 5 attribute for valid inputs, disable in selects (not allowed).
+  * Fix error when using hints without an attribute.
+    ([@butsjoh](https://github.com/butsjoh) and [@rafaelfranca](https://github.com/rafaelfranca))
+  * Fix messy html output for hint, error and label components.
+    ([@butsjoh](https://github.com/butsjoh) and [@rafaelfranca](https://github.com/rafaelfranca))
+  * Allow direct setting of for attribute on label. ([@Bertg](https://github.com/Bertg))
+
+## 1.3.0
+
+### enhancements
+  * Allow collection input to accept a collection of symbols.
+  * Add default css class to button.
+  * Allow forms for objects that do not respond to the `errors` method.
+  * `collection_check_boxes` and `collection_radio` now wrap the input in the label.
+  * Automatic add min/max values for numeric attributes based on validations and step for integers - HTML5.
+    ([@dasch](https://github.com/dasch))
+  * Add `:placeholder` option for string inputs, allowing customization through I18n - HTML5.
+    ([@jonathan](https://github.com/jonathan))
+  * Add `:search` and `:tel` input types, with `:tel` mapping automatically from attributes matching "phone" - HTML5.
+  * Add `:required` html attribute for required inputs - HTML5.
+  * Add optional `:components` option to input to control component rendering. ([@khoan](https://github.com/khoan))
+  * Add `SimpleForm.translate` as an easy way to turn off SimpleForm internal translations.
+  * Add `:disabled` option for all inputs. ([@fabiob](https://github.com/fabiob))
+  * Add collection wrapper tag and item wrapper tag to wrap elements in collection helpers - radio / check boxes.
+  * Add `SimpleForm.input_mappings` to allow configuring custom mappings for inputs. ([@TMaYaD](https://github.com/TMaYaD))
+
+### bug fix
+  * Search for validations on both association and attribute.
+  * Use `controller.action_name` to lookup action only when available, to fix issue with Rspec views tests.
+    ([@rafaelfranca](https://github.com/rafaelfranca))
+
+## 1.2.2
+
+### enhancements
+  * Compatibility with Rails 3 RC.
+
+## 1.2.1
+
+### enhancements
+  * Added haml generator support. ([@grimen](https://github.com/grimen))
+  * Added `error_notification` message to form builder.
+  * Added required by default as configuration option.
+  * Added `label_input` as component, allowing boolean to change its order (input appearing first than label).
+  * Added `error_method` to tidy up how errors are exhibited.
+  * Added error class on wrappers. ([@jduff](https://github.com/jduff))
+  * Changed numeric types to have `type=number` for HTML5.
+
+## 1.2.0
+
+### deprecation
+  * Changed `simple_form_install` generator to `simple_form:install`.
+
+### enhancements
+  * Added support to presence validation to check if attribute is required or not. ([@gcirne](https://github.com/gcirne))
+  * Added `input` as class to wrapper tag.
+  * Added config options for hint and error tags. ([@tjogin](https://github.com/tjogin))
+
+## 1.1.3
+
+### deprecation
+  * removed `:conditions`, `:order`, `:joins` and `:include` support in `f.association`.
+
+## 1.1.2
+
+### bug fix
+  * Ensure type is set to "text" and not "string".
+
+## 1.1.1
+
+### bug fix
+  * Fix some escaping issues.
+
+## 1.1.0
+
+### enhancements
+  * Rails 3 support with generators, templates and HTML 5.
+
+## 1.0
+
+* First release.

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 PlataformaTec http://blog.plataformatec.com.br/
+Copyright (c) 2012 PlataformaTec http://blog.plataformatec.com.br/
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,817 @@
+# SimpleForm - Rails forms made easy.
+[![Build Status](https://secure.travis-ci.org/plataformatec/simple_form.png)](http://travis-ci.org/plataformatec/simple_form)
+
+**SimpleForm** aims to be as flexible as possible while helping you with powerful components to create
+your forms. The basic goal of simple form is to not touch your way of defining the layout, letting
+you find the better design for your eyes. Most of the DSL was inherited from Formtastic,
+which we are thankful for and should make you feel right at home.
+
+INFO: This README is [also available in a friendly navigable format](http://simple-form.plataformatec.com.br/).
+
+## Installation
+
+Add it to your Gemfile:
+
+`gem 'simple_form'`
+
+Run the following command to install it:
+
+`bundle install`
+
+Run the generator:
+
+`rails generate simple_form:install`
+
+Also, if you want to use the country select, you will need the
+[country_select gem](https://rubygems.org/gems/country_select), add it to your Gemfile:
+
+`gem 'country_select'`
+
+And you are ready to go. Since this branch aims Rails 3 support, if you want to use it with
+Rails 2.3 you should check this branch:
+
+`http://github.com/plataformatec/simple_form/tree/v1.0`
+
+## Configuration
+
+**SimpleForm** has several configuration options. You can read and change them in the initializer
+created by **SimpleForm**, so if you haven't executed the command below yet, please do:
+
+`rails generate simple_form:install`
+
+### Twitter Bootstrap
+
+**SimpleForm** 2.0 can be easily integrated to the [Twitter Bootstrap](http://twitter.github.com/bootstrap).
+To do that you have to use the `bootstrap` option in the install generator, like this:
+
+`rails generate simple_form:install --bootstrap`
+
+You have to be sure that you added a copy of the [Twitter Bootstrap](http://twitter.github.com/bootstrap)
+assets on your application.
+
+For more information see the generator output, our
+[example application code](https://github.com/rafaelfranca/simple_form-bootstrap) and
+[the live example app](http://simple-form-bootstrap.plataformatec.com.br/).
+
+**NOTE**: **SimpleForm** integration requires Twitter Bootstrap version 2.0 or higher.
+
+### The wrappers API
+
+With **SimpleForm** you can configure how your components will be rendered using the wrappers API.
+The syntax looks like this:
+
+```ruby
+config.wrappers :tag => :div, :class => :input,
+                :error_class => :field_with_errors do |b|
+
+  # Form extensions
+  b.use :html5
+  b.optional :pattern
+  b.use :maxlength
+  b.use :placeholder
+  b.use :readonly
+
+  # Form components
+  b.use :label_input
+  b.use :hint,  :tag => :span, :class => :hint
+  b.use :error, :tag => :span, :class => :error
+end
+```
+
+The _Form components_ will generate the form tags like labels, inputs, hints or errors contents.
+
+The _Form extensions_ are used to generate some attributes or perform some lookups on the model to
+add extra information to your components.
+
+You can create new _Form components_ using the wrappers API as in the following example:
+
+```ruby
+config.wrappers do |b|
+  b.use :placeholder
+  b.use :label_input
+  b.use :tag => :div, :class => 'separator' do |component|
+    component.use :hint,  :tag => :span, :class => :hint
+    component.use :error, :tag => :span, :class => :error
+  end
+end
+```
+
+this will wrap the hint and error components within a `div` tag using the class `'separator'`.
+
+If you want to customize the custom _Form components_ on demand you can give it a name like this:
+
+```ruby
+config.wrappers do |b|
+  b.use :placeholder
+  b.use :label_input
+  b.use :my_wrapper, :tag => :div, :class => 'separator' do |component|
+    component.use :hint,  :tag => :span, :class => :hint
+    component.use :error, :tag => :span, :class => :error
+  end
+end
+```
+
+and now you can pass options to your `input` calls to customize the `:my_wrapper` _Form component_.
+
+```ruby
+# Completely turns off the custom wrapper
+f.input :name, :my_wrapper => false
+
+# Configure the html
+f.input :name, :my_wrapper_html => { :id => 'special_id' }
+
+# Configure the tag
+f.input :name, :my_wrapper_tag => :p
+```
+
+You can also define more than one wrapper and pick one to render in a specific form or input.
+To define another wrapper you have to give it a name, as the follow:
+
+```ruby
+config.wrappers :small do |b|
+  b.use :placeholder
+  b.use :label_input
+end
+```
+
+and use it in this way:
+
+```ruby
+# Specifying to whole form
+simple_form_for @user, :wrapper => :small do |f|
+  f.input :name
+end
+
+# Specifying to one input
+simple_form_for @user do |f|
+  f.input :name, :wrapper => :small
+end
+```
+
+**SimpleForm** also allows you to use optional elements. For instance, let's suppose you want to use
+hints or placeholders, but you don't want them to be generated automatically. You can set their
+default values to `false` or use the `optional` method. Is preferible to use the `optional` syntax:
+
+```ruby
+config.wrappers :placeholder => false do |b|
+  b.use :placeholder
+  b.use :label_input
+  b.use :tag => :div, :class => 'separator' do |component|
+    component.optional :hint, :tag => :span, :class => :hint
+    component.use :error, :tag => :span, :class => :error
+  end
+end
+```
+
+By setting it as `optional`, a hint will only be generated when `:hint => true` is explicitly used.
+The same for placehold.
+
+## Usage
+
+**SimpleForm** was designed to be customized as you need to. Basically it's a stack of components that
+are invoked to create a complete html input for you, which by default contains label, hints, errors
+and the input itself. It does not aim to create a lot of different logic from the default Rails
+form helpers, as they do a great work by themselves. Instead, **SimpleForm** acts as a DSL and just
+maps your input type (retrieved from the column definition in the database) to an specific helper method.
+
+To start using **SimpleForm** you just have to use the helper it provides:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username %>
+  <%= f.input :password %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+This will generate an entire form with labels for user name and password as well, and render errors
+by default when you render the form with invalid data (after submitting for example).
+
+You can overwrite the default label by passing it to the input method. You can also add a hint or
+even a placeholder:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username, :label => 'Your username please' %>
+  <%= f.input :password, :hint => 'No special characters.' %>
+  <%= f.input :email, :placeholder => 'user@domain.com' %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+In some cases you may want to disable labels, hints or error. Or you may want to configure the html
+of any of them:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username, :label_html => { :class => 'my_class' } %>
+  <%= f.input :password, :hint => false, :error_html => { :id => 'password_error'} %>
+  <%= f.input :password_confirmation, :label => false %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+It is also possible to pass any html attribute straight to the input, by using the `:input_html`
+option, for instance:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username, :input_html => { :class => 'special' } %>
+  <%= f.input :password, :input_html => { :maxlength => 20 } %>
+  <%= f.input :remember_me, :input_html => { :value => '1' } %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+If you want to pass the same options to all inputs in the form (for example, a default class),
+you can use the `:defaults` option in `simple_form_for`. Specific options in `input` call will
+overwrite the defaults:
+
+```erb
+<%= simple_form_for @user, :defaults => { :input_html => { :class => 'default_class' } } do |f| %>
+  <%= f.input :username, :input_html => { :class => 'special' } %>
+  <%= f.input :password, :input_html => { :maxlength => 20 } %>
+  <%= f.input :remember_me, :input_html => { :value => '1' } %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+Since **SimpleForm** generates a wrapper div around your label and input by default, you can pass
+any html attribute to that wrapper as well using the `:wrapper_html` option, like so:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username, :wrapper_html => { :class => 'username' } %>
+  <%= f.input :password, :wrapper_html => { :id => 'password' } %>
+  <%= f.input :remember_me, :wrapper_html => { :class => 'options' } %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+By default all inputs are required, which means an * is prepended to the label, but you can disable
+it in any input you want:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :name, :required => false %>
+  <%= f.input :username %>
+  <%= f.input :password %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+**SimpleForm** also lets you overwrite the default input type it creates:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username %>
+  <%= f.input :password %>
+  <%= f.input :description, :as => :text %>
+  <%= f.input :accepts,     :as => :radio_buttons %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+So instead of a checkbox for the *accepts* attribute, you'll have a pair of radio buttons with yes/no
+labels and a text area instead of a text field for the description. You can also render boolean
+attributes using `:as => :select` to show a dropdown.
+
+It is also possible to give the `:disabled` option to **SimpleForm**, and it'll automatically mark
+the wrapper as disabled with a css class, so you can style labels, hints and other components inside
+the wrapper as well:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username, :disabled => true, :hint => 'You cannot change your username.' %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+**SimpleForm** accepts same options as their corresponding input type helper in Rails:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :date_of_birth, :as => :date, :start_year => Date.today.year - 90,
+                              :end_year => Date.today.year - 12, :discard_day => true,
+                              :order => [:month, :year] %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+**SimpleForm** also allows you to use label, hint, input_field, error and full_error helpers
+(please take a look at the rdocs for each method for more info):
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.label :username %>
+  <%= f.input_field :username %>
+  <%= f.hint 'No special characters, please!' %>
+  <%= f.error :username, :id => 'user_name_error' %>
+  <%= f.full_error :token %>
+  <%= f.submit 'Save' %>
+<% end %>
+```
+
+Any extra option passed to these methods will be rendered as html option.
+
+### Collections
+
+And what if you want to create a select containing the age from 18 to 60 in your form? You can do it
+overriding the `:collection` option:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :user %>
+  <%= f.input :age, :collection => 18..60 %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+Collections can be arrays or ranges, and when a `:collection` is given the `:select` input will be
+rendered by default, so we don't need to pass the `:as => :select` option. Other types of collection
+are `:radio_buttons` and `:check_boxes`. Those are added by **SimpleForm** to Rails set of form
+helpers (read Extra Helpers session below for more information).
+
+Collection inputs accept two other options beside collections:
+
+* _label_method_ => the label method to be applied to the collection to retrieve the label (use this
+  instead of the `text_method` option in `collection_select`)
+
+* _value_method_ => the value method to be applied to the collection to retrieve the value
+
+Those methods are useful to manipulate the given collection. Both of these options also accept
+lambda/procs in case you want to calculate the value or label in a special way eg. custom
+translation. All other options given are sent straight to the underlying helper. For example, you
+can give prompt as:
+
+```ruby
+f.input :age, :collection => 18..60, :prompt => "Select your age"
+```
+
+It is also possible to create grouped collection selects, that will use the html *optgroup* tags, like this:
+
+```ruby
+f.input :country_id, :collection => @continents, :as => :grouped_select, :group_method => :countries
+```
+
+Grouped collection inputs accept the same `:label_method` and `:value_method` options, which will be
+used to retrieve label/value attributes for the `option` tags. Besides that, you can give:
+
+* _group_method_ => the method to be called on the given collection to generate the options for
+  each group (required)
+
+* _group_label_method_ => the label method to be applied on the given collection to retrieve the label
+  for the _optgroup_ (**SimpleForm** will attempt to guess the best one the same way it does with
+  `:label_method`)
+
+### Priority
+
+**SimpleForm** also supports `:time_zone` and `:country`. When using such helpers, you can give
+`:priority` as option to select which time zones and/or countries should be given higher priority:
+
+```ruby
+f.input :residence_country, :priority => [ "Brazil" ]
+f.input :time_zone, :priority => /US/
+```
+
+Those values can also be configured with a default value to be used site use through the
+`SimpleForm.country_priority` and `SimpleForm.time_zone_priority` helpers.
+
+Note: While using `country_select` if you want to restrict to only a subset of countries for a specific
+drop down then you may use the `:collection` option:
+
+```ruby
+f.input :shipping_country, :priority => [ "Brazil" ], :collection => [ "Australia", "Brazil", "New Zealand"]
+```
+
+### Wrapper
+
+**SimpleForm** allows you to add a wrapper which contains the label, error, hint and input.
+The first step is to configure a wrapper tag:
+
+```ruby
+SimpleForm.wrapper_tag = :p
+```
+
+And now, you no longer need to wrap your `f.input` calls anymore:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :username %>
+  <%= f.input :password %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+## Associations
+
+To deal with associations, **SimpleForm** can generate select inputs, a series of radios buttons or check boxes.
+Lets see how it works: imagine you have a user model that belongs to a company and has_and_belongs_to_many
+roles. The structure would be something like:
+
+```ruby
+class User < ActiveRecord::Base
+  belongs_to :company
+  has_and_belongs_to_many :roles
+end
+
+class Company < ActiveRecord::Base
+  has_many :users
+end
+
+class Role < ActiveRecord::Base
+  has_and_belongs_to_many :users
+end
+```
+
+Now we have the user form:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :name %>
+  <%= f.association :company %>
+  <%= f.association :roles %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+Simple enough, right? This is going to render a `:select` input for choosing the `:company`, and another
+`:select` input with `:multiple` option for the `:roles`. You can, of course, change it to use radio
+buttons and check boxes as well:
+
+```ruby
+f.association :company, :as => :radio_buttons
+f.association :roles,   :as => :check_boxes
+```
+
+The association helper just invokes `input` under the hood, so all options available to `:select`,
+`:radio_buttons` and `:check_boxes` are also available to association. Additionally, you can specify
+the collection by hand, all together with the prompt:
+
+```ruby
+f.association :company, :collection => Company.active.all(:order => 'name'), :prompt => "Choose a Company"
+```
+
+## Buttons
+
+All web forms need buttons, right? **SimpleForm** wraps them in the DSL, acting like a proxy:
+
+```erb
+<%= simple_form_for @user do |f| %>
+  <%= f.input :name %>
+  <%= f.button :submit %>
+<% end %>
+```
+
+The above will simply call submit. You choose to use it or not, it's just a question of taste.
+
+## Wrapping Rails Form Helpers
+
+Say you wanted to use a rails form helper but still wrap it in **SimpleForm** goodness? You can, by
+calling input with a block like so:
+
+```erb
+<%= f.input :role do %>
+  <%= f.select :role, Role.all.map { |r| [r.name, r.id, { :class => r.company.id }] }, :include_blank => true %>
+<% end %>
+```
+
+In the above example, we're taking advantage of Rails 3's select method that allows us to pass in a
+hash of additional attributes for each option.
+
+## Extra helpers
+
+**SimpleForm** also comes with some extra helpers you can use inside rails default forms without relying
+on `simple_form_for` helper. They are listed below.
+
+### Simple Fields For
+
+Wrapper to use simple form inside a default rails form
+
+```ruby
+form_for @user do |f|
+  f.simple_fields_for :posts do |posts_form|
+    # Here you have all simple_form methods available
+    posts_form.input :title
+  end
+end
+```
+
+### Collection Radio Buttons
+
+Creates a collection of radio inputs with labels associated (same API as `collection_select`):
+
+```ruby
+form_for @user do |f|
+  f.collection_radio_buttons :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
+end
+```
+
+```html
+<input id="user_options_true" name="user[options]" type="radio" value="true" />
+<label class="collection_radio_buttons" for="user_options_true">Yes</label>
+<input id="user_options_false" name="user[options]" type="radio" value="false" />
+<label class="collection_radio_buttons" for="user_options_false">No</label>
+```
+
+### Collection Check Boxes
+
+Creates a collection of check boxes with labels associated (same API as `collection_select`):
+
+```ruby
+form_for @user do |f|
+  f.collection_check_boxes :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
+end
+```
+
+```html
+<input name="user[options][]" type="hidden" value="" />
+<input id="user_options_true" name="user[options][]" type="checkbox" value="true" />
+<label class="collection_check_box" for="user_options_true">Yes</label>
+<input name="user[options][]" type="hidden" value="" />
+<input id="user_options_false" name="user[options][]" type="checkbox" value="false" />
+<label class="collection_check_box" for="user_options_false">No</label>
+```
+
+To use this with associations in your model, you can do the following:
+
+```ruby
+form_for @user do |f|
+  f.collection_check_boxes :role_ids, Role.all, :id, :name # using :roles here is not going to work.
+end
+```
+
+## Mappings/Inputs available
+
+**SimpleForm** comes with a lot of default mappings:
+
+```
+Mapping               Input                         Column Type
+
+boolean               check box                     boolean
+string                text field                    string
+email                 email field                   string with name matching "email"
+url                   url field                     string with name matching "url"
+tel                   tel field                     string with name matching "phone"
+password              password field                string with name matching "password"
+search                search                        -
+text                  text area                     text
+file                  file field                    string, responding to file methods
+hidden                hidden field                  -
+integer               number field                  integer
+float                 number field                  float
+decimal               number field                  decimal
+range                 range field                   -
+datetime              datetime select               datetime/timestamp
+date                  date select                   date
+time                  time select                   time
+select                collection select             belongs_to/has_many/has_and_belongs_to_many associations
+radio_buttons         collection radio buttons      belongs_to
+check_boxes           collection check boxes        has_many/has_and_belongs_to_many associations
+country               country select                string with name matching "country"
+time_zone             time zone select              string with name matching "time_zone"
+```
+
+## Custom inputs
+
+It is very easy to add custom inputs to **SimpleForm**. For instance, if you want to add a custom input
+that extends the string one, you just need to add this file:
+
+```ruby
+# app/inputs/currency_input.rb
+class CurrencyInput < SimpleForm::Inputs::Base
+  def input
+    "$ #{@builder.text_field(attribute_name, input_html_options)}".html_safe
+  end
+end
+```
+
+And use it in your views:
+
+```ruby
+f.input :money, :as => :currency
+```
+
+You can also redefine existing **SimpleForm** inputs by creating a new class with the same name. For
+instance, if you want to wrap date/time/datetime in a div, you can do:
+
+```ruby
+# app/inputs/date_time_input.rb
+class DateTimeInput < SimpleForm::Inputs::DateTimeInput
+  def input
+    "<div>#{super}</div>".html_safe
+  end
+end
+```
+
+## Custom form builder
+
+You can create a custom form builder that uses **SimpleForm**.
+
+Create a helper method that calls `simple_form_for` with a custom builder:
+
+```ruby
+def custom_form_for(object, *args, &block)
+  options = args.extract_options!
+  simple_form_for(object, *(args << options.merge(:builder => CustomFormBuilder)), &block)
+end
+```
+
+Create a form builder class that inherits from `SimpleForm::FormBuilder`.
+
+```ruby
+class CustomFormBuilder < SimpleForm::FormBuilder
+  def input(attribute_name, options = {}, &block)
+    options[:input_html].merge! :class => 'custom'
+    super
+  end
+end
+```
+
+## I18n
+
+**SimpleForm** uses all power of I18n API to lookup labels, hints and placeholders. To customize your
+forms you can create a locale file like this:
+
+```yaml
+en:
+  simple_form:
+    labels:
+      user:
+        username: 'User name'
+        password: 'Password'
+    hints:
+      user:
+        username: 'User name to sign in.'
+        password: 'No special characters, please.'
+    placeholders:
+      user:
+        username: 'Your username'
+        password: '****'
+```
+
+And your forms will use this information to render the components for you.
+
+**SimpleForm** also lets you be more specific, separating lookups through actions for labels, hints and
+placeholders. Let's say you want a different label for new and edit actions, the locale file would
+be something like:
+
+```yaml
+en:
+  simple_form:
+    labels:
+      user:
+        username: 'User name'
+        password: 'Password'
+        edit:
+          username: 'Change user name'
+          password: 'Change password'
+```
+
+This way **SimpleForm** will figure out the right translation for you, based on the action being
+rendered. And to be a little bit DRYer with your locale file, you can specify defaults for all
+models under the 'defaults' key:
+
+```yaml
+en:
+  simple_form:
+    labels:
+      defaults:
+        username: 'User name'
+        password: 'Password'
+        new:
+          username: 'Choose a user name'
+    hints:
+      defaults:
+        username: 'User name to sign in.'
+        password: 'No special characters, please.'
+    placeholders:
+      defaults:
+        username: 'Your username'
+        password: '****'
+```
+
+**SimpleForm** will always look for a default attribute translation under the "defaults" key if no
+specific is found inside the model key.Note that this syntax is different from 1.x. To migrate to
+the new syntax, just move "labels.#{attribute}" to "labels.defaults.#{attribute}".
+
+In addition, **SimpleForm** will fallback to default human_attribute_name from Rails when no other
+translation is found for labels. Finally, you can also overwrite any label, hint or placeholder
+inside your view, just by passing the option manually. This way the I18n lookup will be skipped.
+
+**SimpleForm** also has support for translating options in collection helpers. For instance, given a
+User with a `:gender` attribute, you might want to create a select box showing translated labels
+that would post either `male` or `female` as value. With **SimpleForm** you could create an input
+like this:
+
+```ruby
+f.input :gender, :collection => [:male, :female]
+```
+
+And **SimpleForm** will try a lookup like this in your locale file, to find the right labels to show:
+
+```yaml
+en:
+  simple_form:
+    options:
+      user:
+        gender:
+          male: 'Male'
+          female: "Female'
+```
+
+You can also use the `defaults` key as you would do with labels, hints and placeholders. It is
+important to notice that **SimpleForm** will only do the lookup for options if you give a collection
+composed of symbols only. This is to avoid constant lookups to I18n.
+
+It's also possible to translate buttons, using Rails' built-in I18n support:
+
+```yaml
+en:
+  helpers:
+    submit:
+      user:
+        create: "Add %{model}"
+        update: "Save Changes"
+```
+
+There are other options that can be configured through I18n API, such as required text and boolean.
+Be sure to check our locale file or the one copied to your application after you run
+`rails generate simple_form:install`.
+
+## HTML 5 Notice
+
+By default, **SimpleForm** will generate input field types and attributes that are supported in HTML5,
+but are considered invalid HTML for older document types such as HTML4 or XHTML1.0. The HTML5
+extensions include the new field types such as email, number, search, url, tel, and the new
+attributes such as required, autofocus, maxlength, min, max, step.
+
+Most browsers will not care, but some of the newer ones - in particular Chrome 10+ - use the
+required attribute to force a value into an input and will prevent form submission without it.
+Depending on the design of the application this may or may not be desired. In many cases it can
+break existing UI's.
+
+It is possible to disable all HTML 5 extensions in **SimpleForm** with the following configuration:
+
+```ruby
+SimpleForm.html5 = false # default is true
+```
+
+If you want to have all other HTML 5 features, such as the new field types, you can disable only
+the browser validation:
+
+```ruby
+SimpleForm.browser_validations = false # default is true
+```
+
+This option adds a new `novalidate` property to the form, instructing it to skip all HTML 5
+validation. The inputs will still be generated with the required and other attributes, that might
+help you to use some generic javascript validation.
+
+You can also add `novalidate` to a specific form by setting the option on the form itself:
+
+```erb
+<%= simple_form_for(resource, :html => {:novalidate => true}) do |form| %>
+```
+
+Please notice that any of the configurations above will disable the `placeholder` component,
+which is an HTML 5 feature. We believe most of the newest browsers are handling this attribute fine,
+and if they aren't, any plugin you use would take of using the placeholder attribute to do it.
+However, you can disable it if you want, by removing the placeholder component from the components
+list in **SimpleForm** configuration file.
+
+## Information
+
+### Google Group
+
+If you have any questions, comments, or concerns please use the Google Group instead of the GitHub
+Issues tracker:
+
+http://groups.google.com/group/plataformatec-simpleform
+
+### RDocs
+
+You can view the **SimpleForm** documentation in RDoc format here:
+
+http://rubydoc.info/github/plataformatec/simple_form/master/frames
+
+If you need to use **SimpleForm** with Rails 2.3, you can always run `gem server` from the command line
+after you install the gem to access the old documentation.
+
+### Bug reports
+
+If you discover any bugs, feel free to create an issue on GitHub. Please add as much information as
+possible to help us fixing the possible bug. We also encourage you to help even more by forking and
+sending us a pull request.
+
+https://github.com/plataformatec/simple_form/issues
+
+## Maintainers
+
+* José Valim (https://github.com/josevalim)
+* Carlos Antonio da Silva (https://github.com/carlosantoniodasilva)
+* Rafael Mendonça França (https://github.com/rafaelfranca)
+
+## License
+
+MIT License. Copyright 2012 Plataforma Tecnologia. http://blog.plataformatec.com.br