Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 315 lines (216 sloc) 12.883 kB
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
1 == SimpleForm
a7d0cc2 @carlosantoniodasilva Initial commit.
carlosantoniodasilva authored
2
6eb0470 @josevalim Update README
josevalim authored
3 Forms made easy (for Rails)!
a7d0cc2 @carlosantoniodasilva Initial commit.
carlosantoniodasilva authored
4
6eb0470 @josevalim Update README
josevalim authored
5 SimpleForm aims to be as flexible as possible while helping you with powerful components to create your forms. The basic goal of simple form is to not touch your way of defining the layout, this way letting you find how you find the better design for your eyes. Good part of the DSL was inherited from Formtastic, which we are thankful for and should make you feel right at home.
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
6
6eb0470 @josevalim Update README
josevalim authored
7 == Installation
8
9 Install the gem:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
10
1037fc4 @josevalim Bump to 1.1.1.
josevalim authored
11 sudo gem install simple_form
6eb0470 @josevalim Update README
josevalim authored
12
13 Run the generator:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
14
151411f @josevalim Stub out Rails 3 compatible branch.
josevalim authored
15 rails generate simple_form_install
16
17 And you are ready to go. Since this branch is aims Rails 3 support,
18 if you want to use it with Rails 2.3 you should check this branch:
6eb0470 @josevalim Update README
josevalim authored
19
151411f @josevalim Stub out Rails 3 compatible branch.
josevalim authored
20 http://github.com/plataformatec/simple_form/tree/v1.0
6eb0470 @josevalim Update README
josevalim authored
21
22 == Usage
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
23
6eb0470 @josevalim Update README
josevalim authored
24 SimpleForm was designed to be customized as you need to. Basically it's a stack of components that are invoked to create a complete html input for you, which by default contains label, hints, errors and the input itself. It does not aim to create a lot of different logic from the default Rails form helpers, as they do a great work by themselves. Instead, SimpleForm acts as a DSL and just maps your input type (retrieved from the column definition in the database) to an specific helper method.
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
25
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
26 To start using SimpleForm you just have to use the helper it provides:
27
28 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
29 <%= f.input :username %>
30 <%= f.input :password %>
31 <%= f.button :submit %>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
32 <% end -%>
33
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
34 This will generate an entire form with labels for user name and password as well, and render errors by default when you render the form with invalid data (after submitting for example).
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
35
36 You can overwrite the default label by passing it to the input method, or even add a hint:
37
38 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
39 <%= f.input :username, :label => 'Your username please' %>
40 <%= f.input :password, :hint => 'No special characters.' %>
41 <%= f.button :submit %>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
42 <% end -%>
43
6eb0470 @josevalim Update README
josevalim authored
44 You can also disable labels, hints or error or configure the html of any of them:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
45
46 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
47 <%= f.input :username, :label_html => { :class => 'my_class' } %>
48 <%= f.input :password, :hint => false, :error_html => { :id => "password_error"} %>
49 <%= f.input :password_confirmation, :label => false %>
50 <%= f.button :submit %>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
51 <% end -%>
52
6eb0470 @josevalim Update README
josevalim authored
53 By default all inputs are required, which means an * is prepended to the label, but you can disable it in any input you want:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
54
55 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
56 <%= f.input :name, :required => false %>
57 <%= f.input :username %>
58 <%= f.input :password %>
59 <%= f.button :submit %>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
60 <% end -%>
61
6eb0470 @josevalim Update README
josevalim authored
62 SimpleForm also lets you overwrite the default input type it creates:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
63
64 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
65 <%= f.input :username %>
66 <%= f.input :password %>
67 <%= f.input :description, :as => :text %>
68 <%= f.input :accepts, :as => :radio %>
69 <%= f.button :submit %>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
70 <% end -%>
71
6eb0470 @josevalim Update README
josevalim authored
72 So instead of a checkbox for the :accepts attribute, you'll have a pair of radio buttons with yes/no labels and a text area instead of a text field for the description. You can also render boolean attributes using :as => :select to show a dropdown.
73
74 SimpleForm also allows you using label, hint and error helpers it provides:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
75
76 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
77 <%= f.label :username %>
78 <%= f.text_field :username %>
79 <%= f.error :username, :id => 'user_name_error' %>
80 <%= f.hint 'No special characters, please!' %>
81 <%= f.submit 'Save' %>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
82 <% end -%>
83
6eb0470 @josevalim Update README
josevalim authored
84 Any extra option passed to label, hint or error will be rendered as html option.
85
86 === Collections
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
87
6eb0470 @josevalim Update README
josevalim authored
88 And what if you want to create a select containing the age from 18 to 60 in your form? You can do it overriding the :collection option:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
89
90 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
91 <%= f.input :user %>
92 <%= f.input :age, :collection => 18..60 %>
93 <%= f.button :submit %>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
94 <% end -%>
95
6eb0470 @josevalim Update README
josevalim authored
96 Collections can be arrays or ranges, and when a :collection is given the :select input will be rendered by default, so we don't need to pass the :as => :select option. Other types of collection are :radio and :check_boxes. Those are added by SimpleForm to Rails set of form helpers (read Extra Helpers session below for more information).
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
97
6eb0470 @josevalim Update README
josevalim authored
98 Collection inputs accepts two other options beside collections:
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
99
6eb0470 @josevalim Update README
josevalim authored
100 * label_method => the label method to be applied to the collection to retrieve the label
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
101
6eb0470 @josevalim Update README
josevalim authored
102 * value_method => the value method to be applied to the collection to retrieve the value
103
104 Those methods are useful to manipulate the given collection. All other options given are sent straight to the underlying helper. For example, you can give prompt as:
105
106 f.input :age, :collection => 18..60, :prompt => "Select your age"
107
108 === Priority
109
110 SimpleForm also supports :time_zone and :country. When using such helpers, you can give :priority as option to select which time zones and/or countries should be given higher priority:
111
f38fe38 @carlosantoniodasilva Adding simple_form_install generator, and fix tabs and typo in README
carlosantoniodasilva authored
112 f.input :residence_country, :priority => [ "Brazil" ]
6eb0470 @josevalim Update README
josevalim authored
113 f.input :time_zone, :priority => /US/
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
114
6eb0470 @josevalim Update README
josevalim authored
115 Those values can also be configured with a default value to be used site use through the SimpleForm.country_priority and SimpleForm.time_zone_priority helpers.
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
116
6eb0470 @josevalim Update README
josevalim authored
117 === Wrapper
118
119 SimpleForm allows you to add a wrapper which contains the label, error, hint and input.
120 The first step is to configure a wrapper tag:
121
f38fe38 @carlosantoniodasilva Adding simple_form_install generator, and fix tabs and typo in README
carlosantoniodasilva authored
122 SimpleForm.wrapper_tag = :p
6eb0470 @josevalim Update README
josevalim authored
123
9599f83 @josevalim Update README.
josevalim authored
124 And now, you don't need to wrap your f.input calls with anymore:
6eb0470 @josevalim Update README
josevalim authored
125
f38fe38 @carlosantoniodasilva Adding simple_form_install generator, and fix tabs and typo in README
carlosantoniodasilva authored
126 <% simple_form_for @user do |f| -%>
127 <%= f.input :username %>
128 <%= f.input :password %>
9599f83 @josevalim Update README.
josevalim authored
129 <%= f.button :submit %>
f38fe38 @carlosantoniodasilva Adding simple_form_install generator, and fix tabs and typo in README
carlosantoniodasilva authored
130 <% end -%>
6eb0470 @josevalim Update README
josevalim authored
131
132 == Associations
133
134 To deal with associations, SimpleForm can generate select inputs or a series of radios or check boxes. Lets see how it works: imagine you have the user model that belongs to a company and has_and_belongs_to_many roles. The structure should be something like:
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
135
136 class User < ActiveRecord::Base
137 belongs_to :company
138 has_and_belongs_to_many :roles
139 end
140
141 class Company < ActiveRecord::Base
142 has_many :users
143 end
144
145 class Role < ActiveRecord::Base
146 has_and_belongs_to_many :users
147 end
148
149 Now we have the user form:
150
151 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
152 <%= f.input :name %>
153 <%= f.association :company %>
154 <%= f.association :roles %>
155 <%= f.button :submit %>
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
156 <% end -%>
157
158 Simple enough right? This is going to render a :select input for choosing the :company, and another :select input with :multiple option for the :roles. You can of course change it, to use radios and check boxes as well:
159
151411f @josevalim Stub out Rails 3 compatible branch.
josevalim authored
160 f.association :company, :as => :radio
161 f.association :roles, :as => :check_boxes
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
162
5cb92a2 @josevalim Remove useless API.
josevalim authored
163 The association helper just invokes input under the hood, so all options available to :select, :radio and :check_boxes are also available to association. Additionally, you can specify the collection by hand, all together with the prompt:
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
164
6eb0470 @josevalim Update README
josevalim authored
165 f.association :company, :collection => Company.active.all(:order => 'name'), :prompt => "Choose a Company"
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
166
6eb0470 @josevalim Update README
josevalim authored
167 == Buttons
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
168
63d5695 @josevalim Update README.
josevalim authored
169 All web forms need buttons, right? SimpleForm wraps them in the DSL, acting like a proxy:
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
170
171 <% simple_form_for @user do |f| -%>
9599f83 @josevalim Update README.
josevalim authored
172 <%= f.input :name %>
173 <%= f.button :submit %>
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
174 <% end -%>
175
63d5695 @josevalim Update README.
josevalim authored
176 The above will simply call submit. You choose to use it or not, it's just a question of taste.
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
177
178 == Extra helpers
179
6eb0470 @josevalim Update README
josevalim authored
180 SimpleForm also comes with some extra helpers you can use inside rails default forms without relying on simple_form_for helper. They are listed below.
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
181
182 === Simple Fields For
183
6eb0470 @josevalim Update README
josevalim authored
184 Wrapper to use simple form inside a default rails form
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
185
186 form_for @user do |f|
187 f.simple_fields_for :posts do |posts_form|
188 # Here you have all simple_form methods available
189 posts_form.input :title
190 end
191 end
192
193 === Collection Radio
194
6eb0470 @josevalim Update README
josevalim authored
195 Creates a collection of radio inputs with labels associated (same API as collection_select):
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
196
197 form_for @user do |f|
198 f.collection_radio :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
199 end
200
201 <input id="user_options_true" name="user[options]" type="radio" value="true" />
202 <label class="collection_radio" for="user_options_true">Yes</label>
203 <input id="user_options_false" name="user[options]" type="radio" value="false" />
204 <label class="collection_radio" for="user_options_false">No</label>
205
206 === Collection Check Box
207
6eb0470 @josevalim Update README
josevalim authored
208 Creates a collection of check boxes with labels associated (same API as collection_select):
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
209
210 form_for @user do |f|
211 f.collection_check_box :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
212 end
213
214 <input name="user[options][]" type="hidden" value="" />
215 <input id="user_options_true" name="user[options][]" type="checkbox" value="true" />
216 <label class="collection_check_box" for="user_options_true">Yes</label>
217 <input name="user[options][]" type="hidden" value="" />
218 <input id="user_options_false" name="user[options][]" type="checkbox" value="false" />
219 <label class="collection_check_box" for="user_options_false">No</label>
220
221 == Mappings/Inputs available
222
223 SimpleForm comes with a lot of default mappings:
224
225 Mapping Input Column Type
226
227 boolean check box boolean
228 string text field string
5cb92a2 @josevalim Remove useless API.
josevalim authored
229 email email field string with name matching "email"
230 url url field string with name matching "url"
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
231 password password field string with name matching "password"
232 text text area text
233 file file field string, responding to file methods
234 hidden hidden field -
235 integer text field integer
236 float text field float
237 decimal text field decimal
238 datetime datetime select datetime/timestamp
239 date date select date
240 time time select time
241 select collection select belongs_to/has_many/has_and_belongs_to_many associations
242 radio collection radio belongs_to
243 check_boxes collection check box has_many/has_and_belongs_to_many associations
244 country country select string with name matching "country"
245 time_zone time zone select string with name matching "time_zone"
246
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
247 == I18n
248
249 SimpleForm uses all power of I18n API to lookup labels and hints for you. To customize your forms you can create a locale file like this:
250
251 en:
252 simple_form:
253 labels:
254 user:
255 username: 'User name'
256 password: 'Password'
257 hints:
258 user:
259 username: 'User name to sign in.'
260 password: 'No special characters, please.'
261
262 And your forms will use this information to render labels and hints for you.
263
6eb0470 @josevalim Update README
josevalim authored
264 SimpleForm also lets you be more specific, separating lookups through actions for both hint and label. Let's say you want a different label for new and edit actions, the locale file would be something like:
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
265
266 en:
267 simple_form:
268 labels:
269 user:
f38fe38 @carlosantoniodasilva Adding simple_form_install generator, and fix tabs and typo in README
carlosantoniodasilva authored
270 username: 'User name'
271 password: 'Password'
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
272 edit:
273 username: 'Change user name'
274 password: 'Change password'
275
276 This way SimpleForm will figure out the right translation for you, based on the action being rendered. And to be a little bit DRYer with your locale file, you can skip the model information inside it:
277
278 en:
279 simple_form:
280 labels:
281 username: 'User name'
282 password: 'Password'
283 hints:
284 username: 'User name to sign in.'
285 password: 'No special characters, please.'
286
287 SimpleForm will always look for a default attribute translation if no specific is found inside the model key. In addition, SimpleForm will fallback to default human_attribute_name from Rails when no other translation is found.
288
289 Finally, you can also overwrite labels and hints inside your view, just by passing the label/hint manually. This way the I18n lookup will be skipped.
290
6eb0470 @josevalim Update README
josevalim authored
291 There are other options that can be configured through I18n API, such as required text, boolean and button texts. Be sure to check our locale file or the one copied to your application after you run "script/generate simple_form_install".
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
292
ee6cb1b @josevalim Ready for prime time.
josevalim authored
293 == Configuration
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
294
6eb0470 @josevalim Update README
josevalim authored
295 SimpleForm has several configuration values. You can read and change them in the initializer created by SimpleForm, so if you haven't executed the command below yet, please do:
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
296
6eb0470 @josevalim Update README
josevalim authored
297 ruby script/generate simple_form_install
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
298
a7d0cc2 @carlosantoniodasilva Initial commit.
carlosantoniodasilva authored
299 == TODO
300
301 Please refer to TODO file.
302
ee6cb1b @josevalim Ready for prime time.
josevalim authored
303 == Maintainers
94e3c5d @carlosantoniodasilva Improving README
carlosantoniodasilva authored
304
305 * José Valim (http://github.com/josevalim)
306 * Carlos Antonio da Silva (http://github.com/carlosantoniodasilva)
307
308 == Bugs and Feedback
309
310 If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.
311
312 http://github.com/plataformatec/simple_form/issues
a7d0cc2 @carlosantoniodasilva Initial commit.
carlosantoniodasilva authored
313
ee6cb1b @josevalim Ready for prime time.
josevalim authored
314 MIT License. Copyright 2010 Plataforma Tecnologia. http://blog.plataformatec.com.br
Something went wrong with that request. Please try again.