simple_form 2.0.0 → 2.1.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.
- data/CHANGELOG.md +34 -231
- data/MIT-LICENSE +1 -1
- data/README.md +221 -159
- data/lib/generators/simple_form/install_generator.rb +14 -5
- data/lib/generators/simple_form/templates/config/initializers/{simple_form.rb.tt → simple_form.rb} +8 -42
- data/lib/generators/simple_form/templates/config/initializers/simple_form_bootstrap.rb +45 -0
- data/lib/generators/simple_form/templates/config/initializers/simple_form_foundation.rb +26 -0
- data/lib/generators/simple_form/templates/config/locales/simple_form.en.yml +7 -5
- data/lib/simple_form/action_view_extensions/builder.rb +46 -30
- data/lib/simple_form/action_view_extensions/builder.rb.orig +247 -0
- data/lib/simple_form/action_view_extensions/form_helper.rb +7 -9
- data/lib/simple_form/components/hints.rb +3 -2
- data/lib/simple_form/components/label_input.rb +1 -1
- data/lib/simple_form/components/labels.rb +1 -1
- data/lib/simple_form/components/maxlength.rb +1 -1
- data/lib/simple_form/components/min_max.rb +2 -1
- data/lib/simple_form/components/pattern.rb +1 -1
- data/lib/simple_form/components/readonly.rb +1 -1
- data/lib/simple_form/components.rb +12 -10
- data/lib/simple_form/error_notification.rb +1 -1
- data/lib/simple_form/form_builder.rb +18 -8
- data/lib/simple_form/form_builder.rb.orig +486 -0
- data/lib/simple_form/helpers/validators.rb +2 -2
- data/lib/simple_form/inputs/base.rb +33 -8
- data/lib/simple_form/inputs/boolean_input.rb +19 -5
- data/lib/simple_form/inputs/collection_radio_buttons_input.rb +2 -6
- data/lib/simple_form/inputs/date_time_input.rb +0 -4
- data/lib/simple_form/inputs.rb +19 -17
- data/lib/simple_form/version.rb +1 -1
- data/lib/simple_form/version.rb.orig +7 -0
- data/lib/simple_form/wrappers/many.rb +5 -1
- data/lib/simple_form/wrappers/root.rb +4 -2
- data/lib/simple_form/wrappers/single.rb +6 -0
- data/lib/simple_form.rb +17 -8
- data/test/action_view_extensions/builder_test.rb +145 -66
- data/test/action_view_extensions/form_helper_test.rb +59 -20
- data/test/components/label_test.rb +34 -17
- data/test/form_builder/association_test.rb +19 -10
- data/test/form_builder/error_notification_test.rb +1 -1
- data/test/form_builder/general_test.rb +74 -12
- data/test/form_builder/hint_test.rb +15 -0
- data/test/form_builder/input_field_test.rb +45 -0
- data/test/form_builder/label_test.rb +6 -0
- data/test/form_builder/wrapper_test.rb +58 -4
- data/test/generators/simple_form_generator_test.rb +11 -1
- data/test/inputs/boolean_input_test.rb +39 -0
- data/test/inputs/datetime_input_test.rb +2 -2
- data/test/inputs/disabled_test.rb +51 -11
- data/test/inputs/discovery_test.rb +9 -1
- data/test/inputs/general_test.rb +58 -11
- data/test/inputs/grouped_collection_select_input_test.rb +15 -0
- data/test/inputs/numeric_input_test.rb +6 -0
- data/test/inputs/readonly_test.rb +51 -11
- data/test/inputs/string_input_test.rb +6 -0
- data/test/support/discovery_inputs.rb +6 -0
- data/test/support/misc_helpers.rb +41 -1
- data/test/support/models.rb +8 -4
- data/test/test_helper.rb +8 -6
- metadata +26 -13
- data/test/support/mock_response.rb +0 -14
data/README.md
CHANGED
|
@@ -1,49 +1,48 @@
|
|
|
1
1
|
# SimpleForm - Rails forms made easy.
|
|
2
|
-
[](http://travis-ci.org/plataformatec/simple_form)
|
|
2
|
+
[](http://travis-ci.org/plataformatec/simple_form)
|
|
3
3
|
|
|
4
4
|
**SimpleForm** aims to be as flexible as possible while helping you with powerful components to create
|
|
5
5
|
your forms. The basic goal of SimpleForm is to not touch your way of defining the layout, letting
|
|
6
6
|
you find the better design for your eyes. Most of the DSL was inherited from Formtastic,
|
|
7
7
|
which we are thankful for and should make you feel right at home.
|
|
8
8
|
|
|
9
|
-
INFO: This README
|
|
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
|
|
9
|
+
INFO: This README refers to **SimpleForm** 2.1. For older releases, check the related branch for your version.
|
|
14
10
|
|
|
15
11
|
## Installation
|
|
16
12
|
|
|
17
13
|
Add it to your Gemfile:
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
```ruby
|
|
16
|
+
gem 'simple_form'
|
|
17
|
+
```
|
|
20
18
|
|
|
21
19
|
Run the following command to install it:
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
```console
|
|
22
|
+
bundle install
|
|
23
|
+
```
|
|
24
24
|
|
|
25
25
|
Run the generator:
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
```console
|
|
28
|
+
rails generate simple_form:install
|
|
29
|
+
```
|
|
28
30
|
|
|
29
31
|
Also, if you want to use the country select, you will need the
|
|
30
32
|
[country_select gem](https://rubygems.org/gems/country_select), add it to your Gemfile:
|
|
31
33
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
**SimpleForm** has several configuration options. You can read and change them in the initializer
|
|
37
|
-
created by **SimpleForm**, so if you haven't executed the command below yet, please do:
|
|
38
|
-
|
|
39
|
-
`rails generate simple_form:install`
|
|
34
|
+
```ruby
|
|
35
|
+
gem 'country_select'
|
|
36
|
+
```
|
|
40
37
|
|
|
41
38
|
### Twitter Bootstrap
|
|
42
39
|
|
|
43
40
|
**SimpleForm** 2.0 can be easily integrated to the [Twitter Bootstrap](http://twitter.github.com/bootstrap).
|
|
44
41
|
To do that you have to use the `bootstrap` option in the install generator, like this:
|
|
45
42
|
|
|
46
|
-
|
|
43
|
+
```console
|
|
44
|
+
rails generate simple_form:install --bootstrap
|
|
45
|
+
```
|
|
47
46
|
|
|
48
47
|
You have to be sure that you added a copy of the [Twitter Bootstrap](http://twitter.github.com/bootstrap)
|
|
49
48
|
assets on your application.
|
|
@@ -54,116 +53,17 @@ For more information see the generator output, our
|
|
|
54
53
|
|
|
55
54
|
**NOTE**: **SimpleForm** integration requires Twitter Bootstrap version 2.0 or higher.
|
|
56
55
|
|
|
57
|
-
###
|
|
58
|
-
|
|
59
|
-
With **SimpleForm** you can configure how your components will be rendered using the wrappers API.
|
|
60
|
-
The syntax looks like this:
|
|
56
|
+
### Zurb Foundation 3
|
|
61
57
|
|
|
62
|
-
|
|
63
|
-
config.wrappers :tag => :div, :class => :input,
|
|
64
|
-
:error_class => :field_with_errors do |b|
|
|
65
|
-
|
|
66
|
-
# Form extensions
|
|
67
|
-
b.use :html5
|
|
68
|
-
b.optional :pattern
|
|
69
|
-
b.use :maxlength
|
|
70
|
-
b.use :placeholder
|
|
71
|
-
b.use :readonly
|
|
58
|
+
To generate wrappers that are compatible with [Zurb Foundation 3](http://foundation.zurb.com/), pass the `foundation` option to the generator, like this:
|
|
72
59
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
b.use :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
76
|
-
b.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
77
|
-
end
|
|
60
|
+
```console
|
|
61
|
+
rails generate simple_form:install --foundation
|
|
78
62
|
```
|
|
79
63
|
|
|
80
|
-
|
|
64
|
+
Please note that the Foundation wrapper does not support the `:hint` option by default. In order to enable hints, please uncomment the appropriate line in `config/initializers/simple_form_foundation.rb`. You will need to provide your own CSS styles for hints.
|
|
81
65
|
|
|
82
|
-
|
|
83
|
-
add extra information to your components.
|
|
84
|
-
|
|
85
|
-
You can create new _Form components_ using the wrappers API as in the following example:
|
|
86
|
-
|
|
87
|
-
```ruby
|
|
88
|
-
config.wrappers do |b|
|
|
89
|
-
b.use :placeholder
|
|
90
|
-
b.use :label_input
|
|
91
|
-
b.wrapper :tag => :div, :class => 'separator' do |component|
|
|
92
|
-
component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
93
|
-
component.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
94
|
-
end
|
|
95
|
-
end
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
this will wrap the hint and error components within a `div` tag using the class `'separator'`.
|
|
99
|
-
|
|
100
|
-
If you want to customize the custom _Form components_ on demand you can give it a name like this:
|
|
101
|
-
|
|
102
|
-
```ruby
|
|
103
|
-
config.wrappers do |b|
|
|
104
|
-
b.use :placeholder
|
|
105
|
-
b.use :label_input
|
|
106
|
-
b.wrapper :my_wrapper, :tag => :div, :class => 'separator' do |component|
|
|
107
|
-
component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
108
|
-
component.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
109
|
-
end
|
|
110
|
-
end
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
and now you can pass options to your `input` calls to customize the `:my_wrapper` _Form component_.
|
|
114
|
-
|
|
115
|
-
```ruby
|
|
116
|
-
# Completely turns off the custom wrapper
|
|
117
|
-
f.input :name, :my_wrapper => false
|
|
118
|
-
|
|
119
|
-
# Configure the html
|
|
120
|
-
f.input :name, :my_wrapper_html => { :id => 'special_id' }
|
|
121
|
-
|
|
122
|
-
# Configure the tag
|
|
123
|
-
f.input :name, :my_wrapper_tag => :p
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
You can also define more than one wrapper and pick one to render in a specific form or input.
|
|
127
|
-
To define another wrapper you have to give it a name, as the follow:
|
|
128
|
-
|
|
129
|
-
```ruby
|
|
130
|
-
config.wrappers :small do |b|
|
|
131
|
-
b.use :placeholder
|
|
132
|
-
b.use :label_input
|
|
133
|
-
end
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
and use it in this way:
|
|
137
|
-
|
|
138
|
-
```ruby
|
|
139
|
-
# Specifying to whole form
|
|
140
|
-
simple_form_for @user, :wrapper => :small do |f|
|
|
141
|
-
f.input :name
|
|
142
|
-
end
|
|
143
|
-
|
|
144
|
-
# Specifying to one input
|
|
145
|
-
simple_form_for @user do |f|
|
|
146
|
-
f.input :name, :wrapper => :small
|
|
147
|
-
end
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
**SimpleForm** also allows you to use optional elements. For instance, let's suppose you want to use
|
|
151
|
-
hints or placeholders, but you don't want them to be generated automatically. You can set their
|
|
152
|
-
default values to `false` or use the `optional` method. Is preferible to use the `optional` syntax:
|
|
153
|
-
|
|
154
|
-
```ruby
|
|
155
|
-
config.wrappers :placeholder => false do |b|
|
|
156
|
-
b.use :placeholder
|
|
157
|
-
b.use :label_input
|
|
158
|
-
b.wrapper :tag => :div, :class => 'separator' do |component|
|
|
159
|
-
component.optional :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
160
|
-
component.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
161
|
-
end
|
|
162
|
-
end
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
By setting it as `optional`, a hint will only be generated when `:hint => true` is explicitly used.
|
|
166
|
-
The same for placehold.
|
|
66
|
+
Please see the [instructions on how to install Foundation in a Rails app](http://foundation.zurb.com/docs/rails.php).
|
|
167
67
|
|
|
168
68
|
## Usage
|
|
169
69
|
|
|
@@ -171,7 +71,7 @@ The same for placehold.
|
|
|
171
71
|
are invoked to create a complete html input for you, which by default contains label, hints, errors
|
|
172
72
|
and the input itself. It does not aim to create a lot of different logic from the default Rails
|
|
173
73
|
form helpers, as they do a great work by themselves. Instead, **SimpleForm** acts as a DSL and just
|
|
174
|
-
maps your input type (retrieved from the column definition in the database) to
|
|
74
|
+
maps your input type (retrieved from the column definition in the database) to a specific helper method.
|
|
175
75
|
|
|
176
76
|
To start using **SimpleForm** you just have to use the helper it provides:
|
|
177
77
|
|
|
@@ -187,13 +87,14 @@ This will generate an entire form with labels for user name and password as well
|
|
|
187
87
|
by default when you render the form with invalid data (after submitting for example).
|
|
188
88
|
|
|
189
89
|
You can overwrite the default label by passing it to the input method. You can also add a hint or
|
|
190
|
-
even a placeholder:
|
|
90
|
+
even a placeholder. For boolean inputs, you can add an inline label as well:
|
|
191
91
|
|
|
192
92
|
```erb
|
|
193
93
|
<%= simple_form_for @user do |f| %>
|
|
194
94
|
<%= f.input :username, :label => 'Your username please' %>
|
|
195
95
|
<%= f.input :password, :hint => 'No special characters.' %>
|
|
196
96
|
<%= f.input :email, :placeholder => 'user@domain.com' %>
|
|
97
|
+
<%= f.input :remember_me, :inline_label => 'Yes, remember me' %>
|
|
197
98
|
<%= f.button :submit %>
|
|
198
99
|
<% end %>
|
|
199
100
|
```
|
|
@@ -247,8 +148,11 @@ any html attribute to that wrapper as well using the `:wrapper_html` option, lik
|
|
|
247
148
|
<% end %>
|
|
248
149
|
```
|
|
249
150
|
|
|
250
|
-
|
|
251
|
-
|
|
151
|
+
Required fields are marked with an * prepended to their labels.
|
|
152
|
+
|
|
153
|
+
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`.
|
|
154
|
+
|
|
155
|
+
And of course, the `required` property of any input can be overwritten as needed:
|
|
252
156
|
|
|
253
157
|
```erb
|
|
254
158
|
<%= simple_form_for @user do |f| %>
|
|
@@ -383,26 +287,7 @@ drop down then you may use the `:collection` option:
|
|
|
383
287
|
f.input :shipping_country, :priority => [ "Brazil" ], :collection => [ "Australia", "Brazil", "New Zealand"]
|
|
384
288
|
```
|
|
385
289
|
|
|
386
|
-
###
|
|
387
|
-
|
|
388
|
-
**SimpleForm** allows you to add a wrapper which contains the label, error, hint and input.
|
|
389
|
-
The first step is to configure a wrapper tag:
|
|
390
|
-
|
|
391
|
-
```ruby
|
|
392
|
-
SimpleForm.wrapper_tag = :p
|
|
393
|
-
```
|
|
394
|
-
|
|
395
|
-
And now, you no longer need to wrap your `f.input` calls anymore:
|
|
396
|
-
|
|
397
|
-
```erb
|
|
398
|
-
<%= simple_form_for @user do |f| %>
|
|
399
|
-
<%= f.input :username %>
|
|
400
|
-
<%= f.input :password %>
|
|
401
|
-
<%= f.button :submit %>
|
|
402
|
-
<% end %>
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
## Associations
|
|
290
|
+
### Associations
|
|
406
291
|
|
|
407
292
|
To deal with associations, **SimpleForm** can generate select inputs, a series of radios buttons or check boxes.
|
|
408
293
|
Lets see how it works: imagine you have a user model that belongs to a company and has_and_belongs_to_many
|
|
@@ -451,7 +336,13 @@ the collection by hand, all together with the prompt:
|
|
|
451
336
|
f.association :company, :collection => Company.active.all(:order => 'name'), :prompt => "Choose a Company"
|
|
452
337
|
```
|
|
453
338
|
|
|
454
|
-
|
|
339
|
+
In case you want to declare different labels and values:
|
|
340
|
+
|
|
341
|
+
```ruby
|
|
342
|
+
f.association :company, :label_method => :company_name, :value_method => :id, :include_blank => false
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### Buttons
|
|
455
346
|
|
|
456
347
|
All web forms need buttons, right? **SimpleForm** wraps them in the DSL, acting like a proxy:
|
|
457
348
|
|
|
@@ -464,7 +355,7 @@ All web forms need buttons, right? **SimpleForm** wraps them in the DSL, acting
|
|
|
464
355
|
|
|
465
356
|
The above will simply call submit. You choose to use it or not, it's just a question of taste.
|
|
466
357
|
|
|
467
|
-
|
|
358
|
+
### Wrapping Rails Form Helpers
|
|
468
359
|
|
|
469
360
|
Say you wanted to use a rails form helper but still wrap it in **SimpleForm** goodness? You can, by
|
|
470
361
|
calling input with a block like so:
|
|
@@ -478,14 +369,15 @@ calling input with a block like so:
|
|
|
478
369
|
In the above example, we're taking advantage of Rails 3's select method that allows us to pass in a
|
|
479
370
|
hash of additional attributes for each option.
|
|
480
371
|
|
|
481
|
-
|
|
372
|
+
### Extra helpers
|
|
482
373
|
|
|
483
374
|
**SimpleForm** also comes with some extra helpers you can use inside rails default forms without relying
|
|
484
375
|
on `simple_form_for` helper. They are listed below.
|
|
485
376
|
|
|
486
|
-
|
|
377
|
+
#### Simple Fields For
|
|
487
378
|
|
|
488
|
-
Wrapper to use SimpleForm inside a default rails form
|
|
379
|
+
Wrapper to use **SimpleForm** inside a default rails form. It works in the same way that the `field_for`
|
|
380
|
+
Rails helper, but change the builder to use the `SimpleForm::FormBuilder`.
|
|
489
381
|
|
|
490
382
|
```ruby
|
|
491
383
|
form_for @user do |f|
|
|
@@ -496,7 +388,8 @@ form_for @user do |f|
|
|
|
496
388
|
end
|
|
497
389
|
```
|
|
498
390
|
|
|
499
|
-
|
|
391
|
+
|
|
392
|
+
#### Collection Radio Buttons
|
|
500
393
|
|
|
501
394
|
Creates a collection of radio inputs with labels associated (same API as `collection_select`):
|
|
502
395
|
|
|
@@ -513,7 +406,7 @@ end
|
|
|
513
406
|
<label class="collection_radio_buttons" for="user_options_false">No</label>
|
|
514
407
|
```
|
|
515
408
|
|
|
516
|
-
|
|
409
|
+
#### Collection Check Boxes
|
|
517
410
|
|
|
518
411
|
Creates a collection of check boxes with labels associated (same API as `collection_select`):
|
|
519
412
|
|
|
@@ -544,7 +437,7 @@ end
|
|
|
544
437
|
|
|
545
438
|
**SimpleForm** comes with a lot of default mappings:
|
|
546
439
|
|
|
547
|
-
```
|
|
440
|
+
```text
|
|
548
441
|
Mapping Input Column Type
|
|
549
442
|
|
|
550
443
|
boolean check box boolean
|
|
@@ -598,7 +491,18 @@ instance, if you want to wrap date/time/datetime in a div, you can do:
|
|
|
598
491
|
# app/inputs/date_time_input.rb
|
|
599
492
|
class DateTimeInput < SimpleForm::Inputs::DateTimeInput
|
|
600
493
|
def input
|
|
601
|
-
|
|
494
|
+
template.content_tag(:div, super)
|
|
495
|
+
end
|
|
496
|
+
end
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
Or if you want to add a class to all the select fields you can do:
|
|
500
|
+
|
|
501
|
+
```ruby
|
|
502
|
+
# app/inputs/collection_select_input.rb
|
|
503
|
+
class CollectionSelectInput < SimpleForm::Inputs::CollectionSelectInput
|
|
504
|
+
def input_html_classes
|
|
505
|
+
super.push('chosen')
|
|
602
506
|
end
|
|
603
507
|
end
|
|
604
508
|
```
|
|
@@ -691,7 +595,7 @@ en:
|
|
|
691
595
|
```
|
|
692
596
|
|
|
693
597
|
**SimpleForm** will always look for a default attribute translation under the "defaults" key if no
|
|
694
|
-
specific is found inside the model key.Note that this syntax is different from 1.x. To migrate to
|
|
598
|
+
specific is found inside the model key. Note that this syntax is different from 1.x. To migrate to
|
|
695
599
|
the new syntax, just move "labels.#{attribute}" to "labels.defaults.#{attribute}".
|
|
696
600
|
|
|
697
601
|
In addition, **SimpleForm** will fallback to default human_attribute_name from Rails when no other
|
|
@@ -716,7 +620,7 @@ en:
|
|
|
716
620
|
user:
|
|
717
621
|
gender:
|
|
718
622
|
male: 'Male'
|
|
719
|
-
female:
|
|
623
|
+
female: 'Female'
|
|
720
624
|
```
|
|
721
625
|
|
|
722
626
|
You can also use the `defaults` key as you would do with labels, hints and placeholders. It is
|
|
@@ -738,6 +642,163 @@ There are other options that can be configured through I18n API, such as require
|
|
|
738
642
|
Be sure to check our locale file or the one copied to your application after you run
|
|
739
643
|
`rails generate simple_form:install`.
|
|
740
644
|
|
|
645
|
+
It should be noted that translations for labels, hints and placeholders for a namespaced model, e.g.
|
|
646
|
+
`Admin::User`, should be placed under `admin_user`, not under `admin/user`. This is different from
|
|
647
|
+
how translations for namespaced model and attribute names are defined:
|
|
648
|
+
|
|
649
|
+
```yaml
|
|
650
|
+
en:
|
|
651
|
+
activerecord:
|
|
652
|
+
models:
|
|
653
|
+
admin/user: User
|
|
654
|
+
attributes:
|
|
655
|
+
admin/user:
|
|
656
|
+
name: Name
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
They should be placed under `admin/user`. Form labels, hints and placeholders for those attributes,
|
|
660
|
+
though, should be placed under `admin_user`:
|
|
661
|
+
|
|
662
|
+
```yaml
|
|
663
|
+
en:
|
|
664
|
+
simple_form:
|
|
665
|
+
labels:
|
|
666
|
+
admin_user:
|
|
667
|
+
name: Name
|
|
668
|
+
```
|
|
669
|
+
|
|
670
|
+
This difference exists because **SimpleForm** relies on `object_name` provided by Rails'
|
|
671
|
+
FormBuilder to determine the translation path for a given object instead of `i18n_key` from the
|
|
672
|
+
object itself. Thus, similarly, if a form for an `Admin::User` object is defined by calling
|
|
673
|
+
`simple_form_for @admin_user, :as => :some_user`, **SimpleForm** will look for translations
|
|
674
|
+
under `some_user` instead of `admin_user`.
|
|
675
|
+
|
|
676
|
+
## Configuration
|
|
677
|
+
|
|
678
|
+
**SimpleForm** has several configuration options. You can read and change them in the initializer
|
|
679
|
+
created by **SimpleForm**, so if you haven't executed the command below yet, please do:
|
|
680
|
+
|
|
681
|
+
`rails generate simple_form:install`
|
|
682
|
+
|
|
683
|
+
### The wrappers API
|
|
684
|
+
|
|
685
|
+
With **SimpleForm** you can configure how your components will be rendered using the wrappers API.
|
|
686
|
+
The syntax looks like this:
|
|
687
|
+
|
|
688
|
+
```ruby
|
|
689
|
+
config.wrappers :tag => :div, :class => :input,
|
|
690
|
+
:error_class => :field_with_errors do |b|
|
|
691
|
+
|
|
692
|
+
# Form extensions
|
|
693
|
+
b.use :html5
|
|
694
|
+
b.optional :pattern
|
|
695
|
+
b.use :maxlength
|
|
696
|
+
b.use :placeholder
|
|
697
|
+
b.use :readonly
|
|
698
|
+
|
|
699
|
+
# Form components
|
|
700
|
+
b.use :label_input
|
|
701
|
+
b.use :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
702
|
+
b.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
703
|
+
end
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
The _Form components_ will generate the form tags like labels, inputs, hints or errors contents. The available components are:
|
|
707
|
+
|
|
708
|
+
```ruby
|
|
709
|
+
:label # The <label> tag alone
|
|
710
|
+
:input # The <input> tag alone
|
|
711
|
+
:label_input # The <label> and the <input> tags
|
|
712
|
+
:hint # The hint for the input
|
|
713
|
+
:error # The error for the input
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
The _Form extensions_ are used to generate some attributes or perform some lookups on the model to
|
|
717
|
+
add extra information to your components.
|
|
718
|
+
|
|
719
|
+
You can create new _Form components_ using the wrappers API as in the following example:
|
|
720
|
+
|
|
721
|
+
```ruby
|
|
722
|
+
config.wrappers do |b|
|
|
723
|
+
b.use :placeholder
|
|
724
|
+
b.use :label_input
|
|
725
|
+
b.wrapper :tag => :div, :class => 'separator' do |component|
|
|
726
|
+
component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
727
|
+
component.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
728
|
+
end
|
|
729
|
+
end
|
|
730
|
+
```
|
|
731
|
+
|
|
732
|
+
this will wrap the hint and error components within a `div` tag using the class `'separator'`.
|
|
733
|
+
|
|
734
|
+
If you want to customize the custom _Form components_ on demand you can give it a name like this:
|
|
735
|
+
|
|
736
|
+
```ruby
|
|
737
|
+
config.wrappers do |b|
|
|
738
|
+
b.use :placeholder
|
|
739
|
+
b.use :label_input
|
|
740
|
+
b.wrapper :my_wrapper, :tag => :div, :class => 'separator' do |component|
|
|
741
|
+
component.use :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
742
|
+
component.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
743
|
+
end
|
|
744
|
+
end
|
|
745
|
+
```
|
|
746
|
+
|
|
747
|
+
and now you can pass options to your `input` calls to customize the `:my_wrapper` _Form component_.
|
|
748
|
+
|
|
749
|
+
```ruby
|
|
750
|
+
# Completely turns off the custom wrapper
|
|
751
|
+
f.input :name, :my_wrapper => false
|
|
752
|
+
|
|
753
|
+
# Configure the html
|
|
754
|
+
f.input :name, :my_wrapper_html => { :id => 'special_id' }
|
|
755
|
+
|
|
756
|
+
# Configure the tag
|
|
757
|
+
f.input :name, :my_wrapper_tag => :p
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
You can also define more than one wrapper and pick one to render in a specific form or input.
|
|
761
|
+
To define another wrapper you have to give it a name, as the follow:
|
|
762
|
+
|
|
763
|
+
```ruby
|
|
764
|
+
config.wrappers :small do |b|
|
|
765
|
+
b.use :placeholder
|
|
766
|
+
b.use :label_input
|
|
767
|
+
end
|
|
768
|
+
```
|
|
769
|
+
|
|
770
|
+
and use it in this way:
|
|
771
|
+
|
|
772
|
+
```ruby
|
|
773
|
+
# Specifying to whole form
|
|
774
|
+
simple_form_for @user, :wrapper => :small do |f|
|
|
775
|
+
f.input :name
|
|
776
|
+
end
|
|
777
|
+
|
|
778
|
+
# Specifying to one input
|
|
779
|
+
simple_form_for @user do |f|
|
|
780
|
+
f.input :name, :wrapper => :small
|
|
781
|
+
end
|
|
782
|
+
```
|
|
783
|
+
|
|
784
|
+
**SimpleForm** also allows you to use optional elements. For instance, let's suppose you want to use
|
|
785
|
+
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 preferible to use the `optional` syntax:
|
|
787
|
+
|
|
788
|
+
```ruby
|
|
789
|
+
config.wrappers :placeholder => false do |b|
|
|
790
|
+
b.use :placeholder
|
|
791
|
+
b.use :label_input
|
|
792
|
+
b.wrapper :tag => :div, :class => 'separator' do |component|
|
|
793
|
+
component.optional :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
794
|
+
component.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
795
|
+
end
|
|
796
|
+
end
|
|
797
|
+
```
|
|
798
|
+
|
|
799
|
+
By setting it as `optional`, a hint will only be generated when `:hint => true` is explicitly used.
|
|
800
|
+
The same for placehold.
|
|
801
|
+
|
|
741
802
|
## HTML 5 Notice
|
|
742
803
|
|
|
743
804
|
By default, **SimpleForm** will generate input field types and attributes that are supported in HTML5,
|
|
@@ -810,7 +871,8 @@ https://github.com/plataformatec/simple_form/issues
|
|
|
810
871
|
* José Valim (https://github.com/josevalim)
|
|
811
872
|
* Carlos Antonio da Silva (https://github.com/carlosantoniodasilva)
|
|
812
873
|
* Rafael Mendonça França (https://github.com/rafaelfranca)
|
|
874
|
+
* Vasiliy Ermolovich (https://github.com/nashby)
|
|
813
875
|
|
|
814
876
|
## License
|
|
815
877
|
|
|
816
|
-
MIT License. Copyright
|
|
878
|
+
MIT License. Copyright 2009-2013 Plataformatec. http://plataformatec.com.br
|
|
@@ -5,16 +5,25 @@ module SimpleForm
|
|
|
5
5
|
source_root File.expand_path('../templates', __FILE__)
|
|
6
6
|
class_option :template_engine, :desc => 'Template engine to be invoked (erb, haml or slim).'
|
|
7
7
|
class_option :bootstrap, :type => :boolean, :desc => 'Add the Twitter Bootstrap wrappers to the SimpleForm initializer.'
|
|
8
|
+
class_option :foundation, :type => :boolean, :desc => 'Add the Zurb Foundation 3 wrappers to the SimpleForm initializer.'
|
|
8
9
|
|
|
9
10
|
def info_bootstrap
|
|
10
|
-
return if options.bootstrap?
|
|
11
|
-
puts "SimpleForm 2 supports Twitter
|
|
12
|
-
"
|
|
13
|
-
"generator
|
|
11
|
+
return if options.bootstrap? || options.foundation?
|
|
12
|
+
puts "SimpleForm 2 supports Twitter Bootstrap and Zurb Foundation 3. If you want "\
|
|
13
|
+
"a configuration that is compatible with one of these frameworks, then please " \
|
|
14
|
+
"re-run this generator with --bootstrap or --foundation as an option."
|
|
14
15
|
end
|
|
15
16
|
|
|
16
17
|
def copy_config
|
|
17
|
-
|
|
18
|
+
template "config/initializers/simple_form.rb"
|
|
19
|
+
|
|
20
|
+
if options[:bootstrap]
|
|
21
|
+
template "config/initializers/simple_form_bootstrap.rb"
|
|
22
|
+
elsif options[:foundation]
|
|
23
|
+
template "config/initializers/simple_form_foundation.rb"
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
directory 'config/locales'
|
|
18
27
|
end
|
|
19
28
|
|
|
20
29
|
def copy_scaffold_template
|
data/lib/generators/simple_form/templates/config/initializers/{simple_form.rb.tt → simple_form.rb}
RENAMED
|
@@ -44,50 +44,10 @@ SimpleForm.setup do |config|
|
|
|
44
44
|
b.use :hint, :wrap_with => { :tag => :span, :class => :hint }
|
|
45
45
|
b.use :error, :wrap_with => { :tag => :span, :class => :error }
|
|
46
46
|
end
|
|
47
|
-
<% if options.bootstrap? %>
|
|
48
|
-
config.wrappers :bootstrap, :tag => 'div', :class => 'control-group', :error_class => 'error' do |b|
|
|
49
|
-
b.use :placeholder
|
|
50
|
-
b.use :label
|
|
51
|
-
b.wrapper :tag => 'div', :class => 'controls' do |ba|
|
|
52
|
-
ba.use :input
|
|
53
|
-
ba.use :error, :wrap_with => { :tag => 'span', :class => 'help-inline' }
|
|
54
|
-
ba.use :hint, :wrap_with => { :tag => 'p', :class => 'help-block' }
|
|
55
|
-
end
|
|
56
|
-
end
|
|
57
|
-
|
|
58
|
-
config.wrappers :prepend, :tag => 'div', :class => "control-group", :error_class => 'error' do |b|
|
|
59
|
-
b.use :placeholder
|
|
60
|
-
b.use :label
|
|
61
|
-
b.wrapper :tag => 'div', :class => 'controls' do |input|
|
|
62
|
-
input.wrapper :tag => 'div', :class => 'input-prepend' do |prepend|
|
|
63
|
-
prepend.use :input
|
|
64
|
-
end
|
|
65
|
-
input.use :hint, :wrap_with => { :tag => 'span', :class => 'help-block' }
|
|
66
|
-
input.use :error, :wrap_with => { :tag => 'span', :class => 'help-inline' }
|
|
67
|
-
end
|
|
68
|
-
end
|
|
69
47
|
|
|
70
|
-
config.wrappers :append, :tag => 'div', :class => "control-group", :error_class => 'error' do |b|
|
|
71
|
-
b.use :placeholder
|
|
72
|
-
b.use :label
|
|
73
|
-
b.wrapper :tag => 'div', :class => 'controls' do |input|
|
|
74
|
-
input.wrapper :tag => 'div', :class => 'input-append' do |append|
|
|
75
|
-
append.use :input
|
|
76
|
-
end
|
|
77
|
-
input.use :hint, :wrap_with => { :tag => 'span', :class => 'help-block' }
|
|
78
|
-
input.use :error, :wrap_with => { :tag => 'span', :class => 'help-inline' }
|
|
79
|
-
end
|
|
80
|
-
end
|
|
81
|
-
|
|
82
|
-
# Wrappers for forms and inputs using the Twitter Bootstrap toolkit.
|
|
83
|
-
# Check the Bootstrap docs (http://twitter.github.com/bootstrap)
|
|
84
|
-
# to learn about the different styles for forms and inputs,
|
|
85
|
-
# buttons and other elements.
|
|
86
|
-
config.default_wrapper = :bootstrap
|
|
87
|
-
<% else %>
|
|
88
48
|
# The default wrapper to be used by the FormBuilder.
|
|
89
49
|
config.default_wrapper = :default
|
|
90
|
-
|
|
50
|
+
|
|
91
51
|
# Define the way to render check boxes / radio buttons with labels.
|
|
92
52
|
# Defaults to :nested for bootstrap config.
|
|
93
53
|
# :inline => input + label
|
|
@@ -97,7 +57,9 @@ SimpleForm.setup do |config|
|
|
|
97
57
|
# Default class for buttons
|
|
98
58
|
config.button_class = 'btn'
|
|
99
59
|
|
|
100
|
-
# Method used to tidy up errors.
|
|
60
|
+
# Method used to tidy up errors. Specify any Rails Array method.
|
|
61
|
+
# :first lists the first message for each field.
|
|
62
|
+
# Use :to_sentence to list all errors for each field.
|
|
101
63
|
# config.error_method = :first
|
|
102
64
|
|
|
103
65
|
# Default tag used for error notification helper.
|
|
@@ -156,6 +118,10 @@ SimpleForm.setup do |config|
|
|
|
156
118
|
# matches the regexp as value.
|
|
157
119
|
# config.input_mappings = { /count/ => :integer }
|
|
158
120
|
|
|
121
|
+
# Custom wrappers for input types. This should be a hash containing an input
|
|
122
|
+
# type as key and the wrapper that will be used for all inputs with specified type.
|
|
123
|
+
# config.wrapper_mappings = { :string => :prepend }
|
|
124
|
+
|
|
159
125
|
# Default priority for time_zone inputs.
|
|
160
126
|
# config.time_zone_priority = nil
|
|
161
127
|
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Use this setup block to configure all options available in SimpleForm.
|
|
2
|
+
SimpleForm.setup do |config|
|
|
3
|
+
config.wrappers :bootstrap, :tag => 'div', :class => 'control-group', :error_class => 'error' do |b|
|
|
4
|
+
b.use :html5
|
|
5
|
+
b.use :placeholder
|
|
6
|
+
b.use :label
|
|
7
|
+
b.wrapper :tag => 'div', :class => 'controls' do |ba|
|
|
8
|
+
ba.use :input
|
|
9
|
+
ba.use :error, :wrap_with => { :tag => 'span', :class => 'help-inline' }
|
|
10
|
+
ba.use :hint, :wrap_with => { :tag => 'p', :class => 'help-block' }
|
|
11
|
+
end
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
config.wrappers :prepend, :tag => 'div', :class => "control-group", :error_class => 'error' do |b|
|
|
15
|
+
b.use :html5
|
|
16
|
+
b.use :placeholder
|
|
17
|
+
b.use :label
|
|
18
|
+
b.wrapper :tag => 'div', :class => 'controls' do |input|
|
|
19
|
+
input.wrapper :tag => 'div', :class => 'input-prepend' do |prepend|
|
|
20
|
+
prepend.use :input
|
|
21
|
+
end
|
|
22
|
+
input.use :hint, :wrap_with => { :tag => 'span', :class => 'help-block' }
|
|
23
|
+
input.use :error, :wrap_with => { :tag => 'span', :class => 'help-inline' }
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
config.wrappers :append, :tag => 'div', :class => "control-group", :error_class => 'error' do |b|
|
|
28
|
+
b.use :html5
|
|
29
|
+
b.use :placeholder
|
|
30
|
+
b.use :label
|
|
31
|
+
b.wrapper :tag => 'div', :class => 'controls' do |input|
|
|
32
|
+
input.wrapper :tag => 'div', :class => 'input-append' do |append|
|
|
33
|
+
append.use :input
|
|
34
|
+
end
|
|
35
|
+
input.use :hint, :wrap_with => { :tag => 'span', :class => 'help-block' }
|
|
36
|
+
input.use :error, :wrap_with => { :tag => 'span', :class => 'help-inline' }
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# Wrappers for forms and inputs using the Twitter Bootstrap toolkit.
|
|
41
|
+
# Check the Bootstrap docs (http://twitter.github.com/bootstrap)
|
|
42
|
+
# to learn about the different styles for forms and inputs,
|
|
43
|
+
# buttons and other elements.
|
|
44
|
+
config.default_wrapper = :bootstrap
|
|
45
|
+
end
|