README.md in simple_form-2.0.1 vs README.md in simple_form-2.0.2
- old
+ new
@@ -29,17 +29,10 @@
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'`
-## 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:
@@ -52,121 +45,10 @@
[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, :wrap_with => { :tag => :span, :class => :hint }
- b.use :error, :wrap_with => { :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.wrapper :tag => :div, :class => 'separator' do |component|
- component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
- component.use :error, :wrap_with => { :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.wrapper :my_wrapper, :tag => :div, :class => 'separator' do |component|
- component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
- component.use :error, :wrap_with => { :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.wrapper :tag => :div, :class => 'separator' do |component|
- component.optional :hint, :wrap_with => { :tag => :span, :class => :hint }
- component.use :error, :wrap_with => { :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
@@ -381,31 +263,12 @@
```ruby
f.input :shipping_country, :priority => [ "Brazil" ], :collection => [ "Australia", "Brazil", "New Zealand"]
```
-### Wrapper
+### Associations
-**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
@@ -449,11 +312,11 @@
```ruby
f.association :company, :collection => Company.active.all(:order => 'name'), :prompt => "Choose a Company"
```
-## Buttons
+### Buttons
All web forms need buttons, right? **SimpleForm** wraps them in the DSL, acting like a proxy:
```erb
<%= simple_form_for @user do |f| %>
@@ -462,11 +325,11 @@
<% 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
+### 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
@@ -476,30 +339,32 @@
```
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
+### 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
+#### Simple Fields For
-Wrapper to use SimpleForm inside a default rails form
+Wrapper to use **SimpleForm** inside a default rails form. It works in the same way that the `field_for`
+Rails helper, but change the builder to use the `SimpleForm::FormBuilder`.
```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
+#### 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
@@ -511,11 +376,11 @@
<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
+#### Collection Check Boxes
Creates a collection of check boxes with labels associated (same API as `collection_select`):
```ruby
form_for @user do |f|
@@ -542,11 +407,11 @@
## Mappings/Inputs available
**SimpleForm** comes with a lot of default mappings:
-```
+```text
Mapping Input Column Type
boolean check box boolean
string text field string
email email field string with name matching "email"
@@ -601,10 +466,21 @@
"<div>#{super}</div>".html_safe
end
end
```
+Or if you want to add a class to all the select fields you can do:
+
+```ruby
+# app/inputs/collection_select_input.rb
+class CollectionSelectInput < SimpleForm::Inputs::CollectionSelectInput
+ def input_html_classes
+ super.push('chosen')
+ 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:
@@ -736,10 +612,136 @@
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`.
+## 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`
+
+### 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, :wrap_with => { :tag => :span, :class => :hint }
+ b.use :error, :wrap_with => { :tag => :span, :class => :error }
+end
+```
+
+The _Form components_ will generate the form tags like labels, inputs, hints or errors contents. The available components are:
+
+```ruby
+:label # The <label> tag alone
+:input # The <input> tag alone
+:label_input # The <label> and the <input> tags
+:hint # The hint for the input
+:error # The error for the input
+```
+
+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.wrapper :tag => :div, :class => 'separator' do |component|
+ component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
+ component.use :error, :wrap_with => { :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.wrapper :my_wrapper, :tag => :div, :class => 'separator' do |component|
+ component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
+ component.use :error, :wrap_with => { :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.wrapper :tag => :div, :class => 'separator' do |component|
+ component.optional :hint, :wrap_with => { :tag => :span, :class => :hint }
+ component.use :error, :wrap_with => { :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.
+
## 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
@@ -811,6 +813,6 @@
* 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
+MIT License. Copyright 2012 Plataformatec. http://plataformatec.com.br