simple_form 2.1.0 → 3.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of simple_form might be problematic. Click here for more details.
- checksums.yaml +7 -0
- data/CHANGELOG.md +77 -33
- data/MIT-LICENSE +1 -1
- data/README.md +387 -187
- data/lib/generators/simple_form/install_generator.rb +4 -4
- data/lib/generators/simple_form/templates/README +3 -4
- data/lib/generators/simple_form/templates/config/initializers/simple_form.rb +45 -22
- data/lib/generators/simple_form/templates/config/initializers/simple_form_bootstrap.rb +128 -24
- data/lib/generators/simple_form/templates/config/initializers/simple_form_foundation.rb +87 -6
- data/lib/generators/simple_form/templates/config/locales/simple_form.en.yml +7 -2
- data/lib/simple_form/action_view_extensions/builder.rb +2 -319
- data/lib/simple_form/action_view_extensions/form_helper.rb +8 -11
- data/lib/simple_form/components/errors.rb +28 -2
- data/lib/simple_form/components/hints.rb +8 -3
- data/lib/simple_form/components/html5.rb +6 -3
- data/lib/simple_form/components/label_input.rb +20 -2
- data/lib/simple_form/components/labels.rb +14 -10
- data/lib/simple_form/components/maxlength.rb +2 -9
- data/lib/simple_form/components/min_max.rb +1 -1
- data/lib/simple_form/components/pattern.rb +3 -3
- data/lib/simple_form/components/placeholders.rb +2 -2
- data/lib/simple_form/components/readonly.rb +1 -1
- data/lib/simple_form/components.rb +1 -1
- data/lib/simple_form/error_notification.rb +2 -2
- data/lib/simple_form/form_builder.rb +262 -107
- data/lib/simple_form/helpers.rb +6 -6
- data/lib/simple_form/inputs/base.rb +37 -16
- data/lib/simple_form/inputs/block_input.rb +2 -2
- data/lib/simple_form/inputs/boolean_input.rb +33 -18
- data/lib/simple_form/inputs/collection_input.rb +34 -13
- data/lib/simple_form/inputs/collection_radio_buttons_input.rb +7 -12
- data/lib/simple_form/inputs/collection_select_input.rb +4 -2
- data/lib/simple_form/inputs/date_time_input.rb +23 -9
- data/lib/simple_form/inputs/file_input.rb +4 -2
- data/lib/simple_form/inputs/grouped_collection_select_input.rb +15 -3
- data/lib/simple_form/inputs/hidden_input.rb +4 -2
- data/lib/simple_form/inputs/numeric_input.rb +3 -8
- data/lib/simple_form/inputs/password_input.rb +4 -3
- data/lib/simple_form/inputs/priority_input.rb +4 -2
- data/lib/simple_form/inputs/range_input.rb +1 -1
- data/lib/simple_form/inputs/string_input.rb +4 -3
- data/lib/simple_form/inputs/text_input.rb +4 -2
- data/lib/simple_form/railtie.rb +14 -0
- data/lib/simple_form/tags.rb +68 -0
- data/lib/simple_form/version.rb +1 -1
- data/lib/simple_form/wrappers/builder.rb +11 -35
- data/lib/simple_form/wrappers/leaf.rb +28 -0
- data/lib/simple_form/wrappers/many.rb +7 -7
- data/lib/simple_form/wrappers/root.rb +2 -2
- data/lib/simple_form/wrappers/single.rb +5 -3
- data/lib/simple_form/wrappers.rb +2 -1
- data/lib/simple_form.rb +99 -52
- data/test/action_view_extensions/builder_test.rb +113 -127
- data/test/action_view_extensions/form_helper_test.rb +58 -30
- data/test/components/label_test.rb +83 -83
- data/test/form_builder/association_test.rb +96 -61
- data/test/form_builder/button_test.rb +14 -14
- data/test/form_builder/error_notification_test.rb +9 -9
- data/test/form_builder/error_test.rb +159 -34
- data/test/form_builder/general_test.rb +176 -121
- data/test/form_builder/hint_test.rb +43 -37
- data/test/form_builder/input_field_test.rb +99 -52
- data/test/form_builder/label_test.rb +67 -15
- data/test/form_builder/wrapper_test.rb +157 -41
- data/test/generators/simple_form_generator_test.rb +4 -4
- data/test/inputs/boolean_input_test.rb +92 -24
- data/test/inputs/collection_check_boxes_input_test.rb +150 -71
- data/test/inputs/collection_radio_buttons_input_test.rb +213 -113
- data/test/inputs/collection_select_input_test.rb +221 -85
- data/test/inputs/datetime_input_test.rb +125 -47
- data/test/inputs/disabled_test.rb +25 -25
- data/test/inputs/discovery_test.rb +60 -10
- data/test/inputs/file_input_test.rb +3 -3
- data/test/inputs/general_test.rb +48 -32
- data/test/inputs/grouped_collection_select_input_test.rb +76 -27
- data/test/inputs/hidden_input_test.rb +6 -5
- data/test/inputs/numeric_input_test.rb +46 -46
- data/test/inputs/priority_input_test.rb +21 -15
- data/test/inputs/readonly_test.rb +31 -31
- data/test/inputs/required_test.rb +30 -18
- data/test/inputs/string_input_test.rb +53 -52
- data/test/inputs/text_input_test.rb +15 -8
- data/test/simple_form_test.rb +8 -0
- data/test/support/discovery_inputs.rb +32 -2
- data/test/support/misc_helpers.rb +130 -29
- data/test/support/mock_controller.rb +6 -6
- data/test/support/models.rb +125 -71
- data/test/test_helper.rb +28 -35
- metadata +17 -29
- data/lib/simple_form/action_view_extensions/builder.rb.orig +0 -247
- data/lib/simple_form/core_ext/hash.rb +0 -16
- data/lib/simple_form/form_builder.rb.orig +0 -486
- data/lib/simple_form/version.rb.orig +0 -7
data/README.md
CHANGED
@@ -1,12 +1,16 @@
|
|
1
|
-
|
2
|
-
[](http://travis-ci.org/plataformatec/simple_form)
|
1
|
+

|
3
2
|
|
4
|
-
|
5
|
-
|
3
|
+
By [Plataformatec](http://plataformatec.com.br/).
|
4
|
+
|
5
|
+
Rails forms made easy.
|
6
|
+
|
7
|
+
**Simple Form** aims to be as flexible as possible while helping you with powerful components to create
|
8
|
+
your forms. The basic goal of **Simple Form** is to not touch your way of defining the layout, letting
|
6
9
|
you find the better design for your eyes. Most of the DSL was inherited from Formtastic,
|
7
10
|
which we are thankful for and should make you feel right at home.
|
8
11
|
|
9
|
-
INFO: This README
|
12
|
+
INFO: This README is [also available in a friendly navigable format](http://simple-form.plataformatec.com.br/)
|
13
|
+
and refers to **Simple Form** 3.1. For older releases, check the related branch for your version.
|
10
14
|
|
11
15
|
## Installation
|
12
16
|
|
@@ -28,52 +32,62 @@ Run the generator:
|
|
28
32
|
rails generate simple_form:install
|
29
33
|
```
|
30
34
|
|
31
|
-
|
32
|
-
[country_select gem](https://rubygems.org/gems/country_select), add it to your Gemfile:
|
33
|
-
|
34
|
-
```ruby
|
35
|
-
gem 'country_select'
|
36
|
-
```
|
37
|
-
|
38
|
-
### Twitter Bootstrap
|
35
|
+
### Bootstrap
|
39
36
|
|
40
|
-
**
|
37
|
+
**Simple Form** can be easily integrated to the [Bootstrap](http://getbootstrap.com/).
|
41
38
|
To do that you have to use the `bootstrap` option in the install generator, like this:
|
42
39
|
|
43
40
|
```console
|
44
41
|
rails generate simple_form:install --bootstrap
|
45
42
|
```
|
46
43
|
|
47
|
-
You have to be sure that you added a copy of the [
|
44
|
+
You have to be sure that you added a copy of the [Bootstrap](http://getbootstrap.com/)
|
48
45
|
assets on your application.
|
49
46
|
|
50
47
|
For more information see the generator output, our
|
51
48
|
[example application code](https://github.com/rafaelfranca/simple_form-bootstrap) and
|
52
49
|
[the live example app](http://simple-form-bootstrap.plataformatec.com.br/).
|
53
50
|
|
54
|
-
|
51
|
+
### Zurb Foundation 5
|
55
52
|
|
56
|
-
|
57
|
-
|
58
|
-
To generate wrappers that are compatible with [Zurb Foundation 3](http://foundation.zurb.com/), pass the `foundation` option to the generator, like this:
|
53
|
+
To generate wrappers that are compatible with [Zurb Foundation 5](http://foundation.zurb.com/), pass
|
54
|
+
the `foundation` option to the generator, like this:
|
59
55
|
|
60
56
|
```console
|
61
57
|
rails generate simple_form:install --foundation
|
62
58
|
```
|
63
59
|
|
64
|
-
Please note that the Foundation wrapper does not support the `:hint` option by default. In order to
|
60
|
+
Please note that the Foundation wrapper does not support the `:hint` option by default. In order to
|
61
|
+
enable hints, please uncomment the appropriate line in `config/initializers/simple_form_foundation.rb`.
|
62
|
+
You will need to provide your own CSS styles for hints.
|
63
|
+
|
64
|
+
Please see the [instructions on how to install Foundation in a Rails app](http://foundation.zurb.com/docs/applications.html).
|
65
65
|
|
66
|
-
|
66
|
+
### Country Select
|
67
|
+
|
68
|
+
If you want to use the country select, you will need the
|
69
|
+
[country_select gem](https://rubygems.org/gems/country_select), add it to your Gemfile:
|
70
|
+
|
71
|
+
```ruby
|
72
|
+
gem 'country_select'
|
73
|
+
```
|
74
|
+
|
75
|
+
If you don't want to use the gem you can easily override this behaviour by mapping the
|
76
|
+
country inputs to something else, with a line like this in your `simple_form.rb` initializer:
|
77
|
+
|
78
|
+
```ruby
|
79
|
+
config.input_mappings = { /country/ => :string }
|
80
|
+
```
|
67
81
|
|
68
82
|
## Usage
|
69
83
|
|
70
|
-
**
|
84
|
+
**Simple Form** was designed to be customized as you need to. Basically it's a stack of components that
|
71
85
|
are invoked to create a complete html input for you, which by default contains label, hints, errors
|
72
86
|
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
|
87
|
+
form helpers, as they do a great job by themselves. Instead, **Simple Form** acts as a DSL and just
|
74
88
|
maps your input type (retrieved from the column definition in the database) to a specific helper method.
|
75
89
|
|
76
|
-
To start using **
|
90
|
+
To start using **Simple Form** you just have to use the helper it provides:
|
77
91
|
|
78
92
|
```erb
|
79
93
|
<%= simple_form_for @user do |f| %>
|
@@ -86,15 +100,15 @@ To start using **SimpleForm** you just have to use the helper it provides:
|
|
86
100
|
This will generate an entire form with labels for user name and password as well, and render errors
|
87
101
|
by default when you render the form with invalid data (after submitting for example).
|
88
102
|
|
89
|
-
You can overwrite the default label by passing it to the input method. You can also add a hint
|
90
|
-
even a placeholder. For boolean inputs, you can add an inline label as well:
|
103
|
+
You can overwrite the default label by passing it to the input method. You can also add a hint,
|
104
|
+
an error, or even a placeholder. For boolean inputs, you can add an inline label as well:
|
91
105
|
|
92
106
|
```erb
|
93
107
|
<%= simple_form_for @user do |f| %>
|
94
|
-
<%= f.input :username, :
|
95
|
-
<%= f.input :password, :
|
96
|
-
<%= f.input :email, :
|
97
|
-
<%= f.input :remember_me, :
|
108
|
+
<%= f.input :username, label: 'Your username please', error: 'Username is mandatory, please specify one' %>
|
109
|
+
<%= f.input :password, hint: 'No special characters.' %>
|
110
|
+
<%= f.input :email, placeholder: 'user@domain.com' %>
|
111
|
+
<%= f.input :remember_me, inline_label: 'Yes, remember me' %>
|
98
112
|
<%= f.button :submit %>
|
99
113
|
<% end %>
|
100
114
|
```
|
@@ -104,9 +118,9 @@ of any of them:
|
|
104
118
|
|
105
119
|
```erb
|
106
120
|
<%= simple_form_for @user do |f| %>
|
107
|
-
<%= f.input :username, :
|
108
|
-
<%= f.input :password, :
|
109
|
-
<%= f.input :password_confirmation, :
|
121
|
+
<%= f.input :username, label_html: { class: 'my_class' } %>
|
122
|
+
<%= f.input :password, hint: false, error_html: { id: 'password_error'} %>
|
123
|
+
<%= f.input :password_confirmation, label: false %>
|
110
124
|
<%= f.button :submit %>
|
111
125
|
<% end %>
|
112
126
|
```
|
@@ -116,9 +130,9 @@ option, for instance:
|
|
116
130
|
|
117
131
|
```erb
|
118
132
|
<%= simple_form_for @user do |f| %>
|
119
|
-
<%= f.input :username, :
|
120
|
-
<%= f.input :password, :
|
121
|
-
<%= f.input :remember_me, :
|
133
|
+
<%= f.input :username, input_html: { class: 'special' } %>
|
134
|
+
<%= f.input :password, input_html: { maxlength: 20 } %>
|
135
|
+
<%= f.input :remember_me, input_html: { value: '1' } %>
|
122
136
|
<%= f.button :submit %>
|
123
137
|
<% end %>
|
124
138
|
```
|
@@ -128,80 +142,90 @@ you can use the `:defaults` option in `simple_form_for`. Specific options in `in
|
|
128
142
|
overwrite the defaults:
|
129
143
|
|
130
144
|
```erb
|
131
|
-
<%= simple_form_for @user, :
|
132
|
-
<%= f.input :username, :
|
133
|
-
<%= f.input :password, :
|
134
|
-
<%= f.input :remember_me, :
|
145
|
+
<%= simple_form_for @user, defaults: { input_html: { class: 'default_class' } } do |f| %>
|
146
|
+
<%= f.input :username, input_html: { class: 'special' } %>
|
147
|
+
<%= f.input :password, input_html: { maxlength: 20 } %>
|
148
|
+
<%= f.input :remember_me, input_html: { value: '1' } %>
|
135
149
|
<%= f.button :submit %>
|
136
150
|
<% end %>
|
137
151
|
```
|
138
152
|
|
139
|
-
Since **
|
153
|
+
Since **Simple Form** generates a wrapper div around your label and input by default, you can pass
|
140
154
|
any html attribute to that wrapper as well using the `:wrapper_html` option, like so:
|
141
155
|
|
142
156
|
```erb
|
143
157
|
<%= simple_form_for @user do |f| %>
|
144
|
-
<%= f.input :username, :
|
145
|
-
<%= f.input :password, :
|
146
|
-
<%= f.input :remember_me, :
|
158
|
+
<%= f.input :username, wrapper_html: { class: 'username' } %>
|
159
|
+
<%= f.input :password, wrapper_html: { id: 'password' } %>
|
160
|
+
<%= f.input :remember_me, wrapper_html: { class: 'options' } %>
|
147
161
|
<%= f.button :submit %>
|
148
162
|
<% end %>
|
149
163
|
```
|
150
164
|
|
151
165
|
Required fields are marked with an * prepended to their labels.
|
152
166
|
|
153
|
-
By default all inputs are required. When the form object has `presence` validations attached to its
|
167
|
+
By default all inputs are required. When the form object has `presence` validations attached to its
|
168
|
+
fields, **Simple Form** tells required and optional fields apart. For performance reasons, this
|
169
|
+
detection is skipped on validations that make use of conditional options, such as `:if` and `:unless`.
|
154
170
|
|
155
171
|
And of course, the `required` property of any input can be overwritten as needed:
|
156
172
|
|
157
173
|
```erb
|
158
174
|
<%= simple_form_for @user do |f| %>
|
159
|
-
<%= f.input :name, :
|
175
|
+
<%= f.input :name, required: false %>
|
160
176
|
<%= f.input :username %>
|
161
177
|
<%= f.input :password %>
|
162
178
|
<%= f.button :submit %>
|
163
179
|
<% end %>
|
164
180
|
```
|
165
181
|
|
166
|
-
**
|
182
|
+
By default, **Simple Form** will look at the column type in the database and use an
|
183
|
+
appropriate input for the column. For example, a column created with type
|
184
|
+
`:text` in the database will use a `textarea` input by default. See the section
|
185
|
+
[Available input types and defaults for each column
|
186
|
+
type](https://github.com/plataformatec/simple_form#available-input-types-and-defaults-for-each-column-type)
|
187
|
+
for a complete list of defaults.
|
188
|
+
|
189
|
+
**Simple Form** also lets you overwrite the default input type it creates:
|
167
190
|
|
168
191
|
```erb
|
169
192
|
<%= simple_form_for @user do |f| %>
|
170
193
|
<%= f.input :username %>
|
171
194
|
<%= f.input :password %>
|
172
|
-
<%= f.input :description, :
|
173
|
-
<%= f.input :accepts, :
|
195
|
+
<%= f.input :description, as: :text %>
|
196
|
+
<%= f.input :accepts, as: :radio_buttons %>
|
174
197
|
<%= f.button :submit %>
|
175
198
|
<% end %>
|
176
199
|
```
|
177
200
|
|
178
201
|
So instead of a checkbox for the *accepts* attribute, you'll have a pair of radio buttons with yes/no
|
179
|
-
labels and a
|
180
|
-
attributes using
|
202
|
+
labels and a textarea instead of a text field for the description. You can also render boolean
|
203
|
+
attributes using `as: :select` to show a dropdown.
|
181
204
|
|
182
|
-
It is also possible to give the `:disabled` option to **
|
183
|
-
the wrapper as disabled with a
|
205
|
+
It is also possible to give the `:disabled` option to **Simple Form**, and it'll automatically mark
|
206
|
+
the wrapper as disabled with a CSS class, so you can style labels, hints and other components inside
|
184
207
|
the wrapper as well:
|
185
208
|
|
186
209
|
```erb
|
187
210
|
<%= simple_form_for @user do |f| %>
|
188
|
-
<%= f.input :username, :
|
211
|
+
<%= f.input :username, disabled: true, hint: 'You cannot change your username.' %>
|
189
212
|
<%= f.button :submit %>
|
190
213
|
<% end %>
|
191
214
|
```
|
192
215
|
|
193
|
-
**
|
216
|
+
**Simple Form** accepts same options as their corresponding input type helper in Rails:
|
194
217
|
|
195
218
|
```erb
|
196
219
|
<%= simple_form_for @user do |f| %>
|
197
|
-
<%= f.input :date_of_birth, :
|
198
|
-
:
|
199
|
-
:
|
220
|
+
<%= f.input :date_of_birth, as: :date, start_year: Date.today.year - 90,
|
221
|
+
end_year: Date.today.year - 12, discard_day: true,
|
222
|
+
order: [:month, :year] %>
|
223
|
+
<%= f.input :accepts, as: :boolean, checked_value: true, unchecked_value: false %>
|
200
224
|
<%= f.button :submit %>
|
201
225
|
<% end %>
|
202
226
|
```
|
203
227
|
|
204
|
-
**
|
228
|
+
**Simple Form** also allows you to use label, hint, input_field, error and full_error helpers
|
205
229
|
(please take a look at the rdocs for each method for more info):
|
206
230
|
|
207
231
|
```erb
|
@@ -209,7 +233,7 @@ the wrapper as well:
|
|
209
233
|
<%= f.label :username %>
|
210
234
|
<%= f.input_field :username %>
|
211
235
|
<%= f.hint 'No special characters, please!' %>
|
212
|
-
<%= f.error :username, :
|
236
|
+
<%= f.error :username, id: 'user_name_error' %>
|
213
237
|
<%= f.full_error :token %>
|
214
238
|
<%= f.submit 'Save' %>
|
215
239
|
<% end %>
|
@@ -217,6 +241,61 @@ the wrapper as well:
|
|
217
241
|
|
218
242
|
Any extra option passed to these methods will be rendered as html option.
|
219
243
|
|
244
|
+
### Stripping away all wrapper divs
|
245
|
+
|
246
|
+
**Simple Form** also allows you to strip away all the div wrappers around the `<input>` field that is
|
247
|
+
generated with the usual `f.input`.
|
248
|
+
The easiest way to achieve this is to use `f.input_field`.
|
249
|
+
|
250
|
+
Example:
|
251
|
+
|
252
|
+
```ruby
|
253
|
+
simple_form_for @user do |f|
|
254
|
+
f.input_field :name
|
255
|
+
f.input_field :remember_me, as: :boolean
|
256
|
+
end
|
257
|
+
```
|
258
|
+
|
259
|
+
```html
|
260
|
+
<form>
|
261
|
+
...
|
262
|
+
<input class="string required" id="user_name" maxlength="255" name="user[name]" size="255" type="text">
|
263
|
+
<input name="user[remember_me]" type="hidden" value="0">
|
264
|
+
<label class="checkbox">
|
265
|
+
<input class="boolean optional" id="user_published" name="user[remember_me]" type="checkbox" value="1">
|
266
|
+
</label>
|
267
|
+
</form>
|
268
|
+
```
|
269
|
+
|
270
|
+
For check boxes and radio buttons you can remove the label changing `boolean_style` from default value `:nested` to `:inline`.
|
271
|
+
|
272
|
+
Example:
|
273
|
+
|
274
|
+
```ruby
|
275
|
+
simple_form_for @user do |f|
|
276
|
+
f.input_field :name
|
277
|
+
f.input_field :remember_me, as: :boolean, boolean_style: :inline
|
278
|
+
end
|
279
|
+
```
|
280
|
+
|
281
|
+
```html
|
282
|
+
<form>
|
283
|
+
...
|
284
|
+
<input class="string required" id="user_name" maxlength="255" name="user[name]" size="255" type="text">
|
285
|
+
<input name="user[remember_me]" type="hidden" value="0">
|
286
|
+
<input class="boolean optional" id="user_remember_me" name="user[remember_me]" type="checkbox" value="1">
|
287
|
+
</form>
|
288
|
+
```
|
289
|
+
|
290
|
+
Produces:
|
291
|
+
|
292
|
+
```html
|
293
|
+
<input class="string required" id="user_name" maxlength="100"
|
294
|
+
name="user[name]" size="100" type="text" value="Carlos" />
|
295
|
+
```
|
296
|
+
|
297
|
+
To view the actual RDocs for this, check them out here - http://rubydoc.info/github/plataformatec/simple_form/master/SimpleForm/FormBuilder:input_field
|
298
|
+
|
220
299
|
### Collections
|
221
300
|
|
222
301
|
And what if you want to create a select containing the age from 18 to 60 in your form? You can do it
|
@@ -225,22 +304,22 @@ overriding the `:collection` option:
|
|
225
304
|
```erb
|
226
305
|
<%= simple_form_for @user do |f| %>
|
227
306
|
<%= f.input :user %>
|
228
|
-
<%= f.input :age, :
|
307
|
+
<%= f.input :age, collection: 18..60 %>
|
229
308
|
<%= f.button :submit %>
|
230
309
|
<% end %>
|
231
310
|
```
|
232
311
|
|
233
312
|
Collections can be arrays or ranges, and when a `:collection` is given the `:select` input will be
|
234
|
-
rendered by default, so we don't need to pass the
|
235
|
-
are `:radio_buttons` and `:check_boxes`. Those are added by **
|
236
|
-
helpers (read Extra Helpers
|
313
|
+
rendered by default, so we don't need to pass the `as: :select` option. Other types of collection
|
314
|
+
are `:radio_buttons` and `:check_boxes`. Those are added by **Simple Form** to Rails set of form
|
315
|
+
helpers (read Extra Helpers section below for more information).
|
237
316
|
|
238
317
|
Collection inputs accept two other options beside collections:
|
239
318
|
|
240
|
-
*
|
319
|
+
* *label_method* => the label method to be applied to the collection to retrieve the label (use this
|
241
320
|
instead of the `text_method` option in `collection_select`)
|
242
321
|
|
243
|
-
*
|
322
|
+
* *value_method* => the value method to be applied to the collection to retrieve the value
|
244
323
|
|
245
324
|
Those methods are useful to manipulate the given collection. Both of these options also accept
|
246
325
|
lambda/procs in case you want to calculate the value or label in a special way eg. custom
|
@@ -248,49 +327,50 @@ translation. All other options given are sent straight to the underlying helper.
|
|
248
327
|
can give prompt as:
|
249
328
|
|
250
329
|
```ruby
|
251
|
-
f.input :age, :
|
330
|
+
f.input :age, collection: 18..60, prompt: "Select your age", selected: 21
|
252
331
|
```
|
332
|
+
Extra options are passed into helper [`collection_select`](http://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-collection_select).
|
253
333
|
|
254
334
|
It is also possible to create grouped collection selects, that will use the html *optgroup* tags, like this:
|
255
335
|
|
256
336
|
```ruby
|
257
|
-
f.input :country_id, :
|
337
|
+
f.input :country_id, collection: @continents, as: :grouped_select, group_method: :countries
|
258
338
|
```
|
259
339
|
|
260
340
|
Grouped collection inputs accept the same `:label_method` and `:value_method` options, which will be
|
261
341
|
used to retrieve label/value attributes for the `option` tags. Besides that, you can give:
|
262
342
|
|
263
|
-
*
|
343
|
+
* *group_method* => the method to be called on the given collection to generate the options for
|
264
344
|
each group (required)
|
265
345
|
|
266
|
-
*
|
267
|
-
for the _optgroup_ (**
|
346
|
+
* *group_label_method* => the label method to be applied on the given collection to retrieve the label
|
347
|
+
for the _optgroup_ (**Simple Form** will attempt to guess the best one the same way it does with
|
268
348
|
`:label_method`)
|
269
349
|
|
270
350
|
### Priority
|
271
351
|
|
272
|
-
**
|
273
|
-
`:priority` as option to select which time zones and/or countries should be given higher priority:
|
352
|
+
**Simple Form** also supports `:time_zone` and `:country`. When using such helpers, you can give
|
353
|
+
`:priority` as an option to select which time zones and/or countries should be given higher priority:
|
274
354
|
|
275
355
|
```ruby
|
276
|
-
f.input :residence_country, :
|
277
|
-
f.input :time_zone, :
|
356
|
+
f.input :residence_country, priority: [ "Brazil" ]
|
357
|
+
f.input :time_zone, priority: /US/
|
278
358
|
```
|
279
359
|
|
280
|
-
Those values can also be configured with a default value to be used site
|
360
|
+
Those values can also be configured with a default value to be used on the site through the
|
281
361
|
`SimpleForm.country_priority` and `SimpleForm.time_zone_priority` helpers.
|
282
362
|
|
283
363
|
Note: While using `country_select` if you want to restrict to only a subset of countries for a specific
|
284
364
|
drop down then you may use the `:collection` option:
|
285
365
|
|
286
366
|
```ruby
|
287
|
-
f.input :shipping_country, :
|
367
|
+
f.input :shipping_country, priority: [ "Brazil" ], collection: [ "Australia", "Brazil", "New Zealand"]
|
288
368
|
```
|
289
369
|
|
290
370
|
### Associations
|
291
371
|
|
292
|
-
To deal with associations, **
|
293
|
-
Lets see how it works: imagine you have a user model that belongs to a company and has_and_belongs_to_many
|
372
|
+
To deal with associations, **Simple Form** can generate select inputs, a series of radios buttons or checkboxes.
|
373
|
+
Lets see how it works: imagine you have a user model that belongs to a company and `has_and_belongs_to_many`
|
294
374
|
roles. The structure would be something like:
|
295
375
|
|
296
376
|
```ruby
|
@@ -321,11 +401,11 @@ Now we have the user form:
|
|
321
401
|
|
322
402
|
Simple enough, right? This is going to render a `:select` input for choosing the `:company`, and another
|
323
403
|
`:select` input with `:multiple` option for the `:roles`. You can, of course, change it to use radio
|
324
|
-
buttons and
|
404
|
+
buttons and checkboxes as well:
|
325
405
|
|
326
406
|
```ruby
|
327
|
-
f.association :company, :
|
328
|
-
f.association :roles, :
|
407
|
+
f.association :company, as: :radio_buttons
|
408
|
+
f.association :roles, as: :check_boxes
|
329
409
|
```
|
330
410
|
|
331
411
|
The association helper just invokes `input` under the hood, so all options available to `:select`,
|
@@ -333,18 +413,21 @@ The association helper just invokes `input` under the hood, so all options avail
|
|
333
413
|
the collection by hand, all together with the prompt:
|
334
414
|
|
335
415
|
```ruby
|
336
|
-
f.association :company, :
|
416
|
+
f.association :company, collection: Company.active.order(:name), prompt: "Choose a Company"
|
337
417
|
```
|
338
418
|
|
339
419
|
In case you want to declare different labels and values:
|
340
420
|
|
341
421
|
```ruby
|
342
|
-
f.association :company, :
|
422
|
+
f.association :company, label_method: :company_name, value_method: :id, include_blank: false
|
343
423
|
```
|
344
424
|
|
425
|
+
Please note that the association helper is currently only tested with Active Record. It currently
|
426
|
+
does not work well with Mongoid and depending on the ORM you're using your mileage may vary.
|
427
|
+
|
345
428
|
### Buttons
|
346
429
|
|
347
|
-
All web forms need buttons, right? **
|
430
|
+
All web forms need buttons, right? **Simple Form** wraps them in the DSL, acting like a proxy:
|
348
431
|
|
349
432
|
```erb
|
350
433
|
<%= simple_form_for @user do |f| %>
|
@@ -355,14 +438,30 @@ All web forms need buttons, right? **SimpleForm** wraps them in the DSL, acting
|
|
355
438
|
|
356
439
|
The above will simply call submit. You choose to use it or not, it's just a question of taste.
|
357
440
|
|
441
|
+
The button method also accepts optional parameters, that are delegated to the underlying submit call:
|
442
|
+
|
443
|
+
```erb
|
444
|
+
<%= f.button :submit, "Custom Button Text", class: "my-button" %>
|
445
|
+
```
|
446
|
+
|
447
|
+
To create a `<button>` element, use the following syntax:
|
448
|
+
|
449
|
+
```erb
|
450
|
+
<%= f.button :button, "Custom Button Text" %>
|
451
|
+
|
452
|
+
<%= f.button :button do %>
|
453
|
+
Custom Button Text
|
454
|
+
<% end %>
|
455
|
+
```
|
456
|
+
|
358
457
|
### Wrapping Rails Form Helpers
|
359
458
|
|
360
|
-
Say you wanted to use a rails form helper but still wrap it in **
|
459
|
+
Say you wanted to use a rails form helper but still wrap it in **Simple Form** goodness? You can, by
|
361
460
|
calling input with a block like so:
|
362
461
|
|
363
462
|
```erb
|
364
463
|
<%= f.input :role do %>
|
365
|
-
<%= f.select :role, Role.all.map { |r| [r.name, r.id, { :
|
464
|
+
<%= f.select :role, Role.all.map { |r| [r.name, r.id, { class: r.company.id }] }, include_blank: true %>
|
366
465
|
<% end %>
|
367
466
|
```
|
368
467
|
|
@@ -371,12 +470,12 @@ hash of additional attributes for each option.
|
|
371
470
|
|
372
471
|
### Extra helpers
|
373
472
|
|
374
|
-
**
|
473
|
+
**Simple Form** also comes with some extra helpers you can use inside rails default forms without relying
|
375
474
|
on `simple_form_for` helper. They are listed below.
|
376
475
|
|
377
476
|
#### Simple Fields For
|
378
477
|
|
379
|
-
Wrapper to use **
|
478
|
+
Wrapper to use **Simple Form** inside a default rails form. It works in the same way that the `fields_for`
|
380
479
|
Rails helper, but change the builder to use the `SimpleForm::FormBuilder`.
|
381
480
|
|
382
481
|
```ruby
|
@@ -388,7 +487,6 @@ form_for @user do |f|
|
|
388
487
|
end
|
389
488
|
```
|
390
489
|
|
391
|
-
|
392
490
|
#### Collection Radio Buttons
|
393
491
|
|
394
492
|
Creates a collection of radio inputs with labels associated (same API as `collection_select`):
|
@@ -408,7 +506,7 @@ end
|
|
408
506
|
|
409
507
|
#### Collection Check Boxes
|
410
508
|
|
411
|
-
Creates a collection of
|
509
|
+
Creates a collection of checkboxes with labels associated (same API as `collection_select`):
|
412
510
|
|
413
511
|
```ruby
|
414
512
|
form_for @user do |f|
|
@@ -433,47 +531,50 @@ form_for @user do |f|
|
|
433
531
|
end
|
434
532
|
```
|
435
533
|
|
436
|
-
##
|
437
|
-
|
438
|
-
|
439
|
-
|
440
|
-
|
441
|
-
|
442
|
-
|
443
|
-
|
444
|
-
|
445
|
-
|
446
|
-
|
447
|
-
|
448
|
-
|
449
|
-
|
450
|
-
|
451
|
-
|
452
|
-
|
453
|
-
|
454
|
-
|
455
|
-
|
456
|
-
|
457
|
-
|
458
|
-
|
459
|
-
|
460
|
-
|
461
|
-
|
462
|
-
|
463
|
-
|
464
|
-
|
465
|
-
|
534
|
+
## Available input types and defaults for each column type
|
535
|
+
|
536
|
+
The following table shows the html element you will get for each attribute
|
537
|
+
according to its database definition. These defaults can be changed by
|
538
|
+
specifying the helper method in the column `Mapping` as the `as:` option.
|
539
|
+
|
540
|
+
Mapping | Generated HTML Element | Database Column Type
|
541
|
+
--------------- |:-------------------------------------|:--------------------
|
542
|
+
`boolean` | `input[type=checkbox]` | `boolean`
|
543
|
+
`string` | `input[type=text]` | `string`
|
544
|
+
`email` | `input[type=email]` | `string` with `name =~ /email/`
|
545
|
+
`url` | `input[type=url]` | `string` with `name =~ /url/`
|
546
|
+
`tel` | `input[type=tel]` | `string` with `name =~ /phone/`
|
547
|
+
`password` | `input[type=password]` | `string` with `name =~ /password/`
|
548
|
+
`search` | `input[type=search]` | -
|
549
|
+
`uuid` | `input[type=text]` | `uuid`
|
550
|
+
`text` | `textarea` | `text`
|
551
|
+
`file` | `input[type=file]` | `string` responding to file methods
|
552
|
+
`hidden` | `input[type=hidden]` | -
|
553
|
+
`integer` | `input[type=number]` | `integer`
|
554
|
+
`float` | `input[type=number]` | `float`
|
555
|
+
`decimal` | `input[type=number]` | `decimal`
|
556
|
+
`range` | `input[type=range]` | -
|
557
|
+
`datetime` | `datetime select` | `datetime/timestamp`
|
558
|
+
`date` | `date select` | `date`
|
559
|
+
`time` | `time select` | `time`
|
560
|
+
`select` | `select` | `belongs_to`/`has_many`/`has_and_belongs_to_many` associations
|
561
|
+
`radio_buttons` | collection of `input[type=radio]` | `belongs_to` associations
|
562
|
+
`check_boxes` | collection of `input[type=checkbox]` | `has_many`/`has_and_belongs_to_many` associations
|
563
|
+
`country` | `select` (countries as options) | `string` with `name =~ /country/`
|
564
|
+
`time_zone` | `select` (timezones as options) | `string` with `name =~ /time_zone/`
|
466
565
|
|
467
566
|
## Custom inputs
|
468
567
|
|
469
|
-
It is very easy to add custom inputs to **
|
568
|
+
It is very easy to add custom inputs to **Simple Form**. For instance, if you want to add a custom input
|
470
569
|
that extends the string one, you just need to add this file:
|
471
570
|
|
472
571
|
```ruby
|
473
572
|
# app/inputs/currency_input.rb
|
474
573
|
class CurrencyInput < SimpleForm::Inputs::Base
|
475
|
-
def input
|
476
|
-
|
574
|
+
def input(wrapper_options)
|
575
|
+
merged_input_options = merge_wrapper_options(input_html_options, wrapper_options)
|
576
|
+
|
577
|
+
"$ #{@builder.text_field(attribute_name, merged_input_options)}".html_safe
|
477
578
|
end
|
478
579
|
end
|
479
580
|
```
|
@@ -481,16 +582,17 @@ end
|
|
481
582
|
And use it in your views:
|
482
583
|
|
483
584
|
```ruby
|
484
|
-
f.input :money, :
|
585
|
+
f.input :money, as: :currency
|
485
586
|
```
|
587
|
+
Note, you may have to create the `app/inputs/` directory and restart your webserver.
|
486
588
|
|
487
|
-
You can also redefine existing **
|
589
|
+
You can also redefine existing **Simple Form** inputs by creating a new class with the same name. For
|
488
590
|
instance, if you want to wrap date/time/datetime in a div, you can do:
|
489
591
|
|
490
592
|
```ruby
|
491
593
|
# app/inputs/date_time_input.rb
|
492
594
|
class DateTimeInput < SimpleForm::Inputs::DateTimeInput
|
493
|
-
def input
|
595
|
+
def input(wrapper_options)
|
494
596
|
template.content_tag(:div, super)
|
495
597
|
end
|
496
598
|
end
|
@@ -507,16 +609,38 @@ class CollectionSelectInput < SimpleForm::Inputs::CollectionSelectInput
|
|
507
609
|
end
|
508
610
|
```
|
509
611
|
|
612
|
+
If needed, you can namespace your custom inputs in a module and tell **Simple Form** to look for
|
613
|
+
their definitions in this module. This can avoid conflicts with other form libraries (like Formtastic) that look up
|
614
|
+
the global context to find inputs definition too.
|
615
|
+
|
616
|
+
```ruby
|
617
|
+
# app/inputs/custom_inputs/numeric_input
|
618
|
+
module CustomInputs
|
619
|
+
class NumericInput < SimpleForm::Inputs::NumericInput
|
620
|
+
def input_html_classes
|
621
|
+
super.push('no-spinner')
|
622
|
+
end
|
623
|
+
end
|
624
|
+
end
|
625
|
+
```
|
626
|
+
|
627
|
+
And in the **SimpleForm** initializer :
|
628
|
+
|
629
|
+
```ruby
|
630
|
+
# config/simple_form.rb
|
631
|
+
config.custom_inputs_namespaces << "CustomInputs"
|
632
|
+
```
|
633
|
+
|
510
634
|
## Custom form builder
|
511
635
|
|
512
|
-
You can create a custom form builder that uses **
|
636
|
+
You can create a custom form builder that uses **Simple Form**.
|
513
637
|
|
514
638
|
Create a helper method that calls `simple_form_for` with a custom builder:
|
515
639
|
|
516
640
|
```ruby
|
517
641
|
def custom_form_for(object, *args, &block)
|
518
642
|
options = args.extract_options!
|
519
|
-
simple_form_for(object, *(args << options.merge(:
|
643
|
+
simple_form_for(object, *(args << options.merge(builder: CustomFormBuilder)), &block)
|
520
644
|
end
|
521
645
|
```
|
522
646
|
|
@@ -525,15 +649,14 @@ Create a form builder class that inherits from `SimpleForm::FormBuilder`.
|
|
525
649
|
```ruby
|
526
650
|
class CustomFormBuilder < SimpleForm::FormBuilder
|
527
651
|
def input(attribute_name, options = {}, &block)
|
528
|
-
options
|
529
|
-
super
|
652
|
+
super(attribute_name, options.merge(label: false), &block)
|
530
653
|
end
|
531
654
|
end
|
532
655
|
```
|
533
656
|
|
534
657
|
## I18n
|
535
658
|
|
536
|
-
**
|
659
|
+
**Simple Form** uses all power of I18n API to lookup labels, hints, prompts and placeholders. To customize your
|
537
660
|
forms you can create a locale file like this:
|
538
661
|
|
539
662
|
```yaml
|
@@ -551,12 +674,18 @@ en:
|
|
551
674
|
user:
|
552
675
|
username: 'Your username'
|
553
676
|
password: '****'
|
677
|
+
include_blanks:
|
678
|
+
user:
|
679
|
+
age: 'Rather not say'
|
680
|
+
prompts:
|
681
|
+
user:
|
682
|
+
gender: 'Select your gender'
|
554
683
|
```
|
555
684
|
|
556
685
|
And your forms will use this information to render the components for you.
|
557
686
|
|
558
|
-
**
|
559
|
-
|
687
|
+
**Simple Form** also lets you be more specific, separating lookups through actions.
|
688
|
+
Let's say you want a different label for new and edit actions, the locale file would
|
560
689
|
be something like:
|
561
690
|
|
562
691
|
```yaml
|
@@ -571,7 +700,7 @@ en:
|
|
571
700
|
password: 'Change password'
|
572
701
|
```
|
573
702
|
|
574
|
-
This way **
|
703
|
+
This way **Simple Form** will figure out the right translation for you, based on the action being
|
575
704
|
rendered. And to be a little bit DRYer with your locale file, you can specify defaults for all
|
576
705
|
models under the 'defaults' key:
|
577
706
|
|
@@ -594,24 +723,30 @@ en:
|
|
594
723
|
password: '****'
|
595
724
|
```
|
596
725
|
|
597
|
-
**
|
598
|
-
specific is found inside the model key.
|
599
|
-
the new syntax, just move "labels.#{attribute}" to "labels.defaults.#{attribute}".
|
726
|
+
**Simple Form** will always look for a default attribute translation under the "defaults" key if no
|
727
|
+
specific is found inside the model key.
|
600
728
|
|
601
|
-
In addition, **
|
729
|
+
In addition, **Simple Form** will fallback to default `human_attribute_name` from Rails when no other
|
602
730
|
translation is found for labels. Finally, you can also overwrite any label, hint or placeholder
|
603
731
|
inside your view, just by passing the option manually. This way the I18n lookup will be skipped.
|
604
732
|
|
605
|
-
|
733
|
+
For `:prompt` and `:include_blank` the I18n lookup is optional and to enable it is necessary to pass
|
734
|
+
`:translate` as value.
|
735
|
+
|
736
|
+
```ruby
|
737
|
+
f.input :gender, prompt: :translate
|
738
|
+
```
|
739
|
+
|
740
|
+
**Simple Form** also has support for translating options in collection helpers. For instance, given a
|
606
741
|
User with a `:gender` attribute, you might want to create a select box showing translated labels
|
607
|
-
that would post either `male` or `female` as value. With **
|
742
|
+
that would post either `male` or `female` as value. With **Simple Form** you could create an input
|
608
743
|
like this:
|
609
744
|
|
610
745
|
```ruby
|
611
|
-
f.input :gender, :
|
746
|
+
f.input :gender, collection: [:male, :female]
|
612
747
|
```
|
613
748
|
|
614
|
-
And **
|
749
|
+
And **Simple Form** will try a lookup like this in your locale file, to find the right labels to show:
|
615
750
|
|
616
751
|
```yaml
|
617
752
|
en:
|
@@ -624,7 +759,7 @@ en:
|
|
624
759
|
```
|
625
760
|
|
626
761
|
You can also use the `defaults` key as you would do with labels, hints and placeholders. It is
|
627
|
-
important to notice that **
|
762
|
+
important to notice that **Simple Form** will only do the lookup for options if you give a collection
|
628
763
|
composed of symbols only. This is to avoid constant lookups to I18n.
|
629
764
|
|
630
765
|
It's also possible to translate buttons, using Rails' built-in I18n support:
|
@@ -667,27 +802,43 @@ en:
|
|
667
802
|
name: Name
|
668
803
|
```
|
669
804
|
|
670
|
-
This difference exists because **
|
805
|
+
This difference exists because **Simple Form** relies on `object_name` provided by Rails'
|
671
806
|
FormBuilder to determine the translation path for a given object instead of `i18n_key` from the
|
672
807
|
object itself. Thus, similarly, if a form for an `Admin::User` object is defined by calling
|
673
|
-
`simple_form_for @admin_user, :
|
808
|
+
`simple_form_for @admin_user, as: :some_user`, **Simple Form** will look for translations
|
674
809
|
under `some_user` instead of `admin_user`.
|
675
810
|
|
811
|
+
When translate `simple_fields_for` attributes be sure to use the same name you pass to it, e.g. `simple_fields_for :posts` should be placed under `posts` not `post`:
|
812
|
+
|
813
|
+
```yaml
|
814
|
+
en:
|
815
|
+
simple_form:
|
816
|
+
labels:
|
817
|
+
posts:
|
818
|
+
title: 'Post title'
|
819
|
+
hints:
|
820
|
+
posts:
|
821
|
+
title: 'A good title'
|
822
|
+
placeholders:
|
823
|
+
posts:
|
824
|
+
title: 'Once upon a time...'
|
825
|
+
```
|
826
|
+
|
676
827
|
## Configuration
|
677
828
|
|
678
|
-
**
|
679
|
-
created by **
|
829
|
+
**Simple Form** has several configuration options. You can read and change them in the initializer
|
830
|
+
created by **Simple Form**, so if you haven't executed the command below yet, please do:
|
680
831
|
|
681
832
|
`rails generate simple_form:install`
|
682
833
|
|
683
834
|
### The wrappers API
|
684
835
|
|
685
|
-
With **
|
836
|
+
With **Simple Form** you can configure how your components will be rendered using the wrappers API.
|
686
837
|
The syntax looks like this:
|
687
838
|
|
688
839
|
```ruby
|
689
|
-
config.wrappers :
|
690
|
-
:
|
840
|
+
config.wrappers tag: :div, class: :input,
|
841
|
+
error_class: :field_with_errors do |b|
|
691
842
|
|
692
843
|
# Form extensions
|
693
844
|
b.use :html5
|
@@ -698,12 +849,13 @@ config.wrappers :tag => :div, :class => :input,
|
|
698
849
|
|
699
850
|
# Form components
|
700
851
|
b.use :label_input
|
701
|
-
b.use :hint, :
|
702
|
-
b.use :error, :
|
852
|
+
b.use :hint, wrap_with: { tag: :span, class: :hint }
|
853
|
+
b.use :error, wrap_with: { tag: :span, class: :error }
|
703
854
|
end
|
704
855
|
```
|
705
856
|
|
706
|
-
The _Form components_ will generate the form tags like labels, inputs, hints or errors contents.
|
857
|
+
The _Form components_ will generate the form tags like labels, inputs, hints or errors contents.
|
858
|
+
The available components are:
|
707
859
|
|
708
860
|
```ruby
|
709
861
|
:label # The <label> tag alone
|
@@ -722,24 +874,34 @@ You can create new _Form components_ using the wrappers API as in the following
|
|
722
874
|
config.wrappers do |b|
|
723
875
|
b.use :placeholder
|
724
876
|
b.use :label_input
|
725
|
-
b.wrapper :
|
726
|
-
component.use :hint, :
|
727
|
-
component.use :error, :
|
877
|
+
b.wrapper tag: :div, class: 'separator' do |component|
|
878
|
+
component.use :hint, wrap_with: { tag: :span, class: :hint }
|
879
|
+
component.use :error, wrap_with: { tag: :span, class: :error }
|
728
880
|
end
|
729
881
|
end
|
730
882
|
```
|
731
883
|
|
732
884
|
this will wrap the hint and error components within a `div` tag using the class `'separator'`.
|
733
885
|
|
886
|
+
You can customize _Form components_ passing options to them:
|
887
|
+
|
888
|
+
```ruby
|
889
|
+
config.wrappers do |b|
|
890
|
+
b.use :label_input, class: 'label-input-class'
|
891
|
+
end
|
892
|
+
```
|
893
|
+
|
894
|
+
This you set the input and label class to `'label-input-class'`.
|
895
|
+
|
734
896
|
If you want to customize the custom _Form components_ on demand you can give it a name like this:
|
735
897
|
|
736
898
|
```ruby
|
737
899
|
config.wrappers do |b|
|
738
900
|
b.use :placeholder
|
739
901
|
b.use :label_input
|
740
|
-
b.wrapper :my_wrapper, :
|
741
|
-
component.use :hint, :
|
742
|
-
component.use :error, :
|
902
|
+
b.wrapper :my_wrapper, tag: :div, class: 'separator', html: { id: 'my_wrapper_id' } do |component|
|
903
|
+
component.use :hint, wrap_with: { tag: :span, class: :hint }
|
904
|
+
component.use :error, wrap_with: { tag: :span, class: :error }
|
743
905
|
end
|
744
906
|
end
|
745
907
|
```
|
@@ -748,13 +910,13 @@ and now you can pass options to your `input` calls to customize the `:my_wrapper
|
|
748
910
|
|
749
911
|
```ruby
|
750
912
|
# Completely turns off the custom wrapper
|
751
|
-
f.input :name, :
|
913
|
+
f.input :name, my_wrapper: false
|
752
914
|
|
753
915
|
# Configure the html
|
754
|
-
f.input :name, :
|
916
|
+
f.input :name, my_wrapper_html: { id: 'special_id' }
|
755
917
|
|
756
918
|
# Configure the tag
|
757
|
-
f.input :name, :
|
919
|
+
f.input :name, my_wrapper_tag: :p
|
758
920
|
```
|
759
921
|
|
760
922
|
You can also define more than one wrapper and pick one to render in a specific form or input.
|
@@ -771,37 +933,46 @@ and use it in this way:
|
|
771
933
|
|
772
934
|
```ruby
|
773
935
|
# Specifying to whole form
|
774
|
-
simple_form_for @user, :
|
936
|
+
simple_form_for @user, wrapper: :small do |f|
|
775
937
|
f.input :name
|
776
938
|
end
|
777
939
|
|
778
940
|
# Specifying to one input
|
779
941
|
simple_form_for @user do |f|
|
780
|
-
f.input :name, :
|
942
|
+
f.input :name, wrapper: :small
|
781
943
|
end
|
782
944
|
```
|
783
945
|
|
784
|
-
**
|
946
|
+
**Simple Form** also allows you to use optional elements. For instance, let's suppose you want to use
|
785
947
|
hints or placeholders, but you don't want them to be generated automatically. You can set their
|
786
|
-
default values to `false` or use the `optional` method. Is
|
948
|
+
default values to `false` or use the `optional` method. Is preferable to use the `optional` syntax:
|
787
949
|
|
788
950
|
```ruby
|
789
|
-
config.wrappers :
|
951
|
+
config.wrappers placeholder: false do |b|
|
790
952
|
b.use :placeholder
|
791
953
|
b.use :label_input
|
792
|
-
b.wrapper :
|
793
|
-
component.optional :hint, :
|
794
|
-
component.use :error, :
|
954
|
+
b.wrapper tag: :div, class: 'separator' do |component|
|
955
|
+
component.optional :hint, wrap_with: { tag: :span, class: :hint }
|
956
|
+
component.use :error, wrap_with: { tag: :span, class: :error }
|
795
957
|
end
|
796
958
|
end
|
797
959
|
```
|
798
960
|
|
799
|
-
By setting it as `optional`, a hint will only be generated when
|
800
|
-
The same for
|
961
|
+
By setting it as `optional`, a hint will only be generated when `hint: true` is explicitly used.
|
962
|
+
The same for placeholder.
|
963
|
+
|
964
|
+
It is also possible to give the option `:unless_blank` to the wrapper if you want to render it only
|
965
|
+
when the content is present.
|
966
|
+
|
967
|
+
```ruby
|
968
|
+
b.wrapper tag: :span, class: 'hint', unless_blank: true do |component|
|
969
|
+
component.optional :hint
|
970
|
+
end
|
971
|
+
```
|
801
972
|
|
802
973
|
## HTML 5 Notice
|
803
974
|
|
804
|
-
By default, **
|
975
|
+
By default, **Simple Form** will generate input field types and attributes that are supported in HTML5,
|
805
976
|
but are considered invalid HTML for older document types such as HTML4 or XHTML1.0. The HTML5
|
806
977
|
extensions include the new field types such as email, number, search, url, tel, and the new
|
807
978
|
attributes such as required, autofocus, maxlength, min, max, step.
|
@@ -811,10 +982,25 @@ required attribute to force a value into an input and will prevent form submissi
|
|
811
982
|
Depending on the design of the application this may or may not be desired. In many cases it can
|
812
983
|
break existing UI's.
|
813
984
|
|
814
|
-
It is possible to disable all HTML 5 extensions in **
|
985
|
+
It is possible to disable all HTML 5 extensions in **Simple Form** removing the `html5` component
|
986
|
+
from the wrapper used to render the inputs.
|
987
|
+
|
988
|
+
For example, change:
|
815
989
|
|
816
990
|
```ruby
|
817
|
-
|
991
|
+
config.wrappers tag: :div do |b|
|
992
|
+
b.use :html5
|
993
|
+
|
994
|
+
b.use :label_input
|
995
|
+
end
|
996
|
+
```
|
997
|
+
|
998
|
+
To:
|
999
|
+
|
1000
|
+
```ruby
|
1001
|
+
config.wrappers tag: :div do |b|
|
1002
|
+
b.use :label_input
|
1003
|
+
end
|
818
1004
|
```
|
819
1005
|
|
820
1006
|
If you want to have all other HTML 5 features, such as the new field types, you can disable only
|
@@ -831,14 +1017,23 @@ help you to use some generic javascript validation.
|
|
831
1017
|
You can also add `novalidate` to a specific form by setting the option on the form itself:
|
832
1018
|
|
833
1019
|
```erb
|
834
|
-
<%= simple_form_for(resource, :
|
1020
|
+
<%= simple_form_for(resource, html: { novalidate: true }) do |form| %>
|
835
1021
|
```
|
836
1022
|
|
837
|
-
Please notice that
|
838
|
-
which is an HTML 5 feature. We believe most of the newest browsers are handling this attribute
|
839
|
-
and if they aren't, any plugin you use would take of
|
840
|
-
|
841
|
-
list in **
|
1023
|
+
Please notice that none of the configurations above will disable the `placeholder` component,
|
1024
|
+
which is an HTML 5 feature. We believe most of the newest browsers are handling this attribute
|
1025
|
+
just fine, and if they aren't, any plugin you use would take care of applying the placeholder.
|
1026
|
+
In any case, you can disable it if you really want to, by removing the placeholder component
|
1027
|
+
from the components list in the **Simple Form** configuration file.
|
1028
|
+
|
1029
|
+
HTML 5 date / time inputs are not generated by **Simple Form** by default, so using `date`,
|
1030
|
+
`time` or `datetime` will all generate select boxes using normal Rails helpers. We believe
|
1031
|
+
browsers are not totally ready for these yet, but you can easily opt-in on a per-input basis
|
1032
|
+
by passing the html5 option:
|
1033
|
+
|
1034
|
+
```erb
|
1035
|
+
<%= f.input :expires_at, as: :date, html5: true %>
|
1036
|
+
```
|
842
1037
|
|
843
1038
|
## Information
|
844
1039
|
|
@@ -851,13 +1046,10 @@ http://groups.google.com/group/plataformatec-simpleform
|
|
851
1046
|
|
852
1047
|
### RDocs
|
853
1048
|
|
854
|
-
You can view the **
|
1049
|
+
You can view the **Simple Form** documentation in RDoc format here:
|
855
1050
|
|
856
1051
|
http://rubydoc.info/github/plataformatec/simple_form/master/frames
|
857
1052
|
|
858
|
-
If you need to use **SimpleForm** with Rails 2.3, you can always run `gem server` from the command line
|
859
|
-
after you install the gem to access the old documentation.
|
860
|
-
|
861
1053
|
### Bug reports
|
862
1054
|
|
863
1055
|
If you discover any bugs, feel free to create an issue on GitHub. Please add as much information as
|
@@ -873,6 +1065,14 @@ https://github.com/plataformatec/simple_form/issues
|
|
873
1065
|
* Rafael Mendonça França (https://github.com/rafaelfranca)
|
874
1066
|
* Vasiliy Ermolovich (https://github.com/nashby)
|
875
1067
|
|
1068
|
+
[](http://badge.fury.io/rb/simple_form)
|
1069
|
+
[](http://travis-ci.org/plataformatec/simple_form)
|
1070
|
+
[](https://codeclimate.com/github/plataformatec/simple_form)
|
1071
|
+
[](http://inch-ci.org/github/plataformatec/simple_form)
|
1072
|
+
|
876
1073
|
## License
|
877
1074
|
|
878
|
-
MIT License. Copyright 2009-
|
1075
|
+
MIT License. Copyright 2009-2015 Plataformatec. http://plataformatec.com.br
|
1076
|
+
|
1077
|
+
You are not granted rights or licenses to the trademarks of the Plataformatec, including without
|
1078
|
+
limitation the Simple Form name or logo.
|