simple_form 2.1.3 → 3.0.0
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of simple_form might be problematic. Click here for more details.
- checksums.yaml +4 -4
- data/CHANGELOG.md +21 -51
- data/README.md +195 -161
- data/lib/generators/simple_form/install_generator.rb +4 -4
- data/lib/generators/simple_form/templates/README +2 -2
- data/lib/generators/simple_form/templates/config/initializers/simple_form.rb +16 -13
- data/lib/generators/simple_form/templates/config/initializers/simple_form_bootstrap.rb +16 -16
- data/lib/generators/simple_form/templates/config/initializers/simple_form_foundation.rb +3 -3
- data/lib/simple_form/action_view_extensions/builder.rb +1 -320
- data/lib/simple_form/action_view_extensions/builder.rb.orig +247 -0
- data/lib/simple_form/action_view_extensions/form_helper.rb +2 -9
- data/lib/simple_form/components/errors.rb +1 -7
- data/lib/simple_form/components/hints.rb +2 -7
- data/lib/simple_form/components/html5.rb +5 -2
- data/lib/simple_form/components/labels.rb +4 -4
- data/lib/simple_form/components/maxlength.rb +1 -8
- data/lib/simple_form/components/pattern.rb +2 -2
- data/lib/simple_form/components.rb +1 -1
- data/lib/simple_form/error_notification.rb +2 -2
- data/lib/simple_form/form_builder.rb +154 -50
- data/lib/simple_form/form_builder.rb.orig +486 -0
- data/lib/simple_form/helpers.rb +1 -1
- data/lib/simple_form/inputs/base.rb +7 -10
- data/lib/simple_form/inputs/block_input.rb +1 -1
- data/lib/simple_form/inputs/boolean_input.rb +6 -5
- data/lib/simple_form/inputs/collection_input.rb +7 -7
- data/lib/simple_form/inputs/date_time_input.rb +1 -1
- data/lib/simple_form/inputs/numeric_input.rb +0 -6
- data/lib/simple_form/inputs/password_input.rb +0 -1
- data/lib/simple_form/inputs/string_input.rb +0 -1
- data/lib/simple_form/railtie.rb +7 -0
- data/lib/simple_form/tags.rb +62 -0
- data/lib/simple_form/version.rb +1 -1
- data/lib/simple_form/version.rb.orig +7 -0
- data/lib/simple_form/wrappers/builder.rb +5 -29
- data/lib/simple_form/wrappers/many.rb +1 -1
- data/lib/simple_form/wrappers/root.rb +1 -1
- data/lib/simple_form/wrappers.rb +1 -1
- data/lib/simple_form.rb +43 -47
- data/test/action_view_extensions/builder_test.rb +78 -99
- data/test/action_view_extensions/form_helper_test.rb +25 -16
- data/test/components/label_test.rb +46 -46
- data/test/form_builder/association_test.rb +47 -29
- data/test/form_builder/button_test.rb +4 -4
- data/test/form_builder/error_notification_test.rb +8 -8
- data/test/form_builder/error_test.rb +18 -65
- data/test/form_builder/general_test.rb +62 -63
- data/test/form_builder/hint_test.rb +23 -29
- data/test/form_builder/input_field_test.rb +29 -12
- data/test/form_builder/label_test.rb +7 -17
- data/test/form_builder/wrapper_test.rb +21 -21
- data/test/inputs/boolean_input_test.rb +24 -24
- data/test/inputs/collection_check_boxes_input_test.rb +66 -55
- data/test/inputs/collection_radio_buttons_input_test.rb +81 -79
- data/test/inputs/collection_select_input_test.rb +76 -51
- data/test/inputs/datetime_input_test.rb +17 -11
- data/test/inputs/disabled_test.rb +10 -10
- data/test/inputs/discovery_test.rb +4 -4
- data/test/inputs/file_input_test.rb +1 -1
- data/test/inputs/general_test.rb +28 -12
- data/test/inputs/grouped_collection_select_input_test.rb +33 -20
- data/test/inputs/hidden_input_test.rb +3 -2
- data/test/inputs/numeric_input_test.rb +3 -3
- data/test/inputs/priority_input_test.rb +9 -3
- data/test/inputs/readonly_test.rb +12 -12
- data/test/inputs/required_test.rb +5 -5
- data/test/inputs/string_input_test.rb +15 -25
- data/test/inputs/text_input_test.rb +1 -1
- data/test/support/misc_helpers.rb +46 -24
- data/test/support/mock_controller.rb +6 -6
- data/test/support/models.rb +77 -62
- data/test/test_helper.rb +17 -34
- metadata +39 -22
- data/lib/simple_form/core_ext/hash.rb +0 -16
data/README.md
CHANGED
@@ -1,12 +1,20 @@
|
|
1
|
-
|
2
|
-
[![Build Status](https://secure.travis-ci.org/plataformatec/simple_form.png?branch=master)](http://travis-ci.org/plataformatec/simple_form)
|
1
|
+
![Simple Form Logo](https://raw.github.com/plataformatec/simple_form/master/simple_form.png)
|
3
2
|
|
4
|
-
|
5
|
-
|
3
|
+
By [Plataformatec](http://plataformatec.com.br/).
|
4
|
+
|
5
|
+
[![Gem Version](https://fury-badge.herokuapp.com/rb/simple_form.png)](http://badge.fury.io/rb/simple_form)
|
6
|
+
[![Build Status](https://api.travis-ci.org/plataformatec/simple_form.png?branch=master)](http://travis-ci.org/plataformatec/simple_form)
|
7
|
+
[![Code Climate](https://codeclimate.com/github/plataformatec/simple_form.png)](https://codeclimate.com/github/plataformatec/simple_form)
|
8
|
+
|
9
|
+
Rails forms made easy.
|
10
|
+
|
11
|
+
**Simple Form** aims to be as flexible as possible while helping you with powerful components to create
|
12
|
+
your forms. The basic goal of **Simple Form** is to not touch your way of defining the layout, letting
|
6
13
|
you find the better design for your eyes. Most of the DSL was inherited from Formtastic,
|
7
14
|
which we are thankful for and should make you feel right at home.
|
8
15
|
|
9
|
-
INFO: This README
|
16
|
+
INFO: This README is [also available in a friendly navigable format](http://simple-form.plataformatec.com.br/)
|
17
|
+
and refers to **Simple Form** 3.0. For older releases, check the related branch for your version.
|
10
18
|
|
11
19
|
## Installation
|
12
20
|
|
@@ -35,45 +43,48 @@ Also, if you want to use the country select, you will need the
|
|
35
43
|
gem 'country_select'
|
36
44
|
```
|
37
45
|
|
38
|
-
### Bootstrap
|
46
|
+
### Twitter Bootstrap
|
39
47
|
|
40
|
-
**Simple Form** can be easily integrated to the [Bootstrap](http://
|
48
|
+
**Simple Form** can be easily integrated to the [Twitter Bootstrap](http://twitter.github.com/bootstrap).
|
41
49
|
To do that you have to use the `bootstrap` option in the install generator, like this:
|
42
50
|
|
43
51
|
```console
|
44
52
|
rails generate simple_form:install --bootstrap
|
45
53
|
```
|
46
54
|
|
47
|
-
You have to be sure that you added a copy of the [Bootstrap](http://
|
55
|
+
You have to be sure that you added a copy of the [Twitter Bootstrap](http://twitter.github.com/bootstrap)
|
48
56
|
assets on your application.
|
49
57
|
|
50
58
|
For more information see the generator output, our
|
51
59
|
[example application code](https://github.com/rafaelfranca/simple_form-bootstrap) and
|
52
60
|
[the live example app](http://simple-form-bootstrap.plataformatec.com.br/).
|
53
61
|
|
54
|
-
**NOTE**: **
|
62
|
+
**NOTE**: **Simple Form** integration requires Twitter Bootstrap version 2.0 or higher.
|
55
63
|
|
56
64
|
### Zurb Foundation 3
|
57
65
|
|
58
|
-
To generate wrappers that are compatible with [Zurb Foundation 3](http://foundation.zurb.com/), pass
|
66
|
+
To generate wrappers that are compatible with [Zurb Foundation 3](http://foundation.zurb.com/), pass
|
67
|
+
the `foundation` option to the generator, like this:
|
59
68
|
|
60
69
|
```console
|
61
70
|
rails generate simple_form:install --foundation
|
62
71
|
```
|
63
72
|
|
64
|
-
Please note that the Foundation wrapper does not support the `:hint` option by default. In order to
|
73
|
+
Please note that the Foundation wrapper does not support the `:hint` option by default. In order to
|
74
|
+
enable hints, please uncomment the appropriate line in `config/initializers/simple_form_foundation.rb`.
|
75
|
+
You will need to provide your own CSS styles for hints.
|
65
76
|
|
66
|
-
Please see the [instructions on how to install Foundation in a Rails app](http://foundation.zurb.com/docs/rails.php).
|
77
|
+
Please see the [instructions on how to install Foundation in a Rails app](http://foundation.zurb.com/old-docs/f3/rails.php).
|
67
78
|
|
68
79
|
## Usage
|
69
80
|
|
70
|
-
**
|
81
|
+
**Simple Form** was designed to be customized as you need to. Basically it's a stack of components that
|
71
82
|
are invoked to create a complete html input for you, which by default contains label, hints, errors
|
72
83
|
and the input itself. It does not aim to create a lot of different logic from the default Rails
|
73
|
-
form helpers, as they do a great work by themselves. Instead, **
|
84
|
+
form helpers, as they do a great work by themselves. Instead, **Simple Form** acts as a DSL and just
|
74
85
|
maps your input type (retrieved from the column definition in the database) to a specific helper method.
|
75
86
|
|
76
|
-
To start using **
|
87
|
+
To start using **Simple Form** you just have to use the helper it provides:
|
77
88
|
|
78
89
|
```erb
|
79
90
|
<%= simple_form_for @user do |f| %>
|
@@ -91,10 +102,10 @@ even a placeholder. For boolean inputs, you can add an inline label as well:
|
|
91
102
|
|
92
103
|
```erb
|
93
104
|
<%= simple_form_for @user do |f| %>
|
94
|
-
<%= f.input :username, :
|
95
|
-
<%= f.input :password, :
|
96
|
-
<%= f.input :email, :
|
97
|
-
<%= f.input :remember_me, :
|
105
|
+
<%= f.input :username, label: 'Your username please' %>
|
106
|
+
<%= f.input :password, hint: 'No special characters.' %>
|
107
|
+
<%= f.input :email, placeholder: 'user@domain.com' %>
|
108
|
+
<%= f.input :remember_me, inline_label: 'Yes, remember me' %>
|
98
109
|
<%= f.button :submit %>
|
99
110
|
<% end %>
|
100
111
|
```
|
@@ -104,9 +115,9 @@ of any of them:
|
|
104
115
|
|
105
116
|
```erb
|
106
117
|
<%= simple_form_for @user do |f| %>
|
107
|
-
<%= f.input :username, :
|
108
|
-
<%= f.input :password, :
|
109
|
-
<%= f.input :password_confirmation, :
|
118
|
+
<%= f.input :username, label_html: { class: 'my_class' } %>
|
119
|
+
<%= f.input :password, hint: false, error_html: { id: 'password_error'} %>
|
120
|
+
<%= f.input :password_confirmation, label: false %>
|
110
121
|
<%= f.button :submit %>
|
111
122
|
<% end %>
|
112
123
|
```
|
@@ -116,9 +127,9 @@ option, for instance:
|
|
116
127
|
|
117
128
|
```erb
|
118
129
|
<%= simple_form_for @user do |f| %>
|
119
|
-
<%= f.input :username, :
|
120
|
-
<%= f.input :password, :
|
121
|
-
<%= f.input :remember_me, :
|
130
|
+
<%= f.input :username, input_html: { class: 'special' } %>
|
131
|
+
<%= f.input :password, input_html: { maxlength: 20 } %>
|
132
|
+
<%= f.input :remember_me, input_html: { value: '1' } %>
|
122
133
|
<%= f.button :submit %>
|
123
134
|
<% end %>
|
124
135
|
```
|
@@ -128,87 +139,82 @@ you can use the `:defaults` option in `simple_form_for`. Specific options in `in
|
|
128
139
|
overwrite the defaults:
|
129
140
|
|
130
141
|
```erb
|
131
|
-
<%= simple_form_for @user, :
|
132
|
-
<%= f.input :username, :
|
133
|
-
<%= f.input :password, :
|
134
|
-
<%= f.input :remember_me, :
|
142
|
+
<%= simple_form_for @user, defaults: { input_html: { class: 'default_class' } } do |f| %>
|
143
|
+
<%= f.input :username, input_html: { class: 'special' } %>
|
144
|
+
<%= f.input :password, input_html: { maxlength: 20 } %>
|
145
|
+
<%= f.input :remember_me, input_html: { value: '1' } %>
|
135
146
|
<%= f.button :submit %>
|
136
147
|
<% end %>
|
137
148
|
```
|
138
149
|
|
139
|
-
Since **
|
150
|
+
Since **Simple Form** generates a wrapper div around your label and input by default, you can pass
|
140
151
|
any html attribute to that wrapper as well using the `:wrapper_html` option, like so:
|
141
152
|
|
142
153
|
```erb
|
143
154
|
<%= simple_form_for @user do |f| %>
|
144
|
-
<%= f.input :username, :
|
145
|
-
<%= f.input :password, :
|
146
|
-
<%= f.input :remember_me, :
|
155
|
+
<%= f.input :username, wrapper_html: { class: 'username' } %>
|
156
|
+
<%= f.input :password, wrapper_html: { id: 'password' } %>
|
157
|
+
<%= f.input :remember_me, wrapper_html: { class: 'options' } %>
|
147
158
|
<%= f.button :submit %>
|
148
159
|
<% end %>
|
149
160
|
```
|
150
161
|
|
151
162
|
Required fields are marked with an * prepended to their labels.
|
152
163
|
|
153
|
-
By default all inputs are required. When the form object has `presence` validations attached to its
|
164
|
+
By default all inputs are required. When the form object has `presence` validations attached to its
|
165
|
+
fields, **Simple Form** tells required and optional fields apart. For performance reasons, this
|
166
|
+
detection is skipped on validations that make use of conditional options, such as `:if` and `:unless`.
|
154
167
|
|
155
168
|
And of course, the `required` property of any input can be overwritten as needed:
|
156
169
|
|
157
170
|
```erb
|
158
171
|
<%= simple_form_for @user do |f| %>
|
159
|
-
<%= f.input :name, :
|
172
|
+
<%= f.input :name, required: false %>
|
160
173
|
<%= f.input :username %>
|
161
174
|
<%= f.input :password %>
|
162
175
|
<%= f.button :submit %>
|
163
176
|
<% end %>
|
164
177
|
```
|
165
178
|
|
166
|
-
|
167
|
-
appropriate input for the column. For example, a column created with type
|
168
|
-
`:text` in the database will use a `textarea` input by default. See the section
|
169
|
-
[Available input types and defaults for each column
|
170
|
-
type](https://github.com/plataformatec/simple_form#available-input-types-and-defaults-for-each-column-type)
|
171
|
-
for a complete list of defaults.
|
172
|
-
|
173
|
-
**SimpleForm** also lets you overwrite the default input type it creates:
|
179
|
+
**Simple Form** also lets you overwrite the default input type it creates:
|
174
180
|
|
175
181
|
```erb
|
176
182
|
<%= simple_form_for @user do |f| %>
|
177
183
|
<%= f.input :username %>
|
178
184
|
<%= f.input :password %>
|
179
|
-
<%= f.input :description, :
|
180
|
-
<%= f.input :accepts, :
|
185
|
+
<%= f.input :description, as: :text %>
|
186
|
+
<%= f.input :accepts, as: :radio_buttons %>
|
181
187
|
<%= f.button :submit %>
|
182
188
|
<% end %>
|
183
189
|
```
|
184
190
|
|
185
191
|
So instead of a checkbox for the *accepts* attribute, you'll have a pair of radio buttons with yes/no
|
186
|
-
labels and a
|
187
|
-
attributes using
|
192
|
+
labels and a text area instead of a text field for the description. You can also render boolean
|
193
|
+
attributes using `as: :select` to show a dropdown.
|
188
194
|
|
189
|
-
It is also possible to give the `:disabled` option to **
|
195
|
+
It is also possible to give the `:disabled` option to **Simple Form**, and it'll automatically mark
|
190
196
|
the wrapper as disabled with a css class, so you can style labels, hints and other components inside
|
191
197
|
the wrapper as well:
|
192
198
|
|
193
199
|
```erb
|
194
200
|
<%= simple_form_for @user do |f| %>
|
195
|
-
<%= f.input :username, :
|
201
|
+
<%= f.input :username, disabled: true, hint: 'You cannot change your username.' %>
|
196
202
|
<%= f.button :submit %>
|
197
203
|
<% end %>
|
198
204
|
```
|
199
205
|
|
200
|
-
**
|
206
|
+
**Simple Form** accepts same options as their corresponding input type helper in Rails:
|
201
207
|
|
202
208
|
```erb
|
203
209
|
<%= simple_form_for @user do |f| %>
|
204
|
-
<%= f.input :date_of_birth, :
|
205
|
-
:
|
206
|
-
:
|
210
|
+
<%= f.input :date_of_birth, as: :date, start_year: Date.today.year - 90,
|
211
|
+
end_year: Date.today.year - 12, discard_day: true,
|
212
|
+
order: [:month, :year] %>
|
207
213
|
<%= f.button :submit %>
|
208
214
|
<% end %>
|
209
215
|
```
|
210
216
|
|
211
|
-
**
|
217
|
+
**Simple Form** also allows you to use label, hint, input_field, error and full_error helpers
|
212
218
|
(please take a look at the rdocs for each method for more info):
|
213
219
|
|
214
220
|
```erb
|
@@ -216,7 +222,7 @@ the wrapper as well:
|
|
216
222
|
<%= f.label :username %>
|
217
223
|
<%= f.input_field :username %>
|
218
224
|
<%= f.hint 'No special characters, please!' %>
|
219
|
-
<%= f.error :username, :
|
225
|
+
<%= f.error :username, id: 'user_name_error' %>
|
220
226
|
<%= f.full_error :token %>
|
221
227
|
<%= f.submit 'Save' %>
|
222
228
|
<% end %>
|
@@ -224,6 +230,29 @@ the wrapper as well:
|
|
224
230
|
|
225
231
|
Any extra option passed to these methods will be rendered as html option.
|
226
232
|
|
233
|
+
### Stripping away all wrapper divs
|
234
|
+
|
235
|
+
**Simple Form** also allows you to strip away all the div wrappers around the `<input>` field that is
|
236
|
+
generated with the usual `f.input`.
|
237
|
+
The easiest way to achieve this is to use `f.input_field`.
|
238
|
+
|
239
|
+
Example:
|
240
|
+
|
241
|
+
```ruby
|
242
|
+
simple_form_for @user do |f|
|
243
|
+
f.input_field :name
|
244
|
+
end
|
245
|
+
```
|
246
|
+
|
247
|
+
Produces:
|
248
|
+
|
249
|
+
```html
|
250
|
+
<input class="string required" id="user_name" maxlength="100"
|
251
|
+
name="user[name]" size="100" type="text" value="Carlos" />
|
252
|
+
```
|
253
|
+
|
254
|
+
To view the actual RDocs for this, check them out here - http://rubydoc.info/github/plataformatec/simple_form/master/SimpleForm/FormBuilder:input_field
|
255
|
+
|
227
256
|
### Collections
|
228
257
|
|
229
258
|
And what if you want to create a select containing the age from 18 to 60 in your form? You can do it
|
@@ -232,14 +261,14 @@ overriding the `:collection` option:
|
|
232
261
|
```erb
|
233
262
|
<%= simple_form_for @user do |f| %>
|
234
263
|
<%= f.input :user %>
|
235
|
-
<%= f.input :age, :
|
264
|
+
<%= f.input :age, collection: 18..60 %>
|
236
265
|
<%= f.button :submit %>
|
237
266
|
<% end %>
|
238
267
|
```
|
239
268
|
|
240
269
|
Collections can be arrays or ranges, and when a `:collection` is given the `:select` input will be
|
241
|
-
rendered by default, so we don't need to pass the
|
242
|
-
are `:radio_buttons` and `:check_boxes`. Those are added by **
|
270
|
+
rendered by default, so we don't need to pass the `as: :select` option. Other types of collection
|
271
|
+
are `:radio_buttons` and `:check_boxes`. Those are added by **Simple Form** to Rails set of form
|
243
272
|
helpers (read Extra Helpers session below for more information).
|
244
273
|
|
245
274
|
Collection inputs accept two other options beside collections:
|
@@ -255,13 +284,13 @@ translation. All other options given are sent straight to the underlying helper.
|
|
255
284
|
can give prompt as:
|
256
285
|
|
257
286
|
```ruby
|
258
|
-
f.input :age, :
|
287
|
+
f.input :age, collection: 18..60, prompt: "Select your age"
|
259
288
|
```
|
260
289
|
|
261
290
|
It is also possible to create grouped collection selects, that will use the html *optgroup* tags, like this:
|
262
291
|
|
263
292
|
```ruby
|
264
|
-
f.input :country_id, :
|
293
|
+
f.input :country_id, collection: @continents, as: :grouped_select, group_method: :countries
|
265
294
|
```
|
266
295
|
|
267
296
|
Grouped collection inputs accept the same `:label_method` and `:value_method` options, which will be
|
@@ -271,17 +300,17 @@ used to retrieve label/value attributes for the `option` tags. Besides that, you
|
|
271
300
|
each group (required)
|
272
301
|
|
273
302
|
* _group_label_method_ => the label method to be applied on the given collection to retrieve the label
|
274
|
-
for the _optgroup_ (**
|
303
|
+
for the _optgroup_ (**Simple Form** will attempt to guess the best one the same way it does with
|
275
304
|
`:label_method`)
|
276
305
|
|
277
306
|
### Priority
|
278
307
|
|
279
|
-
**
|
308
|
+
**Simple Form** also supports `:time_zone` and `:country`. When using such helpers, you can give
|
280
309
|
`:priority` as option to select which time zones and/or countries should be given higher priority:
|
281
310
|
|
282
311
|
```ruby
|
283
|
-
f.input :residence_country, :
|
284
|
-
f.input :time_zone, :
|
312
|
+
f.input :residence_country, priority: [ "Brazil" ]
|
313
|
+
f.input :time_zone, priority: /US/
|
285
314
|
```
|
286
315
|
|
287
316
|
Those values can also be configured with a default value to be used site use through the
|
@@ -291,12 +320,12 @@ Note: While using `country_select` if you want to restrict to only a subset of c
|
|
291
320
|
drop down then you may use the `:collection` option:
|
292
321
|
|
293
322
|
```ruby
|
294
|
-
f.input :shipping_country, :
|
323
|
+
f.input :shipping_country, priority: [ "Brazil" ], collection: [ "Australia", "Brazil", "New Zealand"]
|
295
324
|
```
|
296
325
|
|
297
326
|
### Associations
|
298
327
|
|
299
|
-
To deal with associations, **
|
328
|
+
To deal with associations, **Simple Form** can generate select inputs, a series of radios buttons or check boxes.
|
300
329
|
Lets see how it works: imagine you have a user model that belongs to a company and has_and_belongs_to_many
|
301
330
|
roles. The structure would be something like:
|
302
331
|
|
@@ -328,11 +357,11 @@ Now we have the user form:
|
|
328
357
|
|
329
358
|
Simple enough, right? This is going to render a `:select` input for choosing the `:company`, and another
|
330
359
|
`:select` input with `:multiple` option for the `:roles`. You can, of course, change it to use radio
|
331
|
-
buttons and
|
360
|
+
buttons and check boxes as well:
|
332
361
|
|
333
362
|
```ruby
|
334
|
-
f.association :company, :
|
335
|
-
f.association :roles, :
|
363
|
+
f.association :company, as: :radio_buttons
|
364
|
+
f.association :roles, as: :check_boxes
|
336
365
|
```
|
337
366
|
|
338
367
|
The association helper just invokes `input` under the hood, so all options available to `:select`,
|
@@ -340,18 +369,21 @@ The association helper just invokes `input` under the hood, so all options avail
|
|
340
369
|
the collection by hand, all together with the prompt:
|
341
370
|
|
342
371
|
```ruby
|
343
|
-
f.association :company, :
|
372
|
+
f.association :company, collection: Company.active.all(order: 'name'), prompt: "Choose a Company"
|
344
373
|
```
|
345
374
|
|
346
375
|
In case you want to declare different labels and values:
|
347
376
|
|
348
377
|
```ruby
|
349
|
-
f.association :company, :
|
378
|
+
f.association :company, label_method: :company_name, value_method: :id, include_blank: false
|
350
379
|
```
|
351
380
|
|
381
|
+
Please note that the association helper is currently only tested with Active Record. It currently
|
382
|
+
does not work well with Mongoid and depending on the ORM you're using your mileage may vary.
|
383
|
+
|
352
384
|
### Buttons
|
353
385
|
|
354
|
-
All web forms need buttons, right? **
|
386
|
+
All web forms need buttons, right? **Simple Form** wraps them in the DSL, acting like a proxy:
|
355
387
|
|
356
388
|
```erb
|
357
389
|
<%= simple_form_for @user do |f| %>
|
@@ -364,12 +396,12 @@ The above will simply call submit. You choose to use it or not, it's just a ques
|
|
364
396
|
|
365
397
|
### Wrapping Rails Form Helpers
|
366
398
|
|
367
|
-
Say you wanted to use a rails form helper but still wrap it in **
|
399
|
+
Say you wanted to use a rails form helper but still wrap it in **Simple Form** goodness? You can, by
|
368
400
|
calling input with a block like so:
|
369
401
|
|
370
402
|
```erb
|
371
403
|
<%= f.input :role do %>
|
372
|
-
<%= f.select :role, Role.all.map { |r| [r.name, r.id, { :
|
404
|
+
<%= f.select :role, Role.all.map { |r| [r.name, r.id, { class: r.company.id }] }, include_blank: true %>
|
373
405
|
<% end %>
|
374
406
|
```
|
375
407
|
|
@@ -378,12 +410,12 @@ hash of additional attributes for each option.
|
|
378
410
|
|
379
411
|
### Extra helpers
|
380
412
|
|
381
|
-
**
|
413
|
+
**Simple Form** also comes with some extra helpers you can use inside rails default forms without relying
|
382
414
|
on `simple_form_for` helper. They are listed below.
|
383
415
|
|
384
416
|
#### Simple Fields For
|
385
417
|
|
386
|
-
Wrapper to use **
|
418
|
+
Wrapper to use **Simple Form** inside a default rails form. It works in the same way that the `fields_for`
|
387
419
|
Rails helper, but change the builder to use the `SimpleForm::FormBuilder`.
|
388
420
|
|
389
421
|
```ruby
|
@@ -395,7 +427,6 @@ form_for @user do |f|
|
|
395
427
|
end
|
396
428
|
```
|
397
429
|
|
398
|
-
|
399
430
|
#### Collection Radio Buttons
|
400
431
|
|
401
432
|
Creates a collection of radio inputs with labels associated (same API as `collection_select`):
|
@@ -415,7 +446,7 @@ end
|
|
415
446
|
|
416
447
|
#### Collection Check Boxes
|
417
448
|
|
418
|
-
Creates a collection of
|
449
|
+
Creates a collection of check boxes with labels associated (same API as `collection_select`):
|
419
450
|
|
420
451
|
```ruby
|
421
452
|
form_for @user do |f|
|
@@ -440,40 +471,40 @@ form_for @user do |f|
|
|
440
471
|
end
|
441
472
|
```
|
442
473
|
|
443
|
-
##
|
444
|
-
|
445
|
-
|
446
|
-
|
447
|
-
|
448
|
-
|
449
|
-
|
450
|
-
|
451
|
-
|
452
|
-
|
453
|
-
|
454
|
-
|
455
|
-
|
456
|
-
|
457
|
-
|
458
|
-
|
459
|
-
|
460
|
-
|
461
|
-
|
462
|
-
|
463
|
-
|
464
|
-
|
465
|
-
|
466
|
-
|
467
|
-
|
468
|
-
|
469
|
-
|
470
|
-
|
471
|
-
|
472
|
-
|
474
|
+
## Mappings/Inputs available
|
475
|
+
|
476
|
+
**Simple Form** comes with a lot of default mappings:
|
477
|
+
|
478
|
+
```text
|
479
|
+
Mapping Input Column Type
|
480
|
+
|
481
|
+
boolean check box boolean
|
482
|
+
string text field string
|
483
|
+
email email field string with name matching "email"
|
484
|
+
url url field string with name matching "url"
|
485
|
+
tel tel field string with name matching "phone"
|
486
|
+
password password field string with name matching "password"
|
487
|
+
search search -
|
488
|
+
text text area text
|
489
|
+
file file field string, responding to file methods
|
490
|
+
hidden hidden field -
|
491
|
+
integer number field integer
|
492
|
+
float number field float
|
493
|
+
decimal number field decimal
|
494
|
+
range range field -
|
495
|
+
datetime datetime select datetime/timestamp
|
496
|
+
date date select date
|
497
|
+
time time select time
|
498
|
+
select collection select belongs_to/has_many/has_and_belongs_to_many associations
|
499
|
+
radio_buttons collection radio buttons belongs_to
|
500
|
+
check_boxes collection check boxes has_many/has_and_belongs_to_many associations
|
501
|
+
country country select string with name matching "country"
|
502
|
+
time_zone time zone select string with name matching "time_zone"
|
503
|
+
```
|
473
504
|
|
474
505
|
## Custom inputs
|
475
506
|
|
476
|
-
It is very easy to add custom inputs to **
|
507
|
+
It is very easy to add custom inputs to **Simple Form**. For instance, if you want to add a custom input
|
477
508
|
that extends the string one, you just need to add this file:
|
478
509
|
|
479
510
|
```ruby
|
@@ -488,11 +519,10 @@ end
|
|
488
519
|
And use it in your views:
|
489
520
|
|
490
521
|
```ruby
|
491
|
-
f.input :money, :
|
522
|
+
f.input :money, as: :currency
|
492
523
|
```
|
493
|
-
Note, you may have to create the `app/inputs/` directory and restart your webserver.
|
494
524
|
|
495
|
-
You can also redefine existing **
|
525
|
+
You can also redefine existing **Simple Form** inputs by creating a new class with the same name. For
|
496
526
|
instance, if you want to wrap date/time/datetime in a div, you can do:
|
497
527
|
|
498
528
|
```ruby
|
@@ -517,14 +547,14 @@ end
|
|
517
547
|
|
518
548
|
## Custom form builder
|
519
549
|
|
520
|
-
You can create a custom form builder that uses **
|
550
|
+
You can create a custom form builder that uses **Simple Form**.
|
521
551
|
|
522
552
|
Create a helper method that calls `simple_form_for` with a custom builder:
|
523
553
|
|
524
554
|
```ruby
|
525
555
|
def custom_form_for(object, *args, &block)
|
526
556
|
options = args.extract_options!
|
527
|
-
simple_form_for(object, *(args << options.merge(:
|
557
|
+
simple_form_for(object, *(args << options.merge(builder: CustomFormBuilder)), &block)
|
528
558
|
end
|
529
559
|
```
|
530
560
|
|
@@ -533,7 +563,7 @@ Create a form builder class that inherits from `SimpleForm::FormBuilder`.
|
|
533
563
|
```ruby
|
534
564
|
class CustomFormBuilder < SimpleForm::FormBuilder
|
535
565
|
def input(attribute_name, options = {}, &block)
|
536
|
-
options[:input_html].merge! :
|
566
|
+
options[:input_html].merge! class: 'custom'
|
537
567
|
super
|
538
568
|
end
|
539
569
|
end
|
@@ -541,7 +571,7 @@ end
|
|
541
571
|
|
542
572
|
## I18n
|
543
573
|
|
544
|
-
**
|
574
|
+
**Simple Form** uses all power of I18n API to lookup labels, hints and placeholders. To customize your
|
545
575
|
forms you can create a locale file like this:
|
546
576
|
|
547
577
|
```yaml
|
@@ -563,7 +593,7 @@ en:
|
|
563
593
|
|
564
594
|
And your forms will use this information to render the components for you.
|
565
595
|
|
566
|
-
**
|
596
|
+
**Simple Form** also lets you be more specific, separating lookups through actions for labels, hints and
|
567
597
|
placeholders. Let's say you want a different label for new and edit actions, the locale file would
|
568
598
|
be something like:
|
569
599
|
|
@@ -579,7 +609,7 @@ en:
|
|
579
609
|
password: 'Change password'
|
580
610
|
```
|
581
611
|
|
582
|
-
This way **
|
612
|
+
This way **Simple Form** will figure out the right translation for you, based on the action being
|
583
613
|
rendered. And to be a little bit DRYer with your locale file, you can specify defaults for all
|
584
614
|
models under the 'defaults' key:
|
585
615
|
|
@@ -602,24 +632,24 @@ en:
|
|
602
632
|
password: '****'
|
603
633
|
```
|
604
634
|
|
605
|
-
**
|
635
|
+
**Simple Form** will always look for a default attribute translation under the "defaults" key if no
|
606
636
|
specific is found inside the model key. Note that this syntax is different from 1.x. To migrate to
|
607
637
|
the new syntax, just move "labels.#{attribute}" to "labels.defaults.#{attribute}".
|
608
638
|
|
609
|
-
In addition, **
|
639
|
+
In addition, **Simple Form** will fallback to default human_attribute_name from Rails when no other
|
610
640
|
translation is found for labels. Finally, you can also overwrite any label, hint or placeholder
|
611
641
|
inside your view, just by passing the option manually. This way the I18n lookup will be skipped.
|
612
642
|
|
613
|
-
**
|
643
|
+
**Simple Form** also has support for translating options in collection helpers. For instance, given a
|
614
644
|
User with a `:gender` attribute, you might want to create a select box showing translated labels
|
615
|
-
that would post either `male` or `female` as value. With **
|
645
|
+
that would post either `male` or `female` as value. With **Simple Form** you could create an input
|
616
646
|
like this:
|
617
647
|
|
618
648
|
```ruby
|
619
|
-
f.input :gender, :
|
649
|
+
f.input :gender, collection: [:male, :female]
|
620
650
|
```
|
621
651
|
|
622
|
-
And **
|
652
|
+
And **Simple Form** will try a lookup like this in your locale file, to find the right labels to show:
|
623
653
|
|
624
654
|
```yaml
|
625
655
|
en:
|
@@ -632,7 +662,7 @@ en:
|
|
632
662
|
```
|
633
663
|
|
634
664
|
You can also use the `defaults` key as you would do with labels, hints and placeholders. It is
|
635
|
-
important to notice that **
|
665
|
+
important to notice that **Simple Form** will only do the lookup for options if you give a collection
|
636
666
|
composed of symbols only. This is to avoid constant lookups to I18n.
|
637
667
|
|
638
668
|
It's also possible to translate buttons, using Rails' built-in I18n support:
|
@@ -675,27 +705,27 @@ en:
|
|
675
705
|
name: Name
|
676
706
|
```
|
677
707
|
|
678
|
-
This difference exists because **
|
708
|
+
This difference exists because **Simple Form** relies on `object_name` provided by Rails'
|
679
709
|
FormBuilder to determine the translation path for a given object instead of `i18n_key` from the
|
680
710
|
object itself. Thus, similarly, if a form for an `Admin::User` object is defined by calling
|
681
|
-
`simple_form_for @admin_user, :
|
711
|
+
`simple_form_for @admin_user, as: :some_user`, **Simple Form** will look for translations
|
682
712
|
under `some_user` instead of `admin_user`.
|
683
713
|
|
684
714
|
## Configuration
|
685
715
|
|
686
|
-
**
|
687
|
-
created by **
|
716
|
+
**Simple Form** has several configuration options. You can read and change them in the initializer
|
717
|
+
created by **Simple Form**, so if you haven't executed the command below yet, please do:
|
688
718
|
|
689
719
|
`rails generate simple_form:install`
|
690
720
|
|
691
721
|
### The wrappers API
|
692
722
|
|
693
|
-
With **
|
723
|
+
With **Simple Form** you can configure how your components will be rendered using the wrappers API.
|
694
724
|
The syntax looks like this:
|
695
725
|
|
696
726
|
```ruby
|
697
|
-
config.wrappers :
|
698
|
-
:
|
727
|
+
config.wrappers tag: :div, class: :input,
|
728
|
+
error_class: :field_with_errors do |b|
|
699
729
|
|
700
730
|
# Form extensions
|
701
731
|
b.use :html5
|
@@ -706,12 +736,13 @@ config.wrappers :tag => :div, :class => :input,
|
|
706
736
|
|
707
737
|
# Form components
|
708
738
|
b.use :label_input
|
709
|
-
b.use :hint, :
|
710
|
-
b.use :error, :
|
739
|
+
b.use :hint, wrap_with: { tag: :span, class: :hint }
|
740
|
+
b.use :error, wrap_with: { tag: :span, class: :error }
|
711
741
|
end
|
712
742
|
```
|
713
743
|
|
714
|
-
The _Form components_ will generate the form tags like labels, inputs, hints or errors contents.
|
744
|
+
The _Form components_ will generate the form tags like labels, inputs, hints or errors contents.
|
745
|
+
The available components are:
|
715
746
|
|
716
747
|
```ruby
|
717
748
|
:label # The <label> tag alone
|
@@ -730,9 +761,9 @@ You can create new _Form components_ using the wrappers API as in the following
|
|
730
761
|
config.wrappers do |b|
|
731
762
|
b.use :placeholder
|
732
763
|
b.use :label_input
|
733
|
-
b.wrapper :
|
734
|
-
component.use :hint, :
|
735
|
-
component.use :error, :
|
764
|
+
b.wrapper tag: :div, class: 'separator' do |component|
|
765
|
+
component.use :hint, wrap_with: { tag: :span, class: :hint }
|
766
|
+
component.use :error, wrap_with: { tag: :span, class: :error }
|
736
767
|
end
|
737
768
|
end
|
738
769
|
```
|
@@ -745,9 +776,9 @@ If you want to customize the custom _Form components_ on demand you can give it
|
|
745
776
|
config.wrappers do |b|
|
746
777
|
b.use :placeholder
|
747
778
|
b.use :label_input
|
748
|
-
b.wrapper :my_wrapper, :
|
749
|
-
component.use :hint, :
|
750
|
-
component.use :error, :
|
779
|
+
b.wrapper :my_wrapper, tag: :div, class: 'separator' do |component|
|
780
|
+
component.use :hint, wrap_with: { tag: :span, class: :hint }
|
781
|
+
component.use :error, wrap_with: { tag: :span, class: :error }
|
751
782
|
end
|
752
783
|
end
|
753
784
|
```
|
@@ -756,13 +787,13 @@ and now you can pass options to your `input` calls to customize the `:my_wrapper
|
|
756
787
|
|
757
788
|
```ruby
|
758
789
|
# Completely turns off the custom wrapper
|
759
|
-
f.input :name, :
|
790
|
+
f.input :name, my_wrapper: false
|
760
791
|
|
761
792
|
# Configure the html
|
762
|
-
f.input :name, :
|
793
|
+
f.input :name, my_wrapper_html: { id: 'special_id' }
|
763
794
|
|
764
795
|
# Configure the tag
|
765
|
-
f.input :name, :
|
796
|
+
f.input :name, my_wrapper_tag: :p
|
766
797
|
```
|
767
798
|
|
768
799
|
You can also define more than one wrapper and pick one to render in a specific form or input.
|
@@ -779,37 +810,37 @@ and use it in this way:
|
|
779
810
|
|
780
811
|
```ruby
|
781
812
|
# Specifying to whole form
|
782
|
-
simple_form_for @user, :
|
813
|
+
simple_form_for @user, wrapper: :small do |f|
|
783
814
|
f.input :name
|
784
815
|
end
|
785
816
|
|
786
817
|
# Specifying to one input
|
787
818
|
simple_form_for @user do |f|
|
788
|
-
f.input :name, :
|
819
|
+
f.input :name, wrapper: :small
|
789
820
|
end
|
790
821
|
```
|
791
822
|
|
792
|
-
**
|
823
|
+
**Simple Form** also allows you to use optional elements. For instance, let's suppose you want to use
|
793
824
|
hints or placeholders, but you don't want them to be generated automatically. You can set their
|
794
|
-
default values to `false` or use the `optional` method. Is
|
825
|
+
default values to `false` or use the `optional` method. Is preferable to use the `optional` syntax:
|
795
826
|
|
796
827
|
```ruby
|
797
|
-
config.wrappers :
|
828
|
+
config.wrappers placeholder: false do |b|
|
798
829
|
b.use :placeholder
|
799
830
|
b.use :label_input
|
800
|
-
b.wrapper :
|
801
|
-
component.optional :hint, :
|
802
|
-
component.use :error, :
|
831
|
+
b.wrapper tag: :div, class: 'separator' do |component|
|
832
|
+
component.optional :hint, wrap_with: { tag: :span, class: :hint }
|
833
|
+
component.use :error, wrap_with: { tag: :span, class: :error }
|
803
834
|
end
|
804
835
|
end
|
805
836
|
```
|
806
837
|
|
807
|
-
By setting it as `optional`, a hint will only be generated when
|
808
|
-
The same for
|
838
|
+
By setting it as `optional`, a hint will only be generated when `hint: true` is explicitly used.
|
839
|
+
The same for placeholder.
|
809
840
|
|
810
841
|
## HTML 5 Notice
|
811
842
|
|
812
|
-
By default, **
|
843
|
+
By default, **Simple Form** will generate input field types and attributes that are supported in HTML5,
|
813
844
|
but are considered invalid HTML for older document types such as HTML4 or XHTML1.0. The HTML5
|
814
845
|
extensions include the new field types such as email, number, search, url, tel, and the new
|
815
846
|
attributes such as required, autofocus, maxlength, min, max, step.
|
@@ -819,7 +850,7 @@ required attribute to force a value into an input and will prevent form submissi
|
|
819
850
|
Depending on the design of the application this may or may not be desired. In many cases it can
|
820
851
|
break existing UI's.
|
821
852
|
|
822
|
-
It is possible to disable all HTML 5 extensions in **
|
853
|
+
It is possible to disable all HTML 5 extensions in **Simple Form** with the following configuration:
|
823
854
|
|
824
855
|
```ruby
|
825
856
|
SimpleForm.html5 = false # default is true
|
@@ -839,14 +870,14 @@ help you to use some generic javascript validation.
|
|
839
870
|
You can also add `novalidate` to a specific form by setting the option on the form itself:
|
840
871
|
|
841
872
|
```erb
|
842
|
-
<%= simple_form_for(resource, :
|
873
|
+
<%= simple_form_for(resource, html: {novalidate: true}) do |form| %>
|
843
874
|
```
|
844
875
|
|
845
|
-
Please notice that any of the configurations above will disable the `placeholder` component,
|
876
|
+
Please notice that any of the configurations above will not disable the `placeholder` component,
|
846
877
|
which is an HTML 5 feature. We believe most of the newest browsers are handling this attribute fine,
|
847
878
|
and if they aren't, any plugin you use would take of using the placeholder attribute to do it.
|
848
879
|
However, you can disable it if you want, by removing the placeholder component from the components
|
849
|
-
list in **
|
880
|
+
list in **Simple Form** configuration file.
|
850
881
|
|
851
882
|
## Information
|
852
883
|
|
@@ -859,11 +890,11 @@ http://groups.google.com/group/plataformatec-simpleform
|
|
859
890
|
|
860
891
|
### RDocs
|
861
892
|
|
862
|
-
You can view the **
|
893
|
+
You can view the **Simple Form** documentation in RDoc format here:
|
863
894
|
|
864
895
|
http://rubydoc.info/github/plataformatec/simple_form/master/frames
|
865
896
|
|
866
|
-
If you need to use **
|
897
|
+
If you need to use **Simple Form** with Rails 2.3, you can always run `gem server` from the command line
|
867
898
|
after you install the gem to access the old documentation.
|
868
899
|
|
869
900
|
### Bug reports
|
@@ -884,3 +915,6 @@ https://github.com/plataformatec/simple_form/issues
|
|
884
915
|
## License
|
885
916
|
|
886
917
|
MIT License. Copyright 2009-2013 Plataformatec. http://plataformatec.com.br
|
918
|
+
|
919
|
+
You are not granted rights or licenses to the trademarks of the Plataformatec, including without
|
920
|
+
limitation the Simple Form name or logo.
|