Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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