Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 855 lines (656 sloc) 29.448 kb
5dd4a63 @rafaelfranca Add travis-ci build image
rafaelfranca authored
1 # SimpleForm - Rails forms made easy.
2 [![Build Status](https://secure.travis-ci.org/plataformatec/simple_form.png)](http://travis-ci.org/plataformatec/simple_form)
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
3
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
4 **SimpleForm** aims to be as flexible as possible while helping you with powerful components to create
2000d32 @derekprior Consistently refer to SimpleForm in docs and tests
derekprior authored
5 your forms. The basic goal of SimpleForm is to not touch your way of defining the layout, letting
eee3dae @carlosantoniodasilva Add note about minimum bootstrap version and new navigable readme
carlosantoniodasilva authored
6 you find the better design for your eyes. Most of the DSL was inherited from Formtastic,
10bd50d @rafaelfranca Review README format
rafaelfranca authored
7 which we are thankful for and should make you feel right at home.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
8
bf1c7d8 @rafaelfranca Update README to warn about the versions 1.x
rafaelfranca authored
9 INFO: This README is [also available in a friendly navigable format](http://simple-form.plataformatec.com.br/)
10 and refers to **SimpleForm** 2.0. If you are using **SimpleForm** in the versions 1.x, you should
11 check this branch:
12
13 https://github.com/plataformatec/simple_form/tree/v1.5
eee3dae @carlosantoniodasilva Add note about minimum bootstrap version and new navigable readme
carlosantoniodasilva authored
14
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
15 ## Installation
16
fca9974 @rafaelfranca Use country_select gem instead of the plugin
rafaelfranca authored
17 Add it to your Gemfile:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
18
fca9974 @rafaelfranca Use country_select gem instead of the plugin
rafaelfranca authored
19 `gem 'simple_form'`
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
20
fca9974 @rafaelfranca Use country_select gem instead of the plugin
rafaelfranca authored
21 Run the following command to install it:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
22
fca9974 @rafaelfranca Use country_select gem instead of the plugin
rafaelfranca authored
23 `bundle install`
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
24
25 Run the generator:
26
c50aea5 @rafaelfranca Review the format
rafaelfranca authored
27 `rails generate simple_form:install`
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
28
fca9974 @rafaelfranca Use country_select gem instead of the plugin
rafaelfranca authored
29 Also, if you want to use the country select, you will need the
30 [country_select gem](https://rubygems.org/gems/country_select), add it to your Gemfile:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
31
fca9974 @rafaelfranca Use country_select gem instead of the plugin
rafaelfranca authored
32 `gem 'country_select'`
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
33
99d1b97 @rafaelfranca Add Twitter Bootstrap section in README and review the generator output
rafaelfranca authored
34 ### Twitter Bootstrap
35
829777a @carlosantoniodasilva Reword bootstrap readme [ci skip]
carlosantoniodasilva authored
36 **SimpleForm** 2.0 can be easily integrated to the [Twitter Bootstrap](http://twitter.github.com/bootstrap).
37 To do that you have to use the `bootstrap` option in the install generator, like this:
99d1b97 @rafaelfranca Add Twitter Bootstrap section in README and review the generator output
rafaelfranca authored
38
39 `rails generate simple_form:install --bootstrap`
40
41 You have to be sure that you added a copy of the [Twitter Bootstrap](http://twitter.github.com/bootstrap)
42 assets on your application.
43
829777a @carlosantoniodasilva Reword bootstrap readme [ci skip]
carlosantoniodasilva authored
44 For more information see the generator output, our
4dd0604 @rafaelfranca More english review
rafaelfranca authored
45 [example application code](https://github.com/rafaelfranca/simple_form-bootstrap) and
829777a @carlosantoniodasilva Reword bootstrap readme [ci skip]
carlosantoniodasilva authored
46 [the live example app](http://simple-form-bootstrap.plataformatec.com.br/).
99d1b97 @rafaelfranca Add Twitter Bootstrap section in README and review the generator output
rafaelfranca authored
47
eee3dae @carlosantoniodasilva Add note about minimum bootstrap version and new navigable readme
carlosantoniodasilva authored
48 **NOTE**: **SimpleForm** integration requires Twitter Bootstrap version 2.0 or higher.
49
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
50 ## Usage
51
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
52 **SimpleForm** was designed to be customized as you need to. Basically it's a stack of components that
10bd50d @rafaelfranca Review README format
rafaelfranca authored
53 are invoked to create a complete html input for you, which by default contains label, hints, errors
54 and the input itself. It does not aim to create a lot of different logic from the default Rails
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
55 form helpers, as they do a great work by themselves. Instead, **SimpleForm** acts as a DSL and just
dfd344c @agis- fix typo
agis- authored
56 maps your input type (retrieved from the column definition in the database) to a specific helper method.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
57
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
58 To start using **SimpleForm** you just have to use the helper it provides:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
59
60 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
61 <%= simple_form_for @user do |f| %>
62 <%= f.input :username %>
63 <%= f.input :password %>
64 <%= f.button :submit %>
65 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
66 ```
67
10bd50d @rafaelfranca Review README format
rafaelfranca authored
68 This will generate an entire form with labels for user name and password as well, and render errors
69 by default when you render the form with invalid data (after submitting for example).
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
70
34c328c @rafaelfranca More formatation
rafaelfranca authored
71 You can overwrite the default label by passing it to the input method. You can also add a hint or
977ed48 @dlee Add docs for inline_label to README (Issue 568)
dlee authored
72 even a placeholder. For boolean inputs, you can add an inline label as well:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
73
74 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
75 <%= simple_form_for @user do |f| %>
76 <%= f.input :username, :label => 'Your username please' %>
77 <%= f.input :password, :hint => 'No special characters.' %>
78 <%= f.input :email, :placeholder => 'user@domain.com' %>
f1b152d @carlosantoniodasilva Remove html_safe call from Readme [ci skip]
carlosantoniodasilva authored
79 <%= f.input :remember_me, :inline_label => 'Yes, remember me' %>
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
80 <%= f.button :submit %>
81 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
82 ```
83
4dd0604 @rafaelfranca More english review
rafaelfranca authored
84 In some cases you may want to disable labels, hints or error. Or you may want to configure the html
34c328c @rafaelfranca More formatation
rafaelfranca authored
85 of any of them:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
86
87 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
88 <%= simple_form_for @user do |f| %>
89 <%= f.input :username, :label_html => { :class => 'my_class' } %>
34c328c @rafaelfranca More formatation
rafaelfranca authored
90 <%= f.input :password, :hint => false, :error_html => { :id => 'password_error'} %>
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
91 <%= f.input :password_confirmation, :label => false %>
92 <%= f.button :submit %>
93 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
94 ```
95
34c328c @rafaelfranca More formatation
rafaelfranca authored
96 It is also possible to pass any html attribute straight to the input, by using the `:input_html`
97 option, for instance:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
98
99 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
100 <%= simple_form_for @user do |f| %>
101 <%= f.input :username, :input_html => { :class => 'special' } %>
102 <%= f.input :password, :input_html => { :maxlength => 20 } %>
103 <%= f.input :remember_me, :input_html => { :value => '1' } %>
104 <%= f.button :submit %>
105 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
106 ```
107
2e6f380 @rafaelfranca Fix documentation for defaults options in simple_form_for
rafaelfranca authored
108 If you want to pass the same options to all inputs in the form (for example, a default class),
109 you can use the `:defaults` option in `simple_form_for`. Specific options in `input` call will
10bd50d @rafaelfranca Review README format
rafaelfranca authored
110 overwrite the defaults:
c04f719 @georgeguimaraes Implements defaults options for simple_form_for.
georgeguimaraes authored
111
112 ```erb
2e6f380 @rafaelfranca Fix documentation for defaults options in simple_form_for
rafaelfranca authored
113 <%= simple_form_for @user, :defaults => { :input_html => { :class => 'default_class' } } do |f| %>
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
114 <%= f.input :username, :input_html => { :class => 'special' } %>
115 <%= f.input :password, :input_html => { :maxlength => 20 } %>
116 <%= f.input :remember_me, :input_html => { :value => '1' } %>
117 <%= f.button :submit %>
118 <% end %>
c04f719 @georgeguimaraes Implements defaults options for simple_form_for.
georgeguimaraes authored
119 ```
120
34c328c @rafaelfranca More formatation
rafaelfranca authored
121 Since **SimpleForm** generates a wrapper div around your label and input by default, you can pass
122 any html attribute to that wrapper as well using the `:wrapper_html` option, like so:
8ee50d8 @olivierlacan Added :wrapper_html example to the README.
olivierlacan authored
123
124 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
125 <%= simple_form_for @user do |f| %>
126 <%= f.input :username, :wrapper_html => { :class => 'username' } %>
127 <%= f.input :password, :wrapper_html => { :id => 'password' } %>
128 <%= f.input :remember_me, :wrapper_html => { :class => 'options' } %>
129 <%= f.button :submit %>
130 <% end %>
8ee50d8 @olivierlacan Added :wrapper_html example to the README.
olivierlacan authored
131 ```
132
d38575f @britto Improve documentation for required fields behavior. Closes #559
britto authored
133 Required fields are marked with an * prepended to their labels.
134
135 By default all inputs are required. When the form object has `presence` validations attached to its fields, **SimpleForm** tells required and optional fields apart. For performance reasons, this detection is skipped on validations that make use of conditional options, such as `:if` and `:unless`.
136
137 And of course, the `required` property of any input can be overwritten as needed:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
138
139 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
140 <%= simple_form_for @user do |f| %>
141 <%= f.input :name, :required => false %>
142 <%= f.input :username %>
143 <%= f.input :password %>
144 <%= f.button :submit %>
145 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
146 ```
147
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
148 **SimpleForm** also lets you overwrite the default input type it creates:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
149
150 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
151 <%= simple_form_for @user do |f| %>
152 <%= f.input :username %>
153 <%= f.input :password %>
154 <%= f.input :description, :as => :text %>
26f3c20 @carlosantoniodasilva :radio is not :radio_buttons
carlosantoniodasilva authored
155 <%= f.input :accepts, :as => :radio_buttons %>
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
156 <%= f.button :submit %>
157 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
158 ```
159
34c328c @rafaelfranca More formatation
rafaelfranca authored
160 So instead of a checkbox for the *accepts* attribute, you'll have a pair of radio buttons with yes/no
10bd50d @rafaelfranca Review README format
rafaelfranca authored
161 labels and a text area instead of a text field for the description. You can also render boolean
34c328c @rafaelfranca More formatation
rafaelfranca authored
162 attributes using `:as => :select` to show a dropdown.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
163
34c328c @rafaelfranca More formatation
rafaelfranca authored
164 It is also possible to give the `:disabled` option to **SimpleForm**, and it'll automatically mark
165 the wrapper as disabled with a css class, so you can style labels, hints and other components inside
10bd50d @rafaelfranca Review README format
rafaelfranca authored
166 the wrapper as well:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
167
168 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
169 <%= simple_form_for @user do |f| %>
34c328c @rafaelfranca More formatation
rafaelfranca authored
170 <%= f.input :username, :disabled => true, :hint => 'You cannot change your username.' %>
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
171 <%= f.button :submit %>
172 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
173 ```
174
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
175 **SimpleForm** accepts same options as their corresponding input type helper in Rails:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
176
177 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
178 <%= simple_form_for @user do |f| %>
179 <%= f.input :date_of_birth, :as => :date, :start_year => Date.today.year - 90,
180 :end_year => Date.today.year - 12, :discard_day => true,
181 :order => [:month, :year] %>
182 <%= f.button :submit %>
183 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
184 ```
185
34c328c @rafaelfranca More formatation
rafaelfranca authored
186 **SimpleForm** also allows you to use label, hint, input_field, error and full_error helpers
10bd50d @rafaelfranca Review README format
rafaelfranca authored
187 (please take a look at the rdocs for each method for more info):
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
188
189 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
190 <%= simple_form_for @user do |f| %>
191 <%= f.label :username %>
192 <%= f.input_field :username %>
193 <%= f.hint 'No special characters, please!' %>
194 <%= f.error :username, :id => 'user_name_error' %>
195 <%= f.full_error :token %>
196 <%= f.submit 'Save' %>
197 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
198 ```
199
200 Any extra option passed to these methods will be rendered as html option.
201
202 ### Collections
203
10bd50d @rafaelfranca Review README format
rafaelfranca authored
204 And what if you want to create a select containing the age from 18 to 60 in your form? You can do it
34c328c @rafaelfranca More formatation
rafaelfranca authored
205 overriding the `:collection` option:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
206
207 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
208 <%= simple_form_for @user do |f| %>
209 <%= f.input :user %>
210 <%= f.input :age, :collection => 18..60 %>
211 <%= f.button :submit %>
212 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
213 ```
214
34c328c @rafaelfranca More formatation
rafaelfranca authored
215 Collections can be arrays or ranges, and when a `:collection` is given the `:select` input will be
216 rendered by default, so we don't need to pass the `:as => :select` option. Other types of collection
217 are `:radio_buttons` and `:check_boxes`. Those are added by **SimpleForm** to Rails set of form
218 helpers (read Extra Helpers session below for more information).
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
219
e4cd411 @carlosantoniodasilva Update Changelog, add Readme info about grouped collection
carlosantoniodasilva authored
220 Collection inputs accept two other options beside collections:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
221
34c328c @rafaelfranca More formatation
rafaelfranca authored
222 * _label_method_ => the label method to be applied to the collection to retrieve the label (use this
223 instead of the `text_method` option in `collection_select`)
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
224
34c328c @rafaelfranca More formatation
rafaelfranca authored
225 * _value_method_ => the value method to be applied to the collection to retrieve the value
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
226
10bd50d @rafaelfranca Review README format
rafaelfranca authored
227 Those methods are useful to manipulate the given collection. Both of these options also accept
228 lambda/procs in case you want to calculate the value or label in a special way eg. custom
229 translation. All other options given are sent straight to the underlying helper. For example, you
230 can give prompt as:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
231
232 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
233 f.input :age, :collection => 18..60, :prompt => "Select your age"
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
234 ```
235
34c328c @rafaelfranca More formatation
rafaelfranca authored
236 It is also possible to create grouped collection selects, that will use the html *optgroup* tags, like this:
e4cd411 @carlosantoniodasilva Update Changelog, add Readme info about grouped collection
carlosantoniodasilva authored
237
238 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
239 f.input :country_id, :collection => @continents, :as => :grouped_select, :group_method => :countries
e4cd411 @carlosantoniodasilva Update Changelog, add Readme info about grouped collection
carlosantoniodasilva authored
240 ```
241
10bd50d @rafaelfranca Review README format
rafaelfranca authored
242 Grouped collection inputs accept the same `:label_method` and `:value_method` options, which will be
243 used to retrieve label/value attributes for the `option` tags. Besides that, you can give:
e4cd411 @carlosantoniodasilva Update Changelog, add Readme info about grouped collection
carlosantoniodasilva authored
244
34c328c @rafaelfranca More formatation
rafaelfranca authored
245 * _group_method_ => the method to be called on the given collection to generate the options for
246 each group (required)
e4cd411 @carlosantoniodasilva Update Changelog, add Readme info about grouped collection
carlosantoniodasilva authored
247
34c328c @rafaelfranca More formatation
rafaelfranca authored
248 * _group_label_method_ => the label method to be applied on the given collection to retrieve the label
249 for the _optgroup_ (**SimpleForm** will attempt to guess the best one the same way it does with
10bd50d @rafaelfranca Review README format
rafaelfranca authored
250 `:label_method`)
e4cd411 @carlosantoniodasilva Update Changelog, add Readme info about grouped collection
carlosantoniodasilva authored
251
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
252 ### Priority
253
34c328c @rafaelfranca More formatation
rafaelfranca authored
254 **SimpleForm** also supports `:time_zone` and `:country`. When using such helpers, you can give
255 `:priority` as option to select which time zones and/or countries should be given higher priority:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
256
257 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
258 f.input :residence_country, :priority => [ "Brazil" ]
259 f.input :time_zone, :priority => /US/
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
260 ```
261
10bd50d @rafaelfranca Review README format
rafaelfranca authored
262 Those values can also be configured with a default value to be used site use through the
263 `SimpleForm.country_priority` and `SimpleForm.time_zone_priority` helpers.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
264
34c328c @rafaelfranca More formatation
rafaelfranca authored
265 Note: While using `country_select` if you want to restrict to only a subset of countries for a specific
266 drop down then you may use the `:collection` option:
a452718 @sailavu Update README.md
sailavu authored
267
268 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
269 f.input :shipping_country, :priority => [ "Brazil" ], :collection => [ "Australia", "Brazil", "New Zealand"]
a452718 @sailavu Update README.md
sailavu authored
270 ```
271
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
272 ### Associations
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
273
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
274 To deal with associations, **SimpleForm** can generate select inputs, a series of radios buttons or check boxes.
10bd50d @rafaelfranca Review README format
rafaelfranca authored
275 Lets see how it works: imagine you have a user model that belongs to a company and has_and_belongs_to_many
276 roles. The structure would be something like:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
277
278 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
279 class User < ActiveRecord::Base
280 belongs_to :company
281 has_and_belongs_to_many :roles
282 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
283
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
284 class Company < ActiveRecord::Base
285 has_many :users
286 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
287
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
288 class Role < ActiveRecord::Base
289 has_and_belongs_to_many :users
290 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
291 ```
292
293 Now we have the user form:
294
295 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
296 <%= simple_form_for @user do |f| %>
297 <%= f.input :name %>
298 <%= f.association :company %>
299 <%= f.association :roles %>
300 <%= f.button :submit %>
301 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
302 ```
303
6641f2b @rafaelfranca English review
rafaelfranca authored
304 Simple enough, right? This is going to render a `:select` input for choosing the `:company`, and another
305 `:select` input with `:multiple` option for the `:roles`. You can, of course, change it to use radio
34c328c @rafaelfranca More formatation
rafaelfranca authored
306 buttons and check boxes as well:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
307
308 ```ruby
26f3c20 @carlosantoniodasilva :radio is not :radio_buttons
carlosantoniodasilva authored
309 f.association :company, :as => :radio_buttons
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
310 f.association :roles, :as => :check_boxes
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
311 ```
312
6641f2b @rafaelfranca English review
rafaelfranca authored
313 The association helper just invokes `input` under the hood, so all options available to `:select`,
34c328c @rafaelfranca More formatation
rafaelfranca authored
314 `:radio_buttons` and `:check_boxes` are also available to association. Additionally, you can specify
315 the collection by hand, all together with the prompt:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
316
317 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
318 f.association :company, :collection => Company.active.all(:order => 'name'), :prompt => "Choose a Company"
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
319 ```
320
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
321 ### Buttons
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
322
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
323 All web forms need buttons, right? **SimpleForm** wraps them in the DSL, acting like a proxy:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
324
325 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
326 <%= simple_form_for @user do |f| %>
327 <%= f.input :name %>
328 <%= f.button :submit %>
329 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
330 ```
331
332 The above will simply call submit. You choose to use it or not, it's just a question of taste.
333
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
334 ### Wrapping Rails Form Helpers
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
335
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
336 Say you wanted to use a rails form helper but still wrap it in **SimpleForm** goodness? You can, by
10bd50d @rafaelfranca Review README format
rafaelfranca authored
337 calling input with a block like so:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
338
339 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
340 <%= f.input :role do %>
341 <%= f.select :role, Role.all.map { |r| [r.name, r.id, { :class => r.company.id }] }, :include_blank => true %>
342 <% end %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
343 ```
344
10bd50d @rafaelfranca Review README format
rafaelfranca authored
345 In the above example, we're taking advantage of Rails 3's select method that allows us to pass in a
346 hash of additional attributes for each option.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
347
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
348 ### Extra helpers
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
349
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
350 **SimpleForm** also comes with some extra helpers you can use inside rails default forms without relying
34c328c @rafaelfranca More formatation
rafaelfranca authored
351 on `simple_form_for` helper. They are listed below.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
352
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
353 #### Simple Fields For
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
354
0d292d0 @rafaelfranca Explain that `simple_fields_for` uses `fields_for` in the README
rafaelfranca authored
355 Wrapper to use **SimpleForm** inside a default rails form. It works in the same way that the `field_for`
356 Rails helper, but change the builder to use the `SimpleForm::FormBuilder`.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
357
358 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
359 form_for @user do |f|
360 f.simple_fields_for :posts do |posts_form|
361 # Here you have all simple_form methods available
362 posts_form.input :title
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
363 end
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
364 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
365 ```
366
0d292d0 @rafaelfranca Explain that `simple_fields_for` uses `fields_for` in the README
rafaelfranca authored
367
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
368 #### Collection Radio Buttons
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
369
34c328c @rafaelfranca More formatation
rafaelfranca authored
370 Creates a collection of radio inputs with labels associated (same API as `collection_select`):
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
371
372 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
373 form_for @user do |f|
26f3c20 @carlosantoniodasilva :radio is not :radio_buttons
carlosantoniodasilva authored
374 f.collection_radio_buttons :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
375 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
376 ```
377
378 ```html
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
379 <input id="user_options_true" name="user[options]" type="radio" value="true" />
26f3c20 @carlosantoniodasilva :radio is not :radio_buttons
carlosantoniodasilva authored
380 <label class="collection_radio_buttons" for="user_options_true">Yes</label>
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
381 <input id="user_options_false" name="user[options]" type="radio" value="false" />
26f3c20 @carlosantoniodasilva :radio is not :radio_buttons
carlosantoniodasilva authored
382 <label class="collection_radio_buttons" for="user_options_false">No</label>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
383 ```
384
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
385 #### Collection Check Boxes
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
386
34c328c @rafaelfranca More formatation
rafaelfranca authored
387 Creates a collection of check boxes with labels associated (same API as `collection_select`):
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
388
389 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
390 form_for @user do |f|
391 f.collection_check_boxes :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
392 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
393 ```
394
395 ```html
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
396 <input name="user[options][]" type="hidden" value="" />
397 <input id="user_options_true" name="user[options][]" type="checkbox" value="true" />
398 <label class="collection_check_box" for="user_options_true">Yes</label>
399 <input name="user[options][]" type="hidden" value="" />
400 <input id="user_options_false" name="user[options][]" type="checkbox" value="false" />
401 <label class="collection_check_box" for="user_options_false">No</label>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
402 ```
403
404 To use this with associations in your model, you can do the following:
405
406 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
407 form_for @user do |f|
408 f.collection_check_boxes :role_ids, Role.all, :id, :name # using :roles here is not going to work.
409 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
410 ```
411
412 ## Mappings/Inputs available
413
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
414 **SimpleForm** comes with a lot of default mappings:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
415
08f6446 @rafaelfranca Update README.md
rafaelfranca authored
416 ```text
26f3c20 @carlosantoniodasilva :radio is not :radio_buttons
carlosantoniodasilva authored
417 Mapping Input Column Type
418
419 boolean check box boolean
420 string text field string
421 email email field string with name matching "email"
422 url url field string with name matching "url"
423 tel tel field string with name matching "phone"
424 password password field string with name matching "password"
425 search search -
426 text text area text
427 file file field string, responding to file methods
428 hidden hidden field -
429 integer number field integer
430 float number field float
431 decimal number field decimal
432 range range field -
433 datetime datetime select datetime/timestamp
434 date date select date
435 time time select time
436 select collection select belongs_to/has_many/has_and_belongs_to_many associations
437 radio_buttons collection radio buttons belongs_to
438 check_boxes collection check boxes has_many/has_and_belongs_to_many associations
439 country country select string with name matching "country"
440 time_zone time zone select string with name matching "time_zone"
10bd50d @rafaelfranca Review README format
rafaelfranca authored
441 ```
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
442
443 ## Custom inputs
444
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
445 It is very easy to add custom inputs to **SimpleForm**. For instance, if you want to add a custom input
10bd50d @rafaelfranca Review README format
rafaelfranca authored
446 that extends the string one, you just need to add this file:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
447
448 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
449 # app/inputs/currency_input.rb
450 class CurrencyInput < SimpleForm::Inputs::Base
451 def input
452 "$ #{@builder.text_field(attribute_name, input_html_options)}".html_safe
453 end
454 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
455 ```
456
457 And use it in your views:
458
459 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
460 f.input :money, :as => :currency
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
461 ```
462
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
463 You can also redefine existing **SimpleForm** inputs by creating a new class with the same name. For
10bd50d @rafaelfranca Review README format
rafaelfranca authored
464 instance, if you want to wrap date/time/datetime in a div, you can do:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
465
466 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
467 # app/inputs/date_time_input.rb
468 class DateTimeInput < SimpleForm::Inputs::DateTimeInput
469 def input
a731551 @dreamfall Update patch-1
dreamfall authored
470 template.content_tag(:div, super)
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
471 end
472 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
473 ```
474
45ae549 @rafaelfranca Document that you can override `input_html_classes` in custom inputs.
rafaelfranca authored
475 Or if you want to add a class to all the select fields you can do:
476
477 ```ruby
478 # app/inputs/collection_select_input.rb
479 class CollectionSelectInput < SimpleForm::Inputs::CollectionSelectInput
480 def input_html_classes
481 super.push('chosen')
482 end
483 end
484 ```
485
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
486 ## Custom form builder
487
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
488 You can create a custom form builder that uses **SimpleForm**.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
489
34c328c @rafaelfranca More formatation
rafaelfranca authored
490 Create a helper method that calls `simple_form_for` with a custom builder:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
491
492 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
493 def custom_form_for(object, *args, &block)
494 options = args.extract_options!
495 simple_form_for(object, *(args << options.merge(:builder => CustomFormBuilder)), &block)
496 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
497 ```
498
34c328c @rafaelfranca More formatation
rafaelfranca authored
499 Create a form builder class that inherits from `SimpleForm::FormBuilder`.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
500
501 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
502 class CustomFormBuilder < SimpleForm::FormBuilder
503 def input(attribute_name, options = {}, &block)
504 options[:input_html].merge! :class => 'custom'
505 super
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
506 end
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
507 end
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
508 ```
509
510 ## I18n
511
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
512 **SimpleForm** uses all power of I18n API to lookup labels, hints and placeholders. To customize your
10bd50d @rafaelfranca Review README format
rafaelfranca authored
513 forms you can create a locale file like this:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
514
515 ```yaml
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
516 en:
517 simple_form:
518 labels:
519 user:
520 username: 'User name'
521 password: 'Password'
522 hints:
523 user:
524 username: 'User name to sign in.'
525 password: 'No special characters, please.'
526 placeholders:
527 user:
528 username: 'Your username'
529 password: '****'
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
530 ```
531
532 And your forms will use this information to render the components for you.
533
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
534 **SimpleForm** also lets you be more specific, separating lookups through actions for labels, hints and
10bd50d @rafaelfranca Review README format
rafaelfranca authored
535 placeholders. Let's say you want a different label for new and edit actions, the locale file would
536 be something like:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
537
538 ```yaml
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
539 en:
540 simple_form:
541 labels:
542 user:
543 username: 'User name'
544 password: 'Password'
545 edit:
546 username: 'Change user name'
547 password: 'Change password'
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
548 ```
549
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
550 This way **SimpleForm** will figure out the right translation for you, based on the action being
10bd50d @rafaelfranca Review README format
rafaelfranca authored
551 rendered. And to be a little bit DRYer with your locale file, you can specify defaults for all
552 models under the 'defaults' key:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
553
554 ```yaml
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
555 en:
556 simple_form:
557 labels:
558 defaults:
559 username: 'User name'
560 password: 'Password'
561 new:
562 username: 'Choose a user name'
563 hints:
564 defaults:
565 username: 'User name to sign in.'
566 password: 'No special characters, please.'
567 placeholders:
568 defaults:
569 username: 'Your username'
570 password: '****'
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
571 ```
572
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
573 **SimpleForm** will always look for a default attribute translation under the "defaults" key if no
50d7a19 @carolfs README.md altered to include information about defining translation s…
carolfs authored
574 specific is found inside the model key. Note that this syntax is different from 1.x. To migrate to
10bd50d @rafaelfranca Review README format
rafaelfranca authored
575 the new syntax, just move "labels.#{attribute}" to "labels.defaults.#{attribute}".
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
576
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
577 In addition, **SimpleForm** will fallback to default human_attribute_name from Rails when no other
10bd50d @rafaelfranca Review README format
rafaelfranca authored
578 translation is found for labels. Finally, you can also overwrite any label, hint or placeholder
579 inside your view, just by passing the option manually. This way the I18n lookup will be skipped.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
580
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
581 **SimpleForm** also has support for translating options in collection helpers. For instance, given a
10bd50d @rafaelfranca Review README format
rafaelfranca authored
582 User with a `:gender` attribute, you might want to create a select box showing translated labels
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
583 that would post either `male` or `female` as value. With **SimpleForm** you could create an input
10bd50d @rafaelfranca Review README format
rafaelfranca authored
584 like this:
eb72c1a @carlosantoniodasilva Update Readme and Changelog
carlosantoniodasilva authored
585
586 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
587 f.input :gender, :collection => [:male, :female]
eb72c1a @carlosantoniodasilva Update Readme and Changelog
carlosantoniodasilva authored
588 ```
589
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
590 And **SimpleForm** will try a lookup like this in your locale file, to find the right labels to show:
eb72c1a @carlosantoniodasilva Update Readme and Changelog
carlosantoniodasilva authored
591
592 ```yaml
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
593 en:
594 simple_form:
595 options:
596 user:
597 gender:
598 male: 'Male'
b1d7333 @jayshepherd Fix double quote typo
jayshepherd authored
599 female: 'Female'
eb72c1a @carlosantoniodasilva Update Readme and Changelog
carlosantoniodasilva authored
600 ```
601
10bd50d @rafaelfranca Review README format
rafaelfranca authored
602 You can also use the `defaults` key as you would do with labels, hints and placeholders. It is
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
603 important to notice that **SimpleForm** will only do the lookup for options if you give a collection
10bd50d @rafaelfranca Review README format
rafaelfranca authored
604 composed of symbols only. This is to avoid constant lookups to I18n.
eb72c1a @carlosantoniodasilva Update Readme and Changelog
carlosantoniodasilva authored
605
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
606 It's also possible to translate buttons, using Rails' built-in I18n support:
607
608 ```yaml
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
609 en:
610 helpers:
611 submit:
612 user:
613 create: "Add %{model}"
614 update: "Save Changes"
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
615 ```
616
10bd50d @rafaelfranca Review README format
rafaelfranca authored
617 There are other options that can be configured through I18n API, such as required text and boolean.
618 Be sure to check our locale file or the one copied to your application after you run
34c328c @rafaelfranca More formatation
rafaelfranca authored
619 `rails generate simple_form:install`.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
620
50d7a19 @carolfs README.md altered to include information about defining translation s…
carolfs authored
621 It should be noted that translations for labels, hints and placeholders for a namespaced model, e.g.
622 `Admin::User`, should be placed under `admin_user`, not under `admin/user`. This is different from
623 how translations for namespaced model and attribute names are defined:
624
625 ```yaml
626 en:
627 activerecord:
628 models:
629 admin/user: User
630 attributes:
631 admin/user:
632 name: Name
633 ```
634
635 They should be placed under `admin/user`. Form labels, hints and placeholders for those attributes,
636 though, should be placed under `admin_user`:
637
638 ```yaml
639 en:
640 simple_form:
641 labels:
642 admin_user:
643 name: Name
644 ```
645
dafaa52 @carolfs More documentation related to translations and issue #555.
carolfs authored
646 This difference exists because **SimpleForm** relies on `object_name` provided by Rails'
647 FormBuilder to determine the translation path for a given object instead of `i18n_key` from the
648 object itself. Thus, similarly, if a form for an `Admin::User` object is defined by calling
649 `simple_form_for @admin_user, :as => :some_user`, **SimpleForm** will look for translations
650 under `some_user` instead of `admin_user`.
651
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
652 ## Configuration
653
654 **SimpleForm** has several configuration options. You can read and change them in the initializer
655 created by **SimpleForm**, so if you haven't executed the command below yet, please do:
656
657 `rails generate simple_form:install`
658
659 ### The wrappers API
660
661 With **SimpleForm** you can configure how your components will be rendered using the wrappers API.
662 The syntax looks like this:
663
664 ```ruby
665 config.wrappers :tag => :div, :class => :input,
666 :error_class => :field_with_errors do |b|
667
668 # Form extensions
669 b.use :html5
670 b.optional :pattern
671 b.use :maxlength
672 b.use :placeholder
673 b.use :readonly
674
675 # Form components
676 b.use :label_input
677 b.use :hint, :wrap_with => { :tag => :span, :class => :hint }
678 b.use :error, :wrap_with => { :tag => :span, :class => :error }
679 end
680 ```
681
1c729ab @karellm Add a list of the available Form components that can be customized wi…
karellm authored
682 The _Form components_ will generate the form tags like labels, inputs, hints or errors contents. The available components are:
683
684 ```ruby
685 :label # The <label> tag alone
686 :input # The <input> tag alone
687 :label_input # The <label> and the <input> tags
688 :hint # The hint for the input
689 :error # The error for the input
690 ```
9ca4fa5 @rafaelfranca Review the README [ci skip]
rafaelfranca authored
691
692 The _Form extensions_ are used to generate some attributes or perform some lookups on the model to
693 add extra information to your components.
694
695 You can create new _Form components_ using the wrappers API as in the following example:
696
697 ```ruby
698 config.wrappers do |b|
699 b.use :placeholder
700 b.use :label_input
701 b.wrapper :tag => :div, :class => 'separator' do |component|
702 component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
703 component.use :error, :wrap_with => { :tag => :span, :class => :error }
704 end
705 end
706 ```
707
708 this will wrap the hint and error components within a `div` tag using the class `'separator'`.
709
710 If you want to customize the custom _Form components_ on demand you can give it a name like this:
711
712 ```ruby
713 config.wrappers do |b|
714 b.use :placeholder
715 b.use :label_input
716 b.wrapper :my_wrapper, :tag => :div, :class => 'separator' do |component|
717 component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
718 component.use :error, :wrap_with => { :tag => :span, :class => :error }
719 end
720 end
721 ```
722
723 and now you can pass options to your `input` calls to customize the `:my_wrapper` _Form component_.
724
725 ```ruby
726 # Completely turns off the custom wrapper
727 f.input :name, :my_wrapper => false
728
729 # Configure the html
730 f.input :name, :my_wrapper_html => { :id => 'special_id' }
731
732 # Configure the tag
733 f.input :name, :my_wrapper_tag => :p
734 ```
735
736 You can also define more than one wrapper and pick one to render in a specific form or input.
737 To define another wrapper you have to give it a name, as the follow:
738
739 ```ruby
740 config.wrappers :small do |b|
741 b.use :placeholder
742 b.use :label_input
743 end
744 ```
745
746 and use it in this way:
747
748 ```ruby
749 # Specifying to whole form
750 simple_form_for @user, :wrapper => :small do |f|
751 f.input :name
752 end
753
754 # Specifying to one input
755 simple_form_for @user do |f|
756 f.input :name, :wrapper => :small
757 end
758 ```
759
760 **SimpleForm** also allows you to use optional elements. For instance, let's suppose you want to use
761 hints or placeholders, but you don't want them to be generated automatically. You can set their
762 default values to `false` or use the `optional` method. Is preferible to use the `optional` syntax:
763
764 ```ruby
765 config.wrappers :placeholder => false do |b|
766 b.use :placeholder
767 b.use :label_input
768 b.wrapper :tag => :div, :class => 'separator' do |component|
769 component.optional :hint, :wrap_with => { :tag => :span, :class => :hint }
770 component.use :error, :wrap_with => { :tag => :span, :class => :error }
771 end
772 end
773 ```
774
775 By setting it as `optional`, a hint will only be generated when `:hint => true` is explicitly used.
776 The same for placehold.
777
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
778 ## HTML 5 Notice
779
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
780 By default, **SimpleForm** will generate input field types and attributes that are supported in HTML5,
10bd50d @rafaelfranca Review README format
rafaelfranca authored
781 but are considered invalid HTML for older document types such as HTML4 or XHTML1.0. The HTML5
782 extensions include the new field types such as email, number, search, url, tel, and the new
783 attributes such as required, autofocus, maxlength, min, max, step.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
784
10bd50d @rafaelfranca Review README format
rafaelfranca authored
785 Most browsers will not care, but some of the newer ones - in particular Chrome 10+ - use the
786 required attribute to force a value into an input and will prevent form submission without it.
787 Depending on the design of the application this may or may not be desired. In many cases it can
788 break existing UI's.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
789
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
790 It is possible to disable all HTML 5 extensions in **SimpleForm** with the following configuration:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
791
792 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
793 SimpleForm.html5 = false # default is true
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
794 ```
795
10bd50d @rafaelfranca Review README format
rafaelfranca authored
796 If you want to have all other HTML 5 features, such as the new field types, you can disable only
797 the browser validation:
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
798
799 ```ruby
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
800 SimpleForm.browser_validations = false # default is true
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
801 ```
802
10bd50d @rafaelfranca Review README format
rafaelfranca authored
803 This option adds a new `novalidate` property to the form, instructing it to skip all HTML 5
804 validation. The inputs will still be generated with the required and other attributes, that might
805 help you to use some generic javascript validation.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
806
807 You can also add `novalidate` to a specific form by setting the option on the form itself:
808
809 ```erb
9f7a7bc @carlosantoniodasilva Remove useless indent from code blocs in readme [ci skip]
carlosantoniodasilva authored
810 <%= simple_form_for(resource, :html => {:novalidate => true}) do |form| %>
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
811 ```
812
10bd50d @rafaelfranca Review README format
rafaelfranca authored
813 Please notice that any of the configurations above will disable the `placeholder` component,
814 which is an HTML 5 feature. We believe most of the newest browsers are handling this attribute fine,
815 and if they aren't, any plugin you use would take of using the placeholder attribute to do it.
816 However, you can disable it if you want, by removing the placeholder component from the components
05f5e97 @rafaelfranca SimpleForm is a strong name
rafaelfranca authored
817 list in **SimpleForm** configuration file.
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
818
b3821b3 @rafaelfranca Move the Configuration section to top
rafaelfranca authored
819 ## Information
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
820
b3821b3 @rafaelfranca Move the Configuration section to top
rafaelfranca authored
821 ### Google Group
822
823 If you have any questions, comments, or concerns please use the Google Group instead of the GitHub
824 Issues tracker:
825
826 http://groups.google.com/group/plataformatec-simpleform
827
828 ### RDocs
829
830 You can view the **SimpleForm** documentation in RDoc format here:
831
832 http://rubydoc.info/github/plataformatec/simple_form/master/frames
833
834 If you need to use **SimpleForm** with Rails 2.3, you can always run `gem server` from the command line
835 after you install the gem to access the old documentation.
836
837 ### Bug reports
838
839 If you discover any bugs, feel free to create an issue on GitHub. Please add as much information as
840 possible to help us fixing the possible bug. We also encourage you to help even more by forking and
841 sending us a pull request.
842
843 https://github.com/plataformatec/simple_form/issues
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
844
845 ## Maintainers
846
3147cc3 @rafaelfranca Welcome back José :heart:
rafaelfranca authored
847 * José Valim (https://github.com/josevalim)
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
848 * Carlos Antonio da Silva (https://github.com/carlosantoniodasilva)
849 * Rafael Mendonça França (https://github.com/rafaelfranca)
46d4bb4 @carlosantoniodasilva Welcome to the team, @nashby! :sparkles:
carlosantoniodasilva authored
850 * Vasiliy Ermolovich (https://github.com/nashby)
61fc74b @olivierlacan Converted README to GitHub-flavored Markdown w/ syntax highlighting f…
olivierlacan authored
851
852 ## License
853
767dfae @carlosantoniodasilva Change Copyright name/link [ci skip]
carlosantoniodasilva authored
854 MIT License. Copyright 2012 Plataformatec. http://plataformatec.com.br
Something went wrong with that request. Please try again.