Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 523 lines (385 sloc) 21.784 kb
420b4ce Justin French 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 Justin French 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 Justin French trying to fix README formatting of <'s at the start of lines
authored
10 <% semantic_form_for @article do |form| %>
353618e Mark Mansour Extending Formtastic can be done by overriding the semantic_form_builder...
markmansour authored
11
0b370ba Justin French Renamed input_field_set() to just inputs() and added a shorthand version...
authored
12 <% form.inputs :name => "Basic" do %>
353618e Mark Mansour Extending Formtastic can be done by overriding the semantic_form_builder...
markmansour authored
13 <%= form.input :title %>
14 <%= form.input :body %>
1db292f Jeff Smick update README to reflect association attribute changes
sprsquish authored
15 <%= form.input :section %>
16 <%= form.input :publication_state, :as => :radio %>
9997ce6 José Valim Added more information about inputs :for in README.
josevalim authored
17 <%= form.input :category %>
353618e Mark Mansour Extending Formtastic can be done by overriding the semantic_form_builder...
markmansour authored
18 <%= form.input :allow_comments, :label => "Allow commenting on this article" %>
19 <% end %>
20
0b370ba Justin French Renamed input_field_set() to just inputs() and added a shorthand version...
authored
21 <% form.inputs :name => "Advanced" do %>
353618e Mark Mansour Extending Formtastic can be done by overriding the semantic_form_builder...
markmansour authored
22 <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
7e3874a Justin French 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 Mark Mansour Extending Formtastic can be done by overriding the semantic_form_builder...
markmansour authored
25 <%= form.input :url_title, :required => false %>
7e3874a Justin French trying to fix README formatting of <'s at the start of lines
authored
26 <% end %>
27
05ae54d José Valim 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 José Valim Added more information about inputs :for in README.
josevalim authored
31 <% end %>
32
353618e Mark Mansour Extending Formtastic can be done by overriding the semantic_form_builder...
markmansour authored
33 <% form.buttons do %>
34 <%= form.commit_button %>
7e3874a Justin French 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 Justin French 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 Justin French Big update and re-organization of the README:
authored
43 h2. It's better than _SomeOtherFormBuilder_ because...
44
f02b136 Justin French 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 Justin French 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 Justin French fix README typo
authored
51 * it handles real world stuff like inline hints, inline error messages & help text
9af5cc8 Justin French 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 Justin French 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 Justin French 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 Justin French 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 Justin French updating README with gem/plugin installation instructions
authored
80 h2. Installation
81
2bf5b23 Justin French updated README to reflect gemcutter gem source
authored
82 The gem is hosted on gemcutter, so if you haven't already, add it as a gem source:
c89e985 Justin French updating README with gem/plugin installation instructions
authored
83
84 <pre>
2bf5b23 Justin French updated README to reflect gemcutter gem source
authored
85 sudo gem sources -a http://gemcutter.org/
c89e985 Justin French updating README with gem/plugin installation instructions
authored
86 </pre>
87
2bf5b23 Justin French updated README to reflect gemcutter gem source
authored
88 Then install the Formtastic gem:q
c89e985 Justin French updating README with gem/plugin installation instructions
authored
89
90 <pre>
2bf5b23 Justin French updated README to reflect gemcutter gem source
authored
91 sudo gem install formtastic
c89e985 Justin French updating README with gem/plugin installation instructions
authored
92 </pre>
93
2bf5b23 Justin French updated README to reflect gemcutter gem source
authored
94 Optionally, run @./script/generate formtastic@ to copy the following files into your app:
fc29eaa Justin French Combined the "formtastic_config" and "formtastic_stylesheets" generators...
authored
95
96 * config/initializers/formtastic.rb (a commented out Formtastic config initializer)
97 * public/stylesheets/formtastic.css
98 * public/stylesheets/formtastic_changes.css
c89e985 Justin French updating README with gem/plugin installation instructions
authored
99
5c1ce48 Justin French moved the stylesheets stuff up with installation
authored
100 A proof-of-concept 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. If you want to use these stylesheets, add both to your layout:
c89e985 Justin French updating README with gem/plugin installation instructions
authored
101
5c1ce48 Justin French moved the stylesheets stuff up with installation
authored
102 <pre>
103 <%= stylesheet_link_tag "formtastic" %>
104 <%= stylesheet_link_tag "formtastic_changes" %>
105 </pre>
2526d2c Justin French Going back to generators instead of Rake tasks for copying stylesheets a...
authored
106
c89e985 Justin French updating README with gem/plugin installation instructions
authored
107
9af5cc8 Justin French Big update and re-organization of the README:
authored
108 h2. Usage
109
110 Forms are really boring to code... you want to get onto the good stuff as fast as possible.
111
60da134 Justin French small README fix since we changed which fields are rendered by default
authored
112 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 Justin French Big update and re-organization of the README:
authored
113
114 <pre>
115 <% semantic_form_for @user do |form| %>
116 <%= form.inputs %>
117 <%= form.buttons %>
118 <% end %>
119 </pre>
120
121 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@:
122
123 <pre>
124 <% semantic_form_for @user do |form| %>
125 <%= form.inputs :title, :body, :section, :categories, :created_at %>
126 <%= form.buttons :commit %>
127 <% end %>
128 </pre>
129
130 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):
131
132 <pre>
133 <% semantic_form_for @post do |form| %>
134 <% form.inputs do %>
135 <%= form.input :title %>
136 <%= form.input :body %>
137 <%= form.input :section, :as => :radio %>
138 <%= form.input :categories %>
139 <%= form.input :created_at, :as => :string %>
140 <% end %>
141 <% form.buttons do %>
142 <%= form.commit_button %>
143 <% end %>
144 <% end %>
145 </pre>
146
a45853c Justin French small README typo
authored
147 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 Justin French Big update and re-organization of the README:
authored
148
149 <pre>
150 <% semantic_form_for @post do |form| %>
151 <% form.inputs :name => "Basic", :id => "basic" do %>
152 <%= form.input :title %>
153 <%= form.input :body %>
154 <% end %>
155 <% form.inputs :name => "Advanced Options", :id => "advanced" do %>
156 <%= form.input :slug, :label => "URL Title", :hint => "Created automatically if left blank", :required => false %>
157 <%= form.input :section, :as => :radio %>
158 <%= form.input :user, :label => "Author", :label_method => :full_name, %>
159 <%= form.input :categories, :required => false %>
160 <%= form.input :created_at, :as => :string, :label => "Publication Date", :required => false %>
161 <% end %>
162 <% form.buttons do %>
163 <%= form.commit_button %>
164 <% end %>
165 <% end %>
166 </pre>
167
8cbbf04 José Valim Added button_html to customize buttons.
josevalim authored
168
9997ce6 José Valim Added more information about inputs :for in README.
josevalim authored
169 Nested forms (Rails 2.3) are also supported. You can do it in the Rails way:
9af5cc8 Justin French Big update and re-organization of the README:
authored
170
171 <pre>
05ae54d José Valim Fixed nested attributes example in README
josevalim authored
172 <% semantic_form_for @post do |form| %>
173 <%= form.inputs :title, :body, :created_at %>
41a6754 José Valim Another README fix.
josevalim authored
174 <% form.semantic_fields_for :author do |author| %>
05ae54d José Valim Fixed nested attributes example in README
josevalim authored
175 <%= author.inputs :first_name, :last_name, :name => 'Author' %>
41a6754 José Valim Another README fix.
josevalim authored
176 <% end %>
05ae54d José Valim Fixed nested attributes example in README
josevalim authored
177 <%= form.buttons %>
9997ce6 José Valim Added more information about inputs :for in README.
josevalim authored
178 <% end %>
179 </pre>
180
6fd1bd2 Justin French improving the documentation in README
authored
181 Or the Formtastic way with the @:for@ option:
9997ce6 José Valim Added more information about inputs :for in README.
josevalim authored
182
183 <pre>
05ae54d José Valim Fixed nested attributes example in README
josevalim authored
184 <% semantic_form_for @post do |form| %>
185 <%= form.inputs :title, :body, :created_at %>
186 <%= form.inputs :first_name, :last_name, :for => :author, :name => "Author" %>
187 <%= form.buttons %>
9af5cc8 Justin French Big update and re-organization of the README:
authored
188 <% end %>
189 </pre>
190
6fd1bd2 Justin French improving the documentation in README
authored
191 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 José Valim Added nested child nindex support.
josevalim authored
192
193 <pre>
194 <% semantic_form_for @post do |form| %>
195 <%= form.inputs %>
196 <%= form.inputs :name => 'Category #%i', :for => :categories %>
197 <%= form.buttons %>
198 <% end %>
199 </pre>
200
6fd1bd2 Justin French improving the documentation in README
authored
201
202 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:
203
204 <pre>
205 <% semantic_form_for @post do |form| %>
206 <%= form.input :title, :input_html => { :size => 60 } %>
207 <%= form.input :body, :input_html => { :class => 'autogrow' } %>
208 <%= form.input :created_at, :input_html => { :disabled => true } %>
209 <%= form.buttons %>
210 <% end %>
211 </pre>
212
213 The same can be done for buttons with the @:button_html@ option:
214
215 <pre>
216 <% semantic_form_for @post do |form| %>
217 ...
218 <% form.buttons do %>
219 <%= form.commit_button :button_html => { :class => "primary" } %>
220 <% end %>
221 <% end %>
222 </pre>
223
224 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")
225
226 <pre>
227 <% semantic_form_for @post do |form| %>
228 <%= form.input :title, :wrapper_html => { :class => "important" } %>
229 <%= form.input :body %>
230 <%= form.input :description, :wrapper_html => { :style => "display:none;" } %>
231 ...
232 <% end %>
233 </pre>
234
235
9af5cc8 Justin French Big update and re-organization of the README:
authored
236
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
237 h2. The Available Inputs
238
9af5cc8 Justin French Big update and re-organization of the README:
authored
239 * :select (a select menu) - default for ActiveRecord associations (belongs_to, has_many, has_and_belongs_to_many)
be644f7 José Valim Updated documentation.
josevalim authored
240 * :check_boxes (a set of check_box inputs) - alternative to :select has_many and has_and_belongs_to_many associations
9af5cc8 Justin French Big update and re-organization of the README:
authored
241 * :radio (a set of radio inputs) - alternative to :select for ActiveRecord belongs_to associations
07380d4 José Valim Added :time_zone input information to README.
josevalim authored
242 * :time_zone (a select input) - default for :string column types with 'time_zone' in the method name
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
243 * :password (a password input) - default for :string column types with 'password' in the method name
244 * :text (a textarea) - default for :text column types
245 * :date (a date select) - default for :date column types
246 * :datetime (a date and time select) - default for :datetime and :timestamp column types
247 * :time (a time select) - default for :time column types
248 * :boolean (a checkbox) - default for :boolean column types
249 * :string (a text field) - default for :string column types
250 * :numeric (a text field, like string) - default for :integer, :float and :decimal column types
945b76c Jeff Smick Add detection for Paperclip and AttachmentFu attributes.
sprsquish authored
251 * :file (a file field) - default for paperclip or attachment_fu attributes
8239478 Justin French Added :as => :country as a new input option (default for :string columns...
authored
252 * :country (a select menu of country names) - default for :string columns named "country", requires a country_select plugin to be installed
2e9e7c5 José Valim Added :as => :hidden support.
josevalim authored
253 * :hidden (a hidden field) - creates a hidden field (added for compatibility)
8239478 Justin French Added :as => :country as a new input option (default for :string columns...
authored
254
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
255
9af5cc8 Justin French Big update and re-organization of the README:
authored
256 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 Justin French bulking up the documentation and readme with the different inputs availa...
authored
257
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
258 h2. Internationalization (I18n)
259
260 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.
261
262 h3. Label/Hint-localization
263
264 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:
265
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
266 Basic localization (labels only, with ActiveRecord):
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
267
268 <pre>
269 <% semantic_form_for @post do |form| %>
270 <%= form.input :title %> # => :label => I18n.t('activerecord.attributes.user.title') or 'Title'
271 <%= form.input :body %> # => :label => I18n.t('activerecord.attributes.user.body') or 'Body'
272 <%= form.input :section %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
273 <% end %>
274 </pre>
275
276 *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?
277
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
278 Enhanced localization (labels + hints + titles/legends, with Formtastic):
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
279
280 1. Enable I18n lookups by default (@config/initializers/formtastic.rb@):
281
282 <pre>
283 Formtastic::SemanticFormBuilder.i18n_lookups_by_default = true
284 </pre>
285
286 2. Add some cool label-translations/variants (@config/locale/en.yml@):
287
288 <pre>
289 en:
290 formtastic:
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
291 titles:
292 post_details: "Post details"
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
293 labels:
294 post:
295 title: "Choose a title..."
296 body: "Write something..."
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
297 edit:
298 title: "Edit title"
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
299 hints:
300 post:
301 title: "Choose a good title for you post."
302 body: "Write something inspiring here."
303 </pre>
304
305 *Note:* We are using English here still, but you get the point.
306
307 3. ...and now you'll get:
308
309 <pre>
310 <% semantic_form_for @post do |form| %>
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
311 <% inputs do %>
312 <%= form.input :title %> # => :label => "Choose a title...", :hint => "Choose a good title for you post."
313 <%= form.input :body %> # => :label => "Write something...", :hint => "Write something inspiring here."
314 <%= form.input :section %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
315 <% end %>
316 ...
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
317 <% end %>
318 </pre>
319
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
320 4. Localized titles (a.k.a. legends):
321
322 _Note: Slightly different because Formtastic can't guess how you group fields in a form._
323
324 <pre>
325 <% semantic_form_for @post do |form| %>
326 <% inputs :title => :post_details do %> # => :title => "Post details"
327 # ...
328 <% end %>
329 # ...
330 <% end %>
331 </pre>
332
333 5. Override I18n settings:
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
334
335 <pre>
336 <% semantic_form_for @post do |form| %>
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
337 <% inputs do %>
338 <%= form.input :title %> # => :label => "Choose a title...", :hint => "Choose a good title for you post."
339 <%= form.input :body, :hint => false %> # => :label => "Write something..."
340 <%= form.input :section, :label => 'Some section' %> # => :label => 'Some section'
341 <% end %>
342 # ...
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
343 <% end %>
344 </pre>
345
346 If I18n-lookups is disabled, i.e.:
347
348 <pre>
349 Formtastic::SemanticFormBuilder.i18n_lookups_by_default = false
350 </pre>
351
352 ...then you can enable I18n within the forms instead:
353
354 <pre>
355 <% semantic_form_for @post do |form| %>
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
356 <% inputs do %>
357 <%= form.input :title, :label => true %> # => :label => "Choose a title..."
358 <%= form.input :body, :label => true %> # => :label => "Write something..."
359 <%= form.input :section, :label => true %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
360 <% end %>
361 # ...
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
362 <% end %>
363 </pre>
364
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
365 6. Advanced I18n lookups
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
366
367 For more flexible forms; Formtastic find translations using a bottom-up approach taking the following variables in account:
368
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
369 * @MODEL@, e.g. "post"
370 * @ACTION@, e.g. "edit"
371 * @ATTRIBUTE@, e.g. "title"
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
372
373 ...in the following order:
374
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
375 1. @formtastic.{titles,labels,hints}.MODEL.ACTION.ATTRIBUTE@ # By model and action
376 2. @formtastic.{titles,labels,hints}.MODEL.ATTRIBUTE@ # By model
377 3. @formtastic.{titles,labels,hints}.ATTRIBUTE@ # Global default
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
378
379 ...which means that you can define translations like this:
380
381 <pre>
382 en:
383 formtastic:
384 labels:
385 title: "Title" # Default global value
386 article:
387 body: "Article content"
388 post:
389 new:
390 title: "Choose a title..."
391 body: "Write something..."
392 edit:
393 title: "Edit title"
394 body: "Edit body"
395 </pre>
396
75782e1 Jonas Grimfelt Updated I18n-instructions in README; on the I18n-support for fieldset ti...
grimen authored
397 *Note:* For @title@: ATTRIBUTE is a KEY chosen by you, e.g. in step 4 example above: @:post_details@.
398
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
399 h2. ValidationReflection plugin
400
401 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 Justin French bulking up the documentation and readme with the different inputs availa...
authored
402
403 h2. Configuration
404
405 If you wish, put something like this in config/initializers/formtastic_config.rb:
406
407 <pre>
3a32b4a José Valim Updated README with new configuration options.
josevalim authored
408 # Set the default text field size when input is a string. Default is 50
409 Formtastic::SemanticFormBuilder.default_text_field_size = 30
410
2d4a72b Justin French big update to the README
authored
411 # Should all fields be considered "required" by default
412 # Defaults to true, see ValidationReflection notes below
ee26f18 Jeff Smick Remove JustinFrench namespace and add deprecation message for anyone sti...
sprsquish authored
413 Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
2d4a72b Justin French big update to the README
authored
414
415 # Set the string that will be appended to the labels/fieldsets which are required
3a32b4a José Valim Updated README with new configuration options.
josevalim authored
416 # It accepts string or procs and the default is a localized version of
417 # '<abbr title="required">*</abbr>'. In other words, if you configure formtastic.required
418 # in your locale, it will replace the abbr title properly. But if you don't want to use
419 # abbr tag, you can simply give a string as below
ee26f18 Jeff Smick Remove JustinFrench namespace and add deprecation message for anyone sti...
sprsquish authored
420 Formtastic::SemanticFormBuilder.required_string = "(required)"
2d4a72b Justin French big update to the README
authored
421
422 # Set the string that will be appended to the labels/fieldsets which are optional
6a74bc7 José Valim Updated README with inline_order customization.
josevalim authored
423 # Defaults to an empty string ("") and also accepts procs (see required_string above)
ee26f18 Jeff Smick Remove JustinFrench namespace and add deprecation message for anyone sti...
sprsquish authored
424 Formtastic::SemanticFormBuilder.optional_string = "(optional)"
5d072fa Andy Pearson Updating README to include a note about configuring inline errors
andypearson authored
425
2d4a72b Justin French big update to the README
authored
426 # Set the way inline errors will be displayed.
d3d53d0 Justin French typo fix in README
authored
427 # Defaults to :sentence, valid options are :sentence, :list and :none
2d4a72b Justin French big update to the README
authored
428 Formtastic::SemanticFormBuilder.inline_errors = :list
282b28c Jeff Smick Add I18n support
sprsquish authored
429
86e87da José Valim Updated README with @@label_str_methods and new I18n.
josevalim authored
430 # Set the method to call on label text to transform or format it for human-friendly
431 # reading when formtastic is user without object. Defaults to :humanize.
282b28c Jeff Smick Add I18n support
sprsquish authored
432 Formtastic::SemanticFormBuilder.label_str_method = :titleize
30cfc86 Jeff Smick Add Formtastic::SemanticFormBuilder.collection_label_methods to allow fo...
sprsquish authored
433
2d4a72b Justin French big update to the README
authored
434 # Set the array of methods to try calling on parent objects in :select and :radio inputs
435 # for the text inside each @<option>@ tag or alongside each radio @<input>@. The first method
436 # that is found on the object will be used.
437 # Defaults to ["to_label", "display_name", "full_name", "name", "title", "username", "login", "value", "to_s"]
438 Formtastic::SemanticFormBuilder.collection_label_methods = ["title_and_author", "display_name", "login", "to_s"]
6a74bc7 José Valim Updated README with inline_order customization.
josevalim authored
439
440 # Formtastic by default renders inside li tags the input, hints and then
441 # errors messages. Sometimes you want the hints to be rendered first than
442 # the input, in the following order: hints, input and errors. You can
443 # customize it doing just as below:
444 Formtastic::SemanticFormBuilder.inline_order = [:hints, :input, :errors]
8239478 Justin French Added :as => :country as a new input option (default for :string columns...
authored
445
446 # Set the default "priority countries" to suit your user base when using :as => :country
447 Formtastic::SemanticFormBuilder.priority_countries = ["Australia", "New Zealand"]
94ce3ec Jonas Grimfelt Documentation for the new I18n features for labels/hints.
grimen authored
448
449 # Specifies if labels/hints for input fields automatically be looked up using I18n.
450 # Default value: false. Overridden for specific fields by setting value to true,
451 # i.e. :label => true, or :hint => true (or opposite depending on initialized value)
452 # Formtastic::SemanticFormBuilder.i18n_lookups_by_default = false
51bbaf9 Justin French SemanticFormBuilder.semantic_fields_for now uses the builder specified i...
authored
453
454 # If you want to subclass SemanticFormBuilder to add/change the behavior to suit your needs, you
455 # can specify the builder class.
456 # Formtastic::SemanticFormHelper.builder = MyCustomBuilder
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
457 </pre>
458
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
459 h2. Status
dcf8beb Initial Commit
Justin French authored
460
9af5cc8 Justin French Big update and re-organization of the README:
authored
461 *THINGS ARE GOING TO CHANGE A BIT BEFORE WE HIT 1.0.*
dcf8beb Initial Commit
Justin French authored
462
9af5cc8 Justin French Big update and re-organization of the README:
authored
463 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 Justin French big update to the README
authored
464
465 On the plus side, it has a comprehensive spec suite and contributions from at least ten independent developers.
dcf8beb Initial Commit
Justin French authored
466
2d4a72b Justin French big update to the README
authored
467 "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 Justin French link to the wiki for the roadmap to 1.0 in README
authored
468
dcf8beb Initial Commit
Justin French authored
469
9af5cc8 Justin French Big update and re-organization of the README:
authored
470 h2. Dependencies
dcf8beb Initial Commit
Justin French authored
471
9af5cc8 Justin French Big update and re-organization of the README:
authored
472 There are none, but...
dcf8beb Initial Commit
Justin French authored
473
9af5cc8 Justin French Big update and re-organization of the README:
authored
474 * 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 Justin French Added :as => :country as a new input option (default for :string columns...
authored
475 * 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 Justin French Big update and re-organization of the README:
authored
476 * 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
477
0b370ba Justin French Renamed input_field_set() to just inputs() and added a shorthand version...
authored
478
9af5cc8 Justin French Big update and re-organization of the README:
authored
479 h2. Compatibility
0b370ba Justin French Renamed input_field_set() to just inputs() and added a shorthand version...
authored
480
9af5cc8 Justin French Big update and re-organization of the README:
authored
481 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 Justin French Renamed input_field_set() to just inputs() and added a shorthand version...
authored
482
483
67a799f Jonas Grimfelt Made method_required? respect the :if conditional on validates_presence_...
grimen authored
484 h2. Got TextMate?
485
486 Well...there's a TextMate-bundle in town, dedicated to make usage of Formtastic in the TextMate editor even more of a breeze:
487
488 "Formtastic.tmbundle":http://github.com/grimen/formtastic_tmbundle
2d4a72b Justin French big update to the README
authored
489
83b9eb1 Justin French updated the contributors list
authored
490 h2. Contributors
491
2ddd0bb Justin French Welcome Jose as a core maintainer :)
authored
492 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 Justin French updated the README a little with contributors and some other busy work
authored
493
66c49e6 Justin French updated contributors list in README
authored
494 * "Jeff Smick":http://github.com/sprsquish
495 * "Tien Dung":http://github.com/tiendung
496 * "Mark Mansour":http://stateofflux.com
497 * "Andy Pearson":http://github.com/andypearson
498 * "negonicrac":http://github.com/negonicrac
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
499 * "Xavier Shay":http://rhnh.net
15ff964 Justin French Added Pat and negonicrac to contributors.
authored
500 * "Pat Allan":http://github.com/freelancing-god
83b9eb1 Justin French updated the contributors list
authored
501 * "Gareth Townsend":http://github.com/quamen
66c49e6 Justin French updated contributors list in README
authored
502 * "Sascha Hoellger":http://github.com/mitnal
503 * "Andrew Carpenter":http://github.com/andrewcarpenter
83b9eb1 Justin French updated the contributors list
authored
504 * "Jack Dempsey":http://github.com/jackdempsey/
66c49e6 Justin French updated contributors list in README
authored
505 * "Greg Fitzgerald":http://github.com/gregf/
506 * "Hector E. Gomez Morales":http://github.com/hectoregm
507 * "Ben Hamill":http://blog.benhamill.com/
83b9eb1 Justin French updated the contributors list
authored
508 * "Simon Chiu":http://github.com/tolatomeow
66c49e6 Justin French updated contributors list in README
authored
509 * "Bin Dong":http://github.com/dongbin
2d4a72b Justin French big update to the README
authored
510
5af0311 Justin French updated the README to pimp the google group more
authored
511
512 h2. Hey, join the Google group!
513
514 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.
515
516
ba3ce05 Justin French updated the README a little with contributors and some other busy work
authored
517 h2. Project Info
518
dc3ace9 Justin French more on the README
authored
519 Formtastic is hosted on Github: http://github.com/justinfrench/formtastic/, where your contributions, forkings, comments and feedback are greatly welcomed.
ba3ce05 Justin French updated the README a little with contributors and some other busy work
authored
520
521
25d0c7a Justin French fleshed out a 'roadmap to 1.0' in the README
authored
522 Copyright (c) 2007-2008 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.