Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 283 lines (200 sloc) 11.629 kB
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
1 h1. Formtastic Sneaky Preview
dcf8beb Initial Commit
Justin French authored
2
3 Formtastic is a Rails FormBuilder DSL (with some other goodies) to make it far easier to create beautiful, semantically rich, syntactically awesome, readily stylable and wonderfully accessible HTML forms in your Rails applications.
4
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
5 h2. The Story
dcf8beb Initial Commit
Justin French authored
6
2d4a72b @justinfrench big update to the README
authored
7 One day, I finally had enough, so I opened up my text editor, and wrote a DSL for how I'd like to author forms:
dcf8beb Initial Commit
Justin French authored
8
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
9 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
10 <% semantic_form_for @article do |form| %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
11
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
12 <% form.inputs :name => "Basic" do %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
13 <%= form.input :title %>
14 <%= form.input :body %>
1db292f @sprsquish update README to reflect association attribute changes
sprsquish authored
15 <%= form.input :section %>
16 <%= form.input :publication_state, :as => :radio %>
17 <%= form.input :author %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
18 <%= form.input :allow_comments, :label => "Allow commenting on this article" %>
19 <% end %>
20
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
21 <% form.inputs :name => "Advanced" do %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
22 <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
23 <%= form.input :extract, :required => false %>
24 <%= form.input :description, :required => false %>
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
25 <%= form.input :url_title, :required => false %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
26 <% end %>
27
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_buil…
markmansour authored
28 <% form.buttons do %>
29 <%= form.commit_button %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
30 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
31
dcf8beb Initial Commit
Justin French authored
32 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
33 </pre>
34
6734cfd @justinfrench sme typos and cleanups in the readme
authored
35 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
36
37
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
38 h2. It's better than _SomeOtherFormBuilder_ because...
39
40 * it can handle ActiveRecord associations (belongs_to, has_many, has_and_belongs_to_many), rendering the appropriate form input
41 * there's heaps of elements, id and class attributes for you to hook in your CSS and JS
42 * it's _really_ quick to get started with a basic form in place (4 lines), then go back to add it more detail if you need it
43 * it handles real world stuff line inline hints, inline error messages, help text
44 * there's a bunch of people using and working on it (it's not just one developer building half a solution)
45 * it's got absolutely awesome spec coverage
46 * 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)
47
48
15e0bd9 updated the README a little to match last night's slides
Justin French authored
49 h2. Why?
50
51 * web apps = lots of forms
52 * forms are so friggin' boring to code
53 * semantically rich & accessible forms really are possible
54 * the "V" is way behind the "M" and "C" in Rails' MVC – it's the ugly sibling
dcf8beb Initial Commit
Justin French authored
55 * best practices and common patterns have to start somewhere
15e0bd9 updated the README a little to match last night's slides
Justin French authored
56 * i need a challenge
dcf8beb Initial Commit
Justin French authored
57
58
15e0bd9 updated the README a little to match last night's slides
Justin French authored
59 h2. Opinions
60
61 * it should be easier to do things the right way than the wrong way
62 * sometimes _more mark-up_ is better
63 * elements and attribute hooks are _gold_ for stylesheet authors
64 * make the common things we do easy, yet still ensure uncommon things are still possible
65
dcf8beb Initial Commit
Justin French authored
66
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
67 h2. Usage
68
69 Forms are really boring to code... you want to get onto the good stuff as fast as possible.
70
71 This renders a set of inputs (one for _most_ columns in the database table, and one for each ActiveRecord belongs_to, has_many or has_and_belongs_to_many association) and a submit button:
72
73 <pre>
74 <% semantic_form_for @user do |form| %>
75 <%= form.inputs %>
76 <%= form.buttons %>
77 <% end %>
78 </pre>
79
80 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@:
81
82 <pre>
83 <% semantic_form_for @user do |form| %>
84 <%= form.inputs :title, :body, :section, :categories, :created_at %>
85 <%= form.buttons :commit %>
86 <% end %>
87 </pre>
88
89 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):
90
91 <pre>
92 <% semantic_form_for @post do |form| %>
93 <% form.inputs do %>
94 <%= form.input :title %>
95 <%= form.input :body %>
96 <%= form.input :section, :as => :radio %>
97 <%= form.input :categories %>
98 <%= form.input :created_at, :as => :string %>
99 <% end %>
100 <% form.buttons do %>
101 <%= form.commit_button %>
102 <% end %>
103 <% end %>
104 </pre>
105
106 If you want to customize the label text, or render some hint text below the field, specify which fields are required/option, or break the form into two fieldsets, the DSL is pretty comprehensive:
107
108 <pre>
109 <% semantic_form_for @post do |form| %>
110 <% form.inputs :name => "Basic", :id => "basic" do %>
111 <%= form.input :title %>
112 <%= form.input :body %>
113 <% end %>
114 <% form.inputs :name => "Advanced Options", :id => "advanced" do %>
115 <%= form.input :slug, :label => "URL Title", :hint => "Created automatically if left blank", :required => false %>
116 <%= form.input :section, :as => :radio %>
117 <%= form.input :user, :label => "Author", :label_method => :full_name, %>
118 <%= form.input :categories, :required => false %>
119 <%= form.input :created_at, :as => :string, :label => "Publication Date", :required => false %>
120 <% end %>
121 <% form.buttons do %>
122 <%= form.commit_button %>
123 <% end %>
124 <% end %>
125 </pre>
126
127 Nested forms (Rails 2.3) are also supported:
128
129 <pre>
130 <% semantic_form_for @post do |post| %>
131 <%= post.semantic_fields_for :author do |author| %>
132 <%= author.inputs %>
133 <%= end %>
134 <%= post.buttons %>
135 <% end %>
136 </pre>
137
138
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
139 h2. The Available Inputs
140
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
141 * :select (a select menu) - default for ActiveRecord associations (belongs_to, has_many, has_and_belongs_to_many)
142 * :radio (a set of radio inputs) - alternative to :select for ActiveRecord belongs_to associations
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
143 * :password (a password input) - default for :string column types with 'password' in the method name
144 * :text (a textarea) - default for :text column types
145 * :date (a date select) - default for :date column types
146 * :datetime (a date and time select) - default for :datetime and :timestamp column types
147 * :time (a time select) - default for :time column types
148 * :boolean (a checkbox) - default for :boolean column types
2007904 @justinfrench added a new boolean_select input, for boolean fields that work better…
authored
149 * :boolean_select (a yes/no select box)
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
150 * :string (a text field) - default for :string column types
151 * :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
152 * :file (a file field) - default for paperclip or attachment_fu attributes
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
153
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
154 The documentation is pretty good for each of these (what it does, what the output is, what the options are, etc) so go check it out.
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
155
156
157 h2. Configuration
158
159 If you wish, put something like this in config/initializers/formtastic_config.rb:
160
161 <pre>
2d4a72b @justinfrench big update to the README
authored
162 # Should all fields be considered "required" by default
163 # Defaults to true, see ValidationReflection notes below
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone …
sprsquish authored
164 Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
2d4a72b @justinfrench big update to the README
authored
165
166 # Set the string that will be appended to the labels/fieldsets which are required
167 # Default is '<abbr title="required">*</abbr>'
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone …
sprsquish authored
168 Formtastic::SemanticFormBuilder.required_string = "(required)"
2d4a72b @justinfrench big update to the README
authored
169
170 # Set the string that will be appended to the labels/fieldsets which are optional
171 # Defaults to an empty string ("")
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone …
sprsquish authored
172 Formtastic::SemanticFormBuilder.optional_string = "(optional)"
5d072fa @andypearson Updating README to include a note about configuring inline errors
andypearson authored
173
2d4a72b @justinfrench big update to the README
authored
174 # Set the way inline errors will be displayed.
d3d53d0 @justinfrench typo fix in README
authored
175 # Defaults to :sentence, valid options are :sentence, :list and :none
2d4a72b @justinfrench big update to the README
authored
176 Formtastic::SemanticFormBuilder.inline_errors = :list
282b28c @sprsquish Add I18n support
sprsquish authored
177
2d4a72b @justinfrench big update to the README
authored
178 # Set the method to call on label text to transform or format it for human-friendly reading
179 # Defaults to :titleize, but you might want :humanize, :to_s, etc
282b28c @sprsquish Add I18n support
sprsquish authored
180 Formtastic::SemanticFormBuilder.label_str_method = :titleize
30cfc86 @sprsquish Add Formtastic::SemanticFormBuilder.collection_label_methods to allow…
sprsquish authored
181
2d4a72b @justinfrench big update to the README
authored
182 # Set the array of methods to try calling on parent objects in :select and :radio inputs
183 # for the text inside each @<option>@ tag or alongside each radio @<input>@. The first method
184 # that is found on the object will be used.
185 # Defaults to ["to_label", "display_name", "full_name", "name", "title", "username", "login", "value", "to_s"]
186 Formtastic::SemanticFormBuilder.collection_label_methods = ["title_and_author", "display_name", "login", "to_s"]
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
187 </pre>
188
189
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
190 h2. Internationalization (I18n)
191
192 Supports I18n! 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.
193
194 Here is an example locale file:
195
196 <pre>
197 en:
198 formtastic:
199 yes: 'Yes'
200 no: 'No'
201 create: 'Create'
202 save: 'Save'
203 year: 'Year'
204 month: 'Month'
205 day: 'Day'
206 hour: 'Hour'
207 minute: 'Minute'
208 second: 'Second'
209 </pre>
210
211
2d4a72b @justinfrench big update to the README
authored
212 h2. ValidationReflection plugin
213
214 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).
215
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
216
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
217 h2. Status
dcf8beb Initial Commit
Justin French authored
218
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
219 *THINGS ARE GOING TO CHANGE A BIT BEFORE WE HIT 1.0.*
dcf8beb Initial Commit
Justin French authored
220
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
221 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
222
223 On the plus side, it has a comprehensive spec suite and contributions from at least ten independent developers.
dcf8beb Initial Commit
Justin French authored
224
2d4a72b @justinfrench big update to the README
authored
225 "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
226
dcf8beb Initial Commit
Justin French authored
227
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
228 h2. Dependencies
dcf8beb Initial Commit
Justin French authored
229
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
230 There are none, but...
dcf8beb Initial Commit
Justin French authored
231
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
232 * 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)
233 * 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
234
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
235
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
236 h2. Compatibility
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
237
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
238 I'm only testing Formtastic with the latest Rails 2.2.x stable release, and it should be fine under Rails 2.3 as well (including nested forms). Patches are welcome to allow backwards compatibility, but I don't have the energy!
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
239
240
92e5fc3 @justinfrench Updates to the README with better examples and output samples.
authored
241
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
242 h2. What about Stylesheets?
2d4a72b @justinfrench big update to the README
authored
243
fcf66e4 @justinfrench burned the 'extending Formtastic' from README... will write a simpler…
authored
244 A proof-of-concept (very much a work-in-progress) stylesheet is provided which you can include in your layout. Customization is best achieved by overriding these styles in an additional stylesheet so that the Formtastic styles can be updated without clobbering your changes.
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
245
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
246 1. Use the generator to copy the formtastic.css and formtastic_changes.css into your public directory
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
247
248 <pre>
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
249 ./script/generate formtastic_stylesheets
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
250 </pre>
282b28c @sprsquish Add I18n support
sprsquish authored
251
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
252 2. Add both formtastic.css and formtastic_changes.css to your layout:
282b28c @sprsquish Add I18n support
sprsquish authored
253
254 <pre>
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
255 <%= stylesheet_link_tag "formtastic" %>
256 <%= stylesheet_link_tag "formtastic_changes" %>
282b28c @sprsquish Add I18n support
sprsquish authored
257 </pre>
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1…
sprsquish authored
258
2d4a72b @justinfrench big update to the README
authored
259
260 h2. Many thanks to Formtastic's contributors
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
261
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
262 * "Justin French":http://justinfrench.com
263 * "Xavier Shay":http://rhnh.net
0c50ce3 @justinfrench Updated contributors list in the README. Thanks Everyone\!
authored
264 * "Bin Dong":http://github.com/dongbin
dc3ace9 @justinfrench more on the README
authored
265 * "Ben Hamill":http://blog.benhamill.com/
15ff964 @justinfrench Added Pat and negonicrac to contributors.
authored
266 * "Pat Allan":http://github.com/freelancing-god
267 * "negonicrac":http://github.com/negonicrac
0c50ce3 @justinfrench Updated contributors list in the README. Thanks Everyone\!
authored
268 * "Andy Pearson":http://github.com/andypearson
1587c56 @justinfrench Vanity commit for Mark ;)
authored
269 * "Mark Mansour":http://stateofflux.com
0c50ce3 @justinfrench Updated contributors list in the README. Thanks Everyone\!
authored
270 * "Tien Dung":http://github.com/tiendung
c8d721e @justinfrench Updated the contributors list
authored
271 * "Sascha Hoellger":http://github.com/mitnal
272 * "Jeff Smick":http://github.com/sprsquish
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
273
2d4a72b @justinfrench big update to the README
authored
274
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
275 h2. Project Info
276
dc3ace9 @justinfrench more on the README
authored
277 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
278
324a875 @justinfrench link to the google group from the README
authored
279 There's also a newly created "Formtastic Google Group":http://groups.google.com.au/group/formtastic.
280
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
281
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
282 Copyright (c) 2007-2008 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.