Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 542 lines (397 sloc) 22.128 kB
420b4ce @justinfrench sick of updating the README with every version bump :)
authored
1 h1. Formtastic
dcf8beb Initial Commit
Justin French authored
2
3 Formtastic is a Rails FormBuilder DSL (with some other goodies) to make it far easier to create beautiful, semantically rich, syntactically awesome, readily stylable and wonderfully accessible HTML forms in your Rails applications.
4
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
5 h2. The Story
dcf8beb Initial Commit
Justin French authored
6
2d4a72b @justinfrench big update to the README
authored
7 One day, I finally had enough, so I opened up my text editor, and wrote a DSL for how I'd like to author forms:
dcf8beb Initial Commit
Justin French authored
8
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
9 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
10 <% semantic_form_for @article do |form| %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
11
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
12 <% form.inputs :name => "Basic" do %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
13 <%= form.input :title %>
14 <%= form.input :body %>
1db292f @sprsquish update README to reflect association attribute changes
sprsquish authored
15 <%= form.input :section %>
16 <%= form.input :publication_state, :as => :radio %>
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
17 <%= form.input :category %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
18 <%= form.input :allow_comments, :label => "Allow commenting on this article" %>
19 <% end %>
20
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
21 <% form.inputs :name => "Advanced" do %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
22 <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
23 <%= form.input :extract, :required => false %>
24 <%= form.input :description, :required => false %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
25 <%= form.input :url_title, :required => false %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
26 <% end %>
27
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
28 <% form.inputs :name => "Author", :for => :author do |author_form| %>
29 <%= author_form.input :first_name %>
30 <%= author_form.input :last_name %>
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
31 <% end %>
32
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
33 <% form.buttons do %>
34 <%= form.commit_button %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
35 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
36
dcf8beb Initial Commit
Justin French authored
37 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
38 </pre>
39
6734cfd @justinfrench sme typos and cleanups in the readme
authored
40 I also wrote the accompanying HTML output I expected, favoring something very similar to the fieldsets, lists and other semantic elements Aaron Gustafson presented in "Learning to Love Forms":http://www.slideshare.net/AaronGustafson/learning-to-love-forms-web-directions-south-07, hacking together enough Ruby to prove it could be done.
dcf8beb Initial Commit
Justin French authored
41
42
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
43 h2. It's better than _SomeOtherFormBuilder_ because...
44
f02b136 @justinfrench rearranged and beefed up the 'it's better than...' README section
authored
45 * it can handle @belongs_to@ associations (like Post belongs_to :author), rendering a select or set of radio inputs with choices from the parent model
46 * it can handle @has_many@ and @has_and_belongs_to_many@ associations (like Post has_many :tags), rendering a multi-select with choices from the child models
47 * it's Rails 2.3-ready (including nested forms)
48 * it has internationalization (I18n)!
49 * it's _really_ quick to get started with a basic form in place (4 lines), then go back to add in more detail if you need it
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
50 * there's heaps of elements, id and class attributes for you to hook in your CSS and JS
f9b8879 @justinfrench fix README typo
authored
51 * it handles real world stuff like inline hints, inline error messages & help text
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
52 * it doesn't hijack or change any of the standard Rails form inputs, so you can still use them as expected (even mix and match)
f02b136 @justinfrench rearranged and beefed up the 'it's better than...' README section
authored
53 * it's got absolutely awesome spec coverage
54 * there's a bunch of people using and working on it (it's not just one developer building half a solution)
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
55
56
15e0bd9 updated the README a little to match last night's slides
Justin French authored
57 h2. Why?
58
59 * web apps = lots of forms
60 * forms are so friggin' boring to code
61 * semantically rich & accessible forms really are possible
62 * the "V" is way behind the "M" and "C" in Rails' MVC – it's the ugly sibling
dcf8beb Initial Commit
Justin French authored
63 * best practices and common patterns have to start somewhere
15e0bd9 updated the README a little to match last night's slides
Justin French authored
64 * i need a challenge
dcf8beb Initial Commit
Justin French authored
65
66
15e0bd9 updated the README a little to match last night's slides
Justin French authored
67 h2. Opinions
68
69 * it should be easier to do things the right way than the wrong way
70 * sometimes _more mark-up_ is better
71 * elements and attribute hooks are _gold_ for stylesheet authors
72 * make the common things we do easy, yet still ensure uncommon things are still possible
73
dcf8beb Initial Commit
Justin French authored
74
3dd6455 @justinfrench Link to RDoc URL in README
authored
75 h2. Documentation
76
77 RDoc documentation _should_ be automatically generated after each commit and made available on the "rdoc.info website":http://rdoc.info/projects/justinfrench/formtastic.
78
79
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
80 h2. Installation
81
2526d2c @justinfrench Going back to generators instead of Rake tasks for copying stylesheet…
authored
82 You can and should get it as a gem:
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
83
84 <pre>
85 gem install justinfrench-formtastic
86 </pre>
87
88 And then add it as a dependency in your environment.rb file:
89
90 <pre>
91 config.gem "justinfrench-formtastic",
92 :lib => 'formtastic',
420b4ce @justinfrench sick of updating the README with every version bump :)
authored
93 :source => 'http://gems.github.com'
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
94 </pre>
95
fc29eaa @justinfrench Combined the "formtastic_config" and "formtastic_stylesheets" generat…
authored
96 If you want, run the generator to copy the following files into your app:
97
98 * config/initializers/formtastic.rb (a commented out Formtastic config initializer)
99 * public/stylesheets/formtastic.css
100 * public/stylesheets/formtastic_changes.css
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
101
102 <pre>
fc29eaa @justinfrench Combined the "formtastic_config" and "formtastic_stylesheets" generat…
authored
103 ./script/generate formtastic
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
104 </pre>
105
2526d2c @justinfrench Going back to generators instead of Rake tasks for copying stylesheet…
authored
106 See also "What about Stylesheets?"
107
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
108
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
109 h2. Usage
110
111 Forms are really boring to code... you want to get onto the good stuff as fast as possible.
112
60da134 @justinfrench small README fix since we changed which fields are rendered by default
authored
113 This renders a set of inputs (one for _most_ columns in the database table, and one for each ActiveRecord belongs_to association), followed by a submit button:
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
114
115 <pre>
116 <% semantic_form_for @user do |form| %>
117 <%= form.inputs %>
118 <%= form.buttons %>
119 <% end %>
120 </pre>
121
122 If you want to specify the order of the fields, skip some of the fields or even add in fields that Formtastic couldn't detect, you can pass in a list of field names to @inputs@ and list of button names to @buttons@:
123
124 <pre>
125 <% semantic_form_for @user do |form| %>
126 <%= form.inputs :title, :body, :section, :categories, :created_at %>
127 <%= form.buttons :commit %>
128 <% end %>
129 </pre>
130
131 If you want control over the input type Formtastic uses for each field, you can expand the @inputs@ and @buttons@ blocks. This specifies the :section input should be a set of radio buttons (rather than the default select box), and that the :created_at field should be a string (rather than the default datetime selects):
132
133 <pre>
134 <% semantic_form_for @post do |form| %>
135 <% form.inputs do %>
136 <%= form.input :title %>
137 <%= form.input :body %>
138 <%= form.input :section, :as => :radio %>
139 <%= form.input :categories %>
140 <%= form.input :created_at, :as => :string %>
141 <% end %>
142 <% form.buttons do %>
143 <%= form.commit_button %>
144 <% end %>
145 <% end %>
146 </pre>
147
a45853c @justinfrench small README typo
authored
148 If you want to customize the label text, or render some hint text below the field, specify which fields are required/optional, or break the form into two fieldsets, the DSL is pretty comprehensive:
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
149
150 <pre>
151 <% semantic_form_for @post do |form| %>
152 <% form.inputs :name => "Basic", :id => "basic" do %>
153 <%= form.input :title %>
154 <%= form.input :body %>
155 <% end %>
156 <% form.inputs :name => "Advanced Options", :id => "advanced" do %>
157 <%= form.input :slug, :label => "URL Title", :hint => "Created automatically if left blank", :required => false %>
158 <%= form.input :section, :as => :radio %>
159 <%= form.input :user, :label => "Author", :label_method => :full_name, %>
160 <%= form.input :categories, :required => false %>
161 <%= form.input :created_at, :as => :string, :label => "Publication Date", :required => false %>
162 <% end %>
163 <% form.buttons do %>
164 <%= form.commit_button %>
165 <% end %>
166 <% end %>
167 </pre>
168
8cbbf04 @josevalim Added button_html to customize buttons.
josevalim authored
169
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
170 Nested forms (Rails 2.3) are also supported. You can do it in the Rails way:
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
171
172 <pre>
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
173 <% semantic_form_for @post do |form| %>
174 <%= form.inputs :title, :body, :created_at %>
41a6754 @josevalim Another README fix.
josevalim authored
175 <% form.semantic_fields_for :author do |author| %>
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
176 <%= author.inputs :first_name, :last_name, :name => 'Author' %>
41a6754 @josevalim Another README fix.
josevalim authored
177 <% end %>
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
178 <%= form.buttons %>
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
179 <% end %>
180 </pre>
181
6fd1bd2 @justinfrench improving the documentation in README
authored
182 Or the Formtastic way with the @:for@ option:
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
183
184 <pre>
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
185 <% semantic_form_for @post do |form| %>
186 <%= form.inputs :title, :body, :created_at %>
187 <%= form.inputs :first_name, :last_name, :for => :author, :name => "Author" %>
188 <%= form.buttons %>
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
189 <% end %>
190 </pre>
191
6fd1bd2 @justinfrench improving the documentation in README
authored
192 When working in has many association, you can even supply "%i" in your fieldset name that it will be properly interpolated with the child index. For example:
d5e3b0a @josevalim Added nested child nindex support.
josevalim authored
193
194 <pre>
195 <% semantic_form_for @post do |form| %>
196 <%= form.inputs %>
197 <%= form.inputs :name => 'Category #%i', :for => :categories %>
198 <%= form.buttons %>
199 <% end %>
200 </pre>
201
6fd1bd2 @justinfrench improving the documentation in README
authored
202
203 Customize HTML attributes for any input using the @:input_html@ option. Typically his is used to disable the input, change the size of a text field, change the rows in a textarea, or even to add a special class to an input to attach special behavior like "autogrow":http://plugins.jquery.com/project/autogrow textareas:
204
205 <pre>
206 <% semantic_form_for @post do |form| %>
207 <%= form.input :title, :input_html => { :size => 60 } %>
208 <%= form.input :body, :input_html => { :class => 'autogrow' } %>
209 <%= form.input :created_at, :input_html => { :disabled => true } %>
210 <%= form.buttons %>
211 <% end %>
212 </pre>
213
214 The same can be done for buttons with the @:button_html@ option:
215
216 <pre>
217 <% semantic_form_for @post do |form| %>
218 ...
219 <% form.buttons do %>
220 <%= form.commit_button :button_html => { :class => "primary" } %>
221 <% end %>
222 <% end %>
223 </pre>
224
225 Customize the HTML attributes for the @<li>@ wrapper around every input with the @:wrapper_html@ option hash. There's one special key in the hash (:class), which will actually _append_ your string of classes to the existing classes provided by Formtastic (like "required string error")
226
227 <pre>
228 <% semantic_form_for @post do |form| %>
229 <%= form.input :title, :wrapper_html => { :class => "important" } %>
230 <%= form.input :body %>
231 <%= form.input :description, :wrapper_html => { :style => "display:none;" } %>
232 ...
233 <% end %>
234 </pre>
235
236
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
237
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
238 h2. The Available Inputs
239
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
240 * :select (a select menu) - default for ActiveRecord associations (belongs_to, has_many, has_and_belongs_to_many)
be644f7 @josevalim Updated documentation.
josevalim authored
241 * :check_boxes (a set of check_box inputs) - alternative to :select has_many and has_and_belongs_to_many associations
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
242 * :radio (a set of radio inputs) - alternative to :select for ActiveRecord belongs_to associations
07380d4 @josevalim Added :time_zone input information to README.
josevalim authored
243 * :time_zone (a select input) - default for :string column types with 'time_zone' in the method name
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
244 * :password (a password input) - default for :string column types with 'password' in the method name
245 * :text (a textarea) - default for :text column types
246 * :date (a date select) - default for :date column types
247 * :datetime (a date and time select) - default for :datetime and :timestamp column types
248 * :time (a time select) - default for :time column types
249 * :boolean (a checkbox) - default for :boolean column types
250 * :string (a text field) - default for :string column types
251 * :numeric (a text field, like string) - default for :integer, :float and :decimal column types
945b76c @sprsquish Add detection for Paperclip and AttachmentFu attributes.
sprsquish authored
252 * :file (a file field) - default for paperclip or attachment_fu attributes
8239478 @justinfrench Added :as => :country as a new input option (default for :string colu…
authored
253 * :country (a select menu of country names) - default for :string columns named "country", requires a country_select plugin to be installed
2e9e7c5 @josevalim Added :as => :hidden support.
josevalim authored
254 * :hidden (a hidden field) - creates a hidden field (added for compatibility)
8239478 @justinfrench Added :as => :country as a new input option (default for :string colu…
authored
255
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
256
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
257 The documentation is pretty good for each of these (what it does, what the output is, what the options are, etc) so go check it out.
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
258
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
259 h2. Internationalization (I18n)
260
261 Formtastic got some neat I18n-features. ActiveRecord object names and attributes are, by default, taken from calling @object.human_name and @object.human_attribute_name(attr) respectively. There are a few words specific to Formtastic that can be translated. See lib/locale/en.yml for more information.
262
263 h3. Label/Hint-localization
264
265 Formtastic supports localized *labels* and *hints* using the I18n API for more advanced usage. Your forms can now be DRYer and more flexible than ever, and still fully localized. This is how:
266
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
267 Basic localization (labels only, with ActiveRecord):
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
268
269 <pre>
270 <% semantic_form_for @post do |form| %>
271 <%= form.input :title %> # => :label => I18n.t('activerecord.attributes.user.title') or 'Title'
272 <%= form.input :body %> # => :label => I18n.t('activerecord.attributes.user.body') or 'Body'
273 <%= form.input :section %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
274 <% end %>
275 </pre>
276
277 *Note:* This is perfectly fine if you just want your labels to be translated using *ActiveRecord I18n attribute translations*, and you don't use input hints. But what if you do? And what if you don't want same labels in all forms?
278
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
279 Enhanced localization (labels + hints + titles/legends, with Formtastic):
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
280
281 1. Enable I18n lookups by default (@config/initializers/formtastic.rb@):
282
283 <pre>
284 Formtastic::SemanticFormBuilder.i18n_lookups_by_default = true
285 </pre>
286
287 2. Add some cool label-translations/variants (@config/locale/en.yml@):
288
289 <pre>
290 en:
291 formtastic:
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
292 titles:
293 post_details: "Post details"
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
294 labels:
295 post:
296 title: "Choose a title..."
297 body: "Write something..."
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
298 edit:
299 title: "Edit title"
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
300 hints:
301 post:
302 title: "Choose a good title for you post."
303 body: "Write something inspiring here."
304 </pre>
305
306 *Note:* We are using English here still, but you get the point.
307
308 3. ...and now you'll get:
309
310 <pre>
311 <% semantic_form_for @post do |form| %>
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
312 <% inputs do %>
313 <%= form.input :title %> # => :label => "Choose a title...", :hint => "Choose a good title for you post."
314 <%= form.input :body %> # => :label => "Write something...", :hint => "Write something inspiring here."
315 <%= form.input :section %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
316 <% end %>
317 ...
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
318 <% end %>
319 </pre>
320
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
321 4. Localized titles (a.k.a. legends):
322
323 _Note: Slightly different because Formtastic can't guess how you group fields in a form._
324
325 <pre>
326 <% semantic_form_for @post do |form| %>
327 <% inputs :title => :post_details do %> # => :title => "Post details"
328 # ...
329 <% end %>
330 # ...
331 <% end %>
332 </pre>
333
334 5. Override I18n settings:
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
335
336 <pre>
337 <% semantic_form_for @post do |form| %>
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
338 <% inputs do %>
339 <%= form.input :title %> # => :label => "Choose a title...", :hint => "Choose a good title for you post."
340 <%= form.input :body, :hint => false %> # => :label => "Write something..."
341 <%= form.input :section, :label => 'Some section' %> # => :label => 'Some section'
342 <% end %>
343 # ...
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
344 <% end %>
345 </pre>
346
347 If I18n-lookups is disabled, i.e.:
348
349 <pre>
350 Formtastic::SemanticFormBuilder.i18n_lookups_by_default = false
351 </pre>
352
353 ...then you can enable I18n within the forms instead:
354
355 <pre>
356 <% semantic_form_for @post do |form| %>
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
357 <% inputs do %>
358 <%= form.input :title, :label => true %> # => :label => "Choose a title..."
359 <%= form.input :body, :label => true %> # => :label => "Write something..."
360 <%= form.input :section, :label => true %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
361 <% end %>
362 # ...
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
363 <% end %>
364 </pre>
365
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
366 6. Advanced I18n lookups
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
367
368 For more flexible forms; Formtastic find translations using a bottom-up approach taking the following variables in account:
369
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
370 * @MODEL@, e.g. "post"
371 * @ACTION@, e.g. "edit"
372 * @ATTRIBUTE@, e.g. "title"
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
373
374 ...in the following order:
375
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
376 1. @formtastic.{titles,labels,hints}.MODEL.ACTION.ATTRIBUTE@ # By model and action
377 2. @formtastic.{titles,labels,hints}.MODEL.ATTRIBUTE@ # By model
378 3. @formtastic.{titles,labels,hints}.ATTRIBUTE@ # Global default
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
379
380 ...which means that you can define translations like this:
381
382 <pre>
383 en:
384 formtastic:
385 labels:
386 title: "Title" # Default global value
387 article:
388 body: "Article content"
389 post:
390 new:
391 title: "Choose a title..."
392 body: "Write something..."
393 edit:
394 title: "Edit title"
395 body: "Edit body"
396 </pre>
397
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
398 *Note:* For @title@: ATTRIBUTE is a KEY chosen by you, e.g. in step 4 example above: @:post_details@.
399
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
400 h2. ValidationReflection plugin
401
402 If you have the "ValidationReflection":http://github.com/redinger/validation_reflection plugin installed, you won't have to specify the :required option (it checks the validations on the model instead).
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
403
404 h2. Configuration
405
406 If you wish, put something like this in config/initializers/formtastic_config.rb:
407
408 <pre>
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
409 # Set the default text field size when input is a string. Default is 50
410 Formtastic::SemanticFormBuilder.default_text_field_size = 30
411
2d4a72b @justinfrench big update to the README
authored
412 # Should all fields be considered "required" by default
413 # Defaults to true, see ValidationReflection notes below
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone …
sprsquish authored
414 Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
2d4a72b @justinfrench big update to the README
authored
415
416 # Set the string that will be appended to the labels/fieldsets which are required
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
417 # It accepts string or procs and the default is a localized version of
418 # '<abbr title="required">*</abbr>'. In other words, if you configure formtastic.required
419 # in your locale, it will replace the abbr title properly. But if you don't want to use
420 # abbr tag, you can simply give a string as below
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone …
sprsquish authored
421 Formtastic::SemanticFormBuilder.required_string = "(required)"
2d4a72b @justinfrench big update to the README
authored
422
423 # Set the string that will be appended to the labels/fieldsets which are optional
6a74bc7 @josevalim Updated README with inline_order customization.
josevalim authored
424 # Defaults to an empty string ("") and also accepts procs (see required_string above)
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone …
sprsquish authored
425 Formtastic::SemanticFormBuilder.optional_string = "(optional)"
5d072fa @andypearson Updating README to include a note about configuring inline errors
andypearson authored
426
2d4a72b @justinfrench big update to the README
authored
427 # Set the way inline errors will be displayed.
d3d53d0 @justinfrench typo fix in README
authored
428 # Defaults to :sentence, valid options are :sentence, :list and :none
2d4a72b @justinfrench big update to the README
authored
429 Formtastic::SemanticFormBuilder.inline_errors = :list
282b28c @sprsquish Add I18n support
sprsquish authored
430
86e87da @josevalim Updated README with @@label_str_methods and new I18n.
josevalim authored
431 # Set the method to call on label text to transform or format it for human-friendly
432 # reading when formtastic is user without object. Defaults to :humanize.
282b28c @sprsquish Add I18n support
sprsquish authored
433 Formtastic::SemanticFormBuilder.label_str_method = :titleize
30cfc86 @sprsquish Add Formtastic::SemanticFormBuilder.collection_label_methods to allow…
sprsquish authored
434
2d4a72b @justinfrench big update to the README
authored
435 # Set the array of methods to try calling on parent objects in :select and :radio inputs
436 # for the text inside each @<option>@ tag or alongside each radio @<input>@. The first method
437 # that is found on the object will be used.
438 # Defaults to ["to_label", "display_name", "full_name", "name", "title", "username", "login", "value", "to_s"]
439 Formtastic::SemanticFormBuilder.collection_label_methods = ["title_and_author", "display_name", "login", "to_s"]
6a74bc7 @josevalim Updated README with inline_order customization.
josevalim authored
440
441 # Formtastic by default renders inside li tags the input, hints and then
442 # errors messages. Sometimes you want the hints to be rendered first than
443 # the input, in the following order: hints, input and errors. You can
444 # customize it doing just as below:
445 Formtastic::SemanticFormBuilder.inline_order = [:hints, :input, :errors]
8239478 @justinfrench Added :as => :country as a new input option (default for :string colu…
authored
446
447 # Set the default "priority countries" to suit your user base when using :as => :country
448 Formtastic::SemanticFormBuilder.priority_countries = ["Australia", "New Zealand"]
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
449
450 # Specifies if labels/hints for input fields automatically be looked up using I18n.
451 # Default value: false. Overridden for specific fields by setting value to true,
452 # i.e. :label => true, or :hint => true (or opposite depending on initialized value)
453 # Formtastic::SemanticFormBuilder.i18n_lookups_by_default = false
51bbaf9 @justinfrench SemanticFormBuilder.semantic_fields_for now uses the builder specifie…
authored
454
455 # If you want to subclass SemanticFormBuilder to add/change the behavior to suit your needs, you
456 # can specify the builder class.
457 # Formtastic::SemanticFormHelper.builder = MyCustomBuilder
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
458 </pre>
459
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
460 h2. Status
dcf8beb Initial Commit
Justin French authored
461
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
462 *THINGS ARE GOING TO CHANGE A BIT BEFORE WE HIT 1.0.*
dcf8beb Initial Commit
Justin French authored
463
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
464 It's a work in progress and a bit rough around the edges still, but I hope you try it and offer some suggestions and improvements anyway.
2d4a72b @justinfrench big update to the README
authored
465
466 On the plus side, it has a comprehensive spec suite and contributions from at least ten independent developers.
dcf8beb Initial Commit
Justin French authored
467
2d4a72b @justinfrench big update to the README
authored
468 "Wishlist":http://wiki.github.com/justinfrench/formtastic/wishlist on the wiki is serving as pretty good documentation for the roadmap to 1.0 and beyond right now, but I'll work on getting a real tracking system or something happening soon.
c5d02e6 @justinfrench link to the wiki for the roadmap to 1.0 in README
authored
469
dcf8beb Initial Commit
Justin French authored
470
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
471 h2. Dependencies
dcf8beb Initial Commit
Justin French authored
472
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
473 There are none, but...
dcf8beb Initial Commit
Justin French authored
474
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
475 * if you have the "ValidationReflection":http://github.com/redinger/validation_reflection plugin is installed, you won't have to specify the :required option (it checks the validations on the model instead)
8239478 @justinfrench Added :as => :country as a new input option (default for :string colu…
authored
476 * if you want to use the :country input, you'll need to install the "iso-3166-country-select plugin":http://github.com/rails/iso-3166-country-select (or any other country_select plugin with the same API)
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
477 * rspec, rspec_hpricot_matchers and rcov gems (plus any of their own dependencies) are required for the test suite
dcf8beb Initial Commit
Justin French authored
478
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
479
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
480 h2. Compatibility
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
481
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
482 I'm only testing Formtastic with the latest Rails 2.2.x stable release, and it should be fine under Rails 2.3 as well (including nested forms). Patches are welcome to allow backwards compatibility, but I don't have the energy!
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
483
484
92e5fc3 @justinfrench Updates to the README with better examples and output samples.
authored
485
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
486 h2. What about Stylesheets?
2d4a72b @justinfrench big update to the README
authored
487
fcf66e4 @justinfrench burned the 'extending Formtastic' from README... will write a simpler…
authored
488 A proof-of-concept (very much a work-in-progress) stylesheet is provided which you can include in your layout. Customization is best achieved by overriding these styles in an additional stylesheet so that the Formtastic styles can be updated without clobbering your changes.
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
489
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
490 1. Use the generator to copy the formtastic.css and formtastic_changes.css into your public directory
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
491
492 <pre>
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
493 ./script/generate formtastic_stylesheets
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
494 </pre>
282b28c @sprsquish Add I18n support
sprsquish authored
495
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
496 2. Add both formtastic.css and formtastic_changes.css to your layout:
282b28c @sprsquish Add I18n support
sprsquish authored
497
498 <pre>
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
499 <%= stylesheet_link_tag "formtastic" %>
500 <%= stylesheet_link_tag "formtastic_changes" %>
282b28c @sprsquish Add I18n support
sprsquish authored
501 </pre>
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
502
67a799f @grimen Made method_required? respect the :if conditional on validates_presen…
grimen authored
503 h2. Got TextMate?
504
505 Well...there's a TextMate-bundle in town, dedicated to make usage of Formtastic in the TextMate editor even more of a breeze:
506
507 "Formtastic.tmbundle":http://github.com/grimen/formtastic_tmbundle
2d4a72b @justinfrench big update to the README
authored
508
83b9eb1 @justinfrench updated the contributors list
authored
509 h2. Contributors
510
2ddd0bb @justinfrench Welcome Jose as a core maintainer :)
authored
511 Formtastic is maintained by "Justin French":http://justinfrench.com and "José Valim":http://github.com/josevalim, but it wouldn't be as awesome as it is today if it weren't for the wonderful contributions of these fine, fine coders.
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
512
66c49e6 @justinfrench updated contributors list in README
authored
513 * "Jeff Smick":http://github.com/sprsquish
514 * "Tien Dung":http://github.com/tiendung
515 * "Mark Mansour":http://stateofflux.com
516 * "Andy Pearson":http://github.com/andypearson
517 * "negonicrac":http://github.com/negonicrac
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
518 * "Xavier Shay":http://rhnh.net
15ff964 @justinfrench Added Pat and negonicrac to contributors.
authored
519 * "Pat Allan":http://github.com/freelancing-god
83b9eb1 @justinfrench updated the contributors list
authored
520 * "Gareth Townsend":http://github.com/quamen
66c49e6 @justinfrench updated contributors list in README
authored
521 * "Sascha Hoellger":http://github.com/mitnal
522 * "Andrew Carpenter":http://github.com/andrewcarpenter
83b9eb1 @justinfrench updated the contributors list
authored
523 * "Jack Dempsey":http://github.com/jackdempsey/
66c49e6 @justinfrench updated contributors list in README
authored
524 * "Greg Fitzgerald":http://github.com/gregf/
525 * "Hector E. Gomez Morales":http://github.com/hectoregm
526 * "Ben Hamill":http://blog.benhamill.com/
83b9eb1 @justinfrench updated the contributors list
authored
527 * "Simon Chiu":http://github.com/tolatomeow
66c49e6 @justinfrench updated contributors list in README
authored
528 * "Bin Dong":http://github.com/dongbin
2d4a72b @justinfrench big update to the README
authored
529
5af0311 @justinfrench updated the README to pimp the google group more
authored
530
531 h2. Hey, join the Google group!
532
533 Please join the "Formtastic Google Group":http://groups.google.com.au/group/formtastic, especially if you'd like to talk about a new feature, or report a bug.
534
535
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
536 h2. Project Info
537
dc3ace9 @justinfrench more on the README
authored
538 Formtastic is hosted on Github: http://github.com/justinfrench/formtastic/, where your contributions, forkings, comments and feedback are greatly welcomed.
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
539
540
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
541 Copyright (c) 2007-2008 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.