Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 548 lines (393 sloc) 22.688 kB
420b4ce @justinfrench sick of updating the README with every version bump :)
justinfrench 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
justinfrench 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
justinfrench 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…
justinfrench 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…
justinfrench 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
justinfrench 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
justinfrench 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
justinfrench 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
justinfrench 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:
justinfrench authored
43 h2. It's better than _SomeOtherFormBuilder_ because...
44
6688887 @grimen More README-polishing.
grimen 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).
f02b136 @justinfrench rearranged and beefed up the 'it's better than...' README section
justinfrench authored
48 * it has internationalization (I18n)!
6688887 @grimen More README-polishing.
grimen authored
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.
50 * there's heaps of elements, id and class attributes for you to hook in your CSS and JS.
51 * it handles real world stuff like inline hints, inline error messages & help text.
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).
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:
justinfrench authored
55
56
15e0bd9 updated the README a little to match last night's slides
Justin French authored
57 h2. Why?
58
6688887 @grimen More README-polishing.
grimen authored
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.
63 * best practices and common patterns have to start somewhere.
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
6688887 @grimen More README-polishing.
grimen authored
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.
15e0bd9 updated the README a little to match last night's slides
Justin French authored
73
dcf8beb Initial Commit
Justin French authored
74
3dd6455 @justinfrench Link to RDoc URL in README
justinfrench 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
justinfrench authored
80 h2. Installation
81
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
82 The gem is hosted on gemcutter, so *if you haven't already*, add it as a gem source:
c89e985 @justinfrench updating README with gem/plugin installation instructions
justinfrench authored
83
84 <pre>
2bf5b23 @justinfrench updated README to reflect gemcutter gem source
justinfrench authored
85 sudo gem sources -a http://gemcutter.org/
c89e985 @justinfrench updating README with gem/plugin installation instructions
justinfrench authored
86 </pre>
87
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
88 Then install the Formtastic gem:
c89e985 @justinfrench updating README with gem/plugin installation instructions
justinfrench authored
89
90 <pre>
2bf5b23 @justinfrench updated README to reflect gemcutter gem source
justinfrench authored
91 sudo gem install formtastic
c89e985 @justinfrench updating README with gem/plugin installation instructions
justinfrench authored
92 </pre>
93
2bf5b23 @justinfrench updated README to reflect gemcutter gem source
justinfrench authored
94 Optionally, run @./script/generate formtastic@ to copy the following files into your app:
fc29eaa @justinfrench Combined the "formtastic_config" and "formtastic_stylesheets" generat…
justinfrench authored
95
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
96 * @config/initializers/formtastic.rb@ - a commented out Formtastic config initializer
97 * @public/stylesheets/formtastic.css@
98 * @public/stylesheets/formtastic_changes.css@
c89e985 @justinfrench updating README with gem/plugin installation instructions
justinfrench authored
99
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen 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 @justinfrench updating README with gem/plugin installation instructions
justinfrench authored
101
5c1ce48 @justinfrench moved the stylesheets stuff up with installation
justinfrench authored
102 <pre>
103 <%= stylesheet_link_tag "formtastic" %>
104 <%= stylesheet_link_tag "formtastic_changes" %>
105 </pre>
2526d2c @justinfrench Going back to generators instead of Rake tasks for copying stylesheet…
justinfrench authored
106
9af5cc8 @justinfrench Big update and re-organization of the README:
justinfrench authored
107 h2. Usage
108
109 Forms are really boring to code... you want to get onto the good stuff as fast as possible.
110
6688887 @grimen More README-polishing.
grimen authored
111 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:
justinfrench authored
112
113 <pre>
114 <% semantic_form_for @user do |form| %>
115 <%= form.inputs %>
116 <%= form.buttons %>
117 <% end %>
118 </pre>
119
120 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@:
121
122 <pre>
123 <% semantic_form_for @user do |form| %>
124 <%= form.inputs :title, :body, :section, :categories, :created_at %>
125 <%= form.buttons :commit %>
126 <% end %>
127 </pre>
128
6688887 @grimen More README-polishing.
grimen authored
129 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):
9af5cc8 @justinfrench Big update and re-organization of the README:
justinfrench authored
130
131 <pre>
132 <% semantic_form_for @post do |form| %>
133 <% form.inputs do %>
134 <%= form.input :title %>
135 <%= form.input :body %>
136 <%= form.input :section, :as => :radio %>
137 <%= form.input :categories %>
138 <%= form.input :created_at, :as => :string %>
139 <% end %>
140 <% form.buttons do %>
141 <%= form.commit_button %>
142 <% end %>
143 <% end %>
144 </pre>
145
a45853c @justinfrench small README typo
justinfrench authored
146 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:
justinfrench authored
147
148 <pre>
149 <% semantic_form_for @post do |form| %>
17f6668 @justinfrench Revert "This reverts commit 440bd2d8da117acdbca57fa199c115caefcd87c0."
justinfrench authored
150 <% form.inputs "Basic", :id => "basic" do %>
9af5cc8 @justinfrench Big update and re-organization of the README:
justinfrench authored
151 <%= form.input :title %>
152 <%= form.input :body %>
153 <% end %>
154 <% form.inputs :name => "Advanced Options", :id => "advanced" do %>
155 <%= form.input :slug, :label => "URL Title", :hint => "Created automatically if left blank", :required => false %>
156 <%= form.input :section, :as => :radio %>
157 <%= form.input :user, :label => "Author", :label_method => :full_name, %>
158 <%= form.input :categories, :required => false %>
159 <%= form.input :created_at, :as => :string, :label => "Publication Date", :required => false %>
160 <% end %>
161 <% form.buttons do %>
162 <%= form.commit_button %>
163 <% end %>
164 <% end %>
165 </pre>
166
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
167 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:
justinfrench authored
168
169 <pre>
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
170 <% semantic_form_for @post do |form| %>
171 <%= form.inputs :title, :body, :created_at %>
41a6754 @josevalim Another README fix.
josevalim authored
172 <% form.semantic_fields_for :author do |author| %>
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
173 <%= author.inputs :first_name, :last_name, :name => "Author" %>
41a6754 @josevalim Another README fix.
josevalim authored
174 <% end %>
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
175 <%= form.buttons %>
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
176 <% end %>
177 </pre>
178
6fd1bd2 @justinfrench improving the documentation in README
justinfrench authored
179 Or the Formtastic way with the @:for@ option:
9997ce6 @josevalim Added more information about inputs :for in README.
josevalim authored
180
181 <pre>
05ae54d @josevalim Fixed nested attributes example in README
josevalim authored
182 <% semantic_form_for @post do |form| %>
183 <%= form.inputs :title, :body, :created_at %>
184 <%= form.inputs :first_name, :last_name, :for => :author, :name => "Author" %>
185 <%= form.buttons %>
9af5cc8 @justinfrench Big update and re-organization of the README:
justinfrench authored
186 <% end %>
187 </pre>
188
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
189 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
190
191 <pre>
192 <% semantic_form_for @post do |form| %>
193 <%= form.inputs %>
194 <%= form.inputs :name => 'Category #%i', :for => :categories %>
195 <%= form.buttons %>
196 <% end %>
197 </pre>
198
6fd1bd2 @justinfrench improving the documentation in README
justinfrench authored
199
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
200 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:
6fd1bd2 @justinfrench improving the documentation in README
justinfrench authored
201
202 <pre>
203 <% semantic_form_for @post do |form| %>
204 <%= form.input :title, :input_html => { :size => 60 } %>
205 <%= form.input :body, :input_html => { :class => 'autogrow' } %>
206 <%= form.input :created_at, :input_html => { :disabled => true } %>
207 <%= form.buttons %>
208 <% end %>
209 </pre>
210
211 The same can be done for buttons with the @:button_html@ option:
212
213 <pre>
214 <% semantic_form_for @post do |form| %>
215 ...
216 <% form.buttons do %>
217 <%= form.commit_button :button_html => { :class => "primary" } %>
218 <% end %>
219 <% end %>
220 </pre>
221
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
222 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"@)
223
6fd1bd2 @justinfrench improving the documentation in README
justinfrench authored
224 <pre>
225 <% semantic_form_for @post do |form| %>
226 <%= form.input :title, :wrapper_html => { :class => "important" } %>
227 <%= form.input :body %>
228 <%= form.input :description, :wrapper_html => { :style => "display:none;" } %>
229 ...
230 <% end %>
231 </pre>
232
233
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
justinfrench authored
234 h2. The Available Inputs
235
d9a06fe @grimen README: Last set of polishing moves for now.
grimen authored
236 The Formtastic input types:
237
8577c18 @grimen More README-readability polishing.
grimen authored
238 * @:select@ - a select menu. Default for ActiveRecord associations: @belongs_to@, @has_many@, and @has_and_belongs_to_many@.
239 * @:check_boxes@ - a set of check_box inputs. Alternative to @:select@ for ActiveRecord-associations: @has_many@, and @has_and_belongs_to_many@.
240 * @:radio@ - a set of radio inputs. Alternative to @:select@ for ActiveRecord-associations: @belongs_to@.
241 * @:time_zone@ - a select input. Default for column types: @:string@ with name matching @"time_zone"@.
242 * @:password@ - a password input. Default for column types: @:string@ with name matching @"password"@.
243 * @:text@ - a textarea. Default for column types: @:text@.
244 * @:date@ - a date select. Default for column types: @:date@.
245 * @:datetime@ - a date and time select. Default for column types: @:datetime@ and @:timestamp@.
246 * @:time@ - a time select. Default for column types: @:time@.
247 * @:boolean@ - a checkbox. Default for column types: @:boolean@.
248 * @:string@ - a text field. Default for column types: @:string@.
249 * @:numeric@ - a text field (just like string). Default for column types: @:integer@, @:float@, and @:decimal@.
250 * @:file@ - a file field. Default for file-attachment attributes matching: "paperclip":http://github.com/thoughtbot/paperclip or "attachment_fu":http://github.com/technoweenie/attachment_fu.
251 * @:country@ - a select menu of country names. Default for column types: :string with name @"country"@ - requires a *country_select* plugin to be installed.
6688887 @grimen More README-polishing.
grimen authored
252 * @:hidden@ - a hidden field. Creates a hidden field (added for compatibility).
253
254 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…
justinfrench authored
255
06ff25d @lardawge Added section clarifying label lookup order.
lardawge authored
256 h2. Delegation for label lookups
257
258 Formtastic decides which label to use in the following order:
259
260 <pre>
261 1. :label # :label => "Choose Title"
262 2. Formtastic i18n # if either :label => true || i18n_lookups_by_default = true (see Internationalization)
263 3. Activerecord i18n # if localization file found for the given attribute
264 4. label_str_method # if nothing provided this defaults to :humanize but can be set to a custom method
265 </pre>
266
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
267 h2. Internationalization (I18n)
268
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
269 h3. Basic Localization
71ef99f @justinfrench nuked the configuration copy/paste from the README, linked to the gen…
justinfrench authored
270
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
271 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.
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
272
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
273 Basic localization (labels only, with ActiveRecord):
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
274
275 <pre>
276 <% semantic_form_for @post do |form| %>
277 <%= form.input :title %> # => :label => I18n.t('activerecord.attributes.user.title') or 'Title'
278 <%= form.input :body %> # => :label => I18n.t('activerecord.attributes.user.body') or 'Body'
279 <%= form.input :section %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
280 <% end %>
281 </pre>
282
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
283 *Note:* This is perfectly fine if you just want your labels/attributes and/or models to be translated using *ActiveRecord I18n attribute translations*, and you don't use input hints and legends. But what if you do? And what if you don't want same labels in all forms?
284
285 h3. Enhanced Localization (Formtastic I18n API)
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
286
d9a06fe @grimen README: Last set of polishing moves for now.
grimen authored
287 Formtastic supports localized *labels*, *hints*, *legends*, *actions* 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:
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
288
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
289 *1. Enable I18n lookups by default (@config/initializers/formtastic.rb@):*
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
290
291 <pre>
292 Formtastic::SemanticFormBuilder.i18n_lookups_by_default = true
293 </pre>
294
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
295 *2. Add some cool label-translations/variants (@config/locale/en.yml@):*
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
296
297 <pre>
298 en:
299 formtastic:
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
300 titles:
301 post_details: "Post details"
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
302 labels:
303 post:
304 title: "Choose a title..."
305 body: "Write something..."
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
306 edit:
307 title: "Edit title"
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
308 hints:
309 post:
310 title: "Choose a good title for you post."
311 body: "Write something inspiring here."
4aca8cd @grimen New I18n-features:
grimen authored
312 actions:
313 create: "Create my {{model}}"
314 update: "Save changes"
315 dummie: "Launch!"
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
316 </pre>
317
318 *Note:* We are using English here still, but you get the point.
319
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
320 *3. ...and now you'll get:*
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
321
322 <pre>
4aca8cd @grimen New I18n-features:
grimen authored
323 <% semantic_form_for Post.new do |form| %>
a8e2f2e @justinfrench fix README examples missing form.x prefix for buttons and inputs
justinfrench authored
324 <% form.inputs do %>
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
325 <%= form.input :title %> # => :label => "Choose a title...", :hint => "Choose a good title for you post."
326 <%= form.input :body %> # => :label => "Write something...", :hint => "Write something inspiring here."
327 <%= form.input :section %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
328 <% end %>
a8e2f2e @justinfrench fix README examples missing form.x prefix for buttons and inputs
justinfrench authored
329 <% form.buttons do %>
4aca8cd @grimen New I18n-features:
grimen authored
330 <%= form.commit_button %> # => "Create my {{model}}"
331 <% end %>
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
332 <% end %>
333 </pre>
334
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
335 *4. Localized titles (a.k.a. legends):*
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
336
17f6668 @justinfrench Revert "This reverts commit 440bd2d8da117acdbca57fa199c115caefcd87c0."
justinfrench authored
337 _Note: Slightly different because Formtastic can't guess how you group fields in a form. Legend text can be set with first (as in the sample below) specified value, or :name/:title options - depending on what flavor is preferred._
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
338
339 <pre>
340 <% semantic_form_for @post do |form| %>
17f6668 @justinfrench Revert "This reverts commit 440bd2d8da117acdbca57fa199c115caefcd87c0."
justinfrench authored
341 <% form.inputs :post_details do %> # => :title => "Post details"
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
342 # ...
343 <% end %>
344 # ...
345 <% end %>
346 </pre>
347
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
348 *5. Override I18n settings:*
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
349
350 <pre>
351 <% semantic_form_for @post do |form| %>
a8e2f2e @justinfrench fix README examples missing form.x prefix for buttons and inputs
justinfrench authored
352 <% form.inputs do %>
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
353 <%= form.input :title %> # => :label => "Choose a title...", :hint => "Choose a good title for you post."
354 <%= form.input :body, :hint => false %> # => :label => "Write something..."
355 <%= form.input :section, :label => 'Some section' %> # => :label => 'Some section'
356 <% end %>
a8e2f2e @justinfrench fix README examples missing form.x prefix for buttons and inputs
justinfrench authored
357 <% form.buttons do %>
4aca8cd @grimen New I18n-features:
grimen authored
358 <%= form.commit_button :dummie %> # => "Launch!"
359 <% end %>
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
360 <% end %>
361 </pre>
362
363 If I18n-lookups is disabled, i.e.:
364
365 <pre>
366 Formtastic::SemanticFormBuilder.i18n_lookups_by_default = false
367 </pre>
368
369 ...then you can enable I18n within the forms instead:
370
371 <pre>
372 <% semantic_form_for @post do |form| %>
a8e2f2e @justinfrench fix README examples missing form.x prefix for buttons and inputs
justinfrench authored
373 <% form.inputs do %>
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
374 <%= form.input :title, :label => true %> # => :label => "Choose a title..."
375 <%= form.input :body, :label => true %> # => :label => "Write something..."
376 <%= form.input :section, :label => true %> # => :label => I18n.t('activerecord.attributes.user.section') or 'Section'
377 <% end %>
a8e2f2e @justinfrench fix README examples missing form.x prefix for buttons and inputs
justinfrench authored
378 <% form.buttons do %>
4aca8cd @grimen New I18n-features:
grimen authored
379 <%= form.commit_button true %> # => "Save changes" (if we are in edit that is...)
380 <% end %>
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
381 <% end %>
382 </pre>
383
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
384 *6. Advanced I18n lookups*
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
385
386 For more flexible forms; Formtastic find translations using a bottom-up approach taking the following variables in account:
387
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
388 * @MODEL@, e.g. "post"
389 * @ACTION@, e.g. "edit"
4aca8cd @grimen New I18n-features:
grimen authored
390 * @KEY/ATTRIBUTE@, e.g. "title", :my_custom_key, ...
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
391
392 ...in the following order:
393
6688887 @grimen More README-polishing.
grimen authored
394 1. @formtastic.{titles,labels,hints,actions}.MODEL.ACTION.ATTRIBUTE@ - by model and action
395 2. @formtastic.{titles,labels,hints,actions}.MODEL.ATTRIBUTE@ - by model
396 3. @formtastic.{titles,labels,hints,actions}.ATTRIBUTE@ - global default
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
397
398 ...which means that you can define translations like this:
399
400 <pre>
401 en:
402 formtastic:
403 labels:
404 title: "Title" # Default global value
405 article:
406 body: "Article content"
407 post:
408 new:
409 title: "Choose a title..."
410 body: "Write something..."
411 edit:
412 title: "Edit title"
413 body: "Edit body"
414 </pre>
415
4aca8cd @grimen New I18n-features:
grimen authored
416 Values for @labels@/@hints@/@actions@ are can take values: @String@ (explicit value), @Symbol@ (i18n-lookup-key relative to the current "type", e.g. actions:), @true@ (force I18n lookup), @false@ (force no I18n lookup). Titles (legends) can only take: @String@ and @Symbol@ - true/false have no meaning.
75782e1 @grimen Updated I18n-instructions in README; on the I18n-support for fieldset…
grimen authored
417
71ef99f @justinfrench nuked the configuration copy/paste from the README, linked to the gen…
justinfrench authored
418
c4ebcef * added semantic_errors method with specs
Wojciech Wnętrzak authored
419 h2. Semantic errors
420
421 You can show errors on base (by default) and any other attribute just passing it name to semantic_errors method:
422
423 <pre>
424 <% semantic_form_for @post do |form| %>
425 <%= form.semantic_errors :state %>
426 <% end %>
427 </pre>
428
429
94ce3ec @grimen Documentation for the new I18n features for labels/hints.
grimen authored
430 h2. ValidationReflection plugin
431
49a18a5 @grimen README-update: I18n instructions are better structured, and easier to…
grimen authored
432 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…
justinfrench authored
433
434
71ef99f @justinfrench nuked the configuration copy/paste from the README, linked to the gen…
justinfrench authored
435 h2. Configuration
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
justinfrench authored
436
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
437 Run @./script/generate formtastic@ to copy a commented out config file into @config/initializers/formtastic.rb@. You can "view the configuration file on GitHub":http://github.com/justinfrench/formtastic/blob/master/generators/formtastic/templates/formtastic.rb
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
438
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
justinfrench authored
439
fef3288 @grimen Added documentation for the form generator in README, and showing som…
grimen authored
440 h2. Form Generator
441
442 There's a Formtastic form code generator to make your transition to Formtastic easier. All you have to do is to *specify an existing model name*, and optionally specify view template framework (ERB/HAML), and you are good to go. *Note:* This won't overwrite any of you stuff. This is how you use it:
443
444 *Alt. 1: Generate in terminal:*
445
446 <pre>
447 $ ./script/generate form Post
448 # ---------------------------------------------------------
449 # GENERATED FORMTASTIC CODE
450 # ---------------------------------------------------------
451
e57b9d1 @grimen Form generator: |f| is a better default for |form|. Also works better…
grimen authored
452 <% f.inputs do %>
453 <%= f.input :title, :label => 'Title' %>
454 <%= f.input :body, :label => 'Body' %>
455 <%= f.input :published, :label => 'Published' %>
fef3288 @grimen Added documentation for the form generator in README, and showing som…
grimen authored
456 <% end %>
457
458 # ---------------------------------------------------------
459 Copied to clipboard - just paste it!
460 </pre>
461
462 *Alt. 2: Generate partial:*
463
464 <pre>
465 $ ./script/generate form Post --partial
466 exists app/views/posts
467 create app/views/posts/_form.html.erb
468 </pre>
469
3f58f3a @justinfrench README update for --controller option form generator
justinfrench authored
470 To generate *HAML* markup, just add the @--haml@ as argument:
471
472 <pre>
473 $ ./script/generate form Post --haml
474 exists app/views/admin/posts
475 create app/views/admin/posts/_form.html.haml
476 </pre>
477
478 To specify the controller in a namespace (eg admin/posts instead of posts), use the --controller argument:
479
480 <pre>
481 $ ./script/generate form Post --partial --controller admin/posts
482 exists app/views/admin/posts
483 create app/views/admin/posts/_form.html.erb
484 </pre>
485
fef3288 @grimen Added documentation for the form generator in README, and showing som…
grimen authored
486
ce7da5e @justinfrench added the builder config to the config template and quick documentati…
justinfrench authored
487 h2. Custom Inputs
488
489 If you want to add your own input types to encapsulate your own logic or interface patterns, you can do so by subclassing SemanticFormBuilder and configuring Formtastic to use your custom builder class.
490
491 @Formtastic::SemanticFormHelper.builder = MyCustomBuilder@
492
493
3f58f3a @justinfrench README update for --controller option form generator
justinfrench authored
494
495
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
496 h2. Status
dcf8beb Initial Commit
Justin French authored
497
6688887 @grimen More README-polishing.
grimen authored
498 Formtastic has been in active development for about a year. We've just recently jumped to an 0.9 version number, signaling that we consider this a 1.0 release candidate, and that the API won't change significantly for the 1.x series.
c5d02e6 @justinfrench link to the wiki for the roadmap to 1.0 in README
justinfrench authored
499
dcf8beb Initial Commit
Justin French authored
500
9af5cc8 @justinfrench Big update and re-organization of the README:
justinfrench authored
501 h2. Dependencies
dcf8beb Initial Commit
Justin French authored
502
9af5cc8 @justinfrench Big update and re-organization of the README:
justinfrench authored
503 There are none, but...
dcf8beb Initial Commit
Justin French authored
504
e9f27cf @grimen The most tiny README-update ever. =)
grimen authored
505 * 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).
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
506 * 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).
507 * "rspec":http://github.com/dchelimsky/rspec/, "rspec_hpricot_matchers":http://rubyforge.org/projects/rspec-hpricot/ and "rcov":http://github.com/relevance/rcov gems (plus any of their own dependencies) are required for the test suite.
dcf8beb Initial Commit
Justin French authored
508
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
justinfrench authored
509
9af5cc8 @justinfrench Big update and re-organization of the README:
justinfrench authored
510 h2. Compatibility
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
justinfrench authored
511
d7fff76 @justinfrench updated compatability guidelines
justinfrench authored
512 I'm only testing Formtastic with the latest Rails 2.4.x stable release, and it should be fine under Rails 2.3.x 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…
justinfrench authored
513
67a799f @grimen Made method_required? respect the :if conditional on validates_presen…
grimen authored
514 h2. Got TextMate?
515
6688887 @grimen More README-polishing.
grimen authored
516 Well...there's a TextMate-bundle in town, dedicated to make usage of Formtastic in the "TextMate":http://macromates.com/ editor even more of a breeze:
67a799f @grimen Made method_required? respect the :if conditional on validates_presen…
grimen authored
517
518 "Formtastic.tmbundle":http://github.com/grimen/formtastic_tmbundle
2d4a72b @justinfrench big update to the README
justinfrench authored
519
61d0056 @justinfrench * updated the status to reflect that this is a release candidate
justinfrench authored
520
2079c59 @justinfrench added a section about contributing to README
justinfrench authored
521 h2. How to contribute
522
523 *Before you send a pull request*, please ensure that you provide appropriate spec/test coverage and ensure the documentation is up-to-date. Bonus points if you perform your changes in a clean topic branch rather than master.
524
525 Please also keep your commits *atomic* so that they are more likely to apply cleanly. That means that each commit should contain the smallest possible logical change. Don't commit two features at once, don't update the gemspec at the same time you add a feature, don't fix a whole bunch of whitespace in a file at the same time you change a few lines, etc, etc.
526
527 For significant changes, you may wish to discuss your idea on the Formtastic Google group before coding to ensure that your change is likely to be accepted. Formtastic relies heavily on i18n, so if you're unsure of the impact this has on your changes, please discuss them with the group.
528
529
259a98c @justinfrench updated heading in README
justinfrench authored
530 h2. Maintainers & Contributors
83b9eb1 @justinfrench updated the contributors list
justinfrench authored
531
4ac2f58 @justinfrench we now have over 40 contributors
justinfrench authored
532 Formtastic is maintained by "Justin French":http://justinfrench.com, "José Valim":http://github.com/josevalim and "Jonas Grimfelt":http://github.com/grimen, but it wouldn't be as awesome as it is today without help from over 40 contributors.
619ce6c @justinfrench added Grimen to the README, updated contributors list, etc
justinfrench authored
533
534 @git shortlog -n -s --no-merges@
2d4a72b @justinfrench big update to the README
justinfrench authored
535
5af0311 @justinfrench updated the README to pimp the google group more
justinfrench authored
536
7a84a73 @justinfrench README heading tweak
justinfrench authored
537 h2. Google Group
5af0311 @justinfrench updated the README to pimp the google group more
justinfrench authored
538
539 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.
540
541
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
justinfrench authored
542 h2. Project Info
543
1fcc068 @grimen An effort to make the README somewhat more readable.
grimen authored
544 Formtastic is hosted on Github: "http://github.com/justinfrench/formtastic":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
justinfrench authored
545
546
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
justinfrench authored
547 Copyright (c) 2007-2008 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.