Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 325 lines (232 sloc) 13.322 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_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 %>
17 <%= form.input :author %>
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
353618e @markmansour Extending Formtastic can be done by overriding the semantic_form_builder...
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
f02b136 @justinfrench rearranged and beefed up the 'it's better than...' README section
authored
40 * 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
41 * 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
42 * it's Rails 2.3-ready (including nested forms)
43 * it has internationalization (I18n)!
44 * 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
45 * there's heaps of elements, id and class attributes for you to hook in your CSS and JS
f9b8879 @justinfrench fix README typo
authored
46 * it handles real world stuff like inline hints, inline error messages & help text
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
47 * 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
48 * it's got absolutely awesome spec coverage
49 * 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
50
51
15e0bd9 updated the README a little to match last night's slides
Justin French authored
52 h2. Why?
53
54 * web apps = lots of forms
55 * forms are so friggin' boring to code
56 * semantically rich & accessible forms really are possible
57 * the "V" is way behind the "M" and "C" in Rails' MVC – it's the ugly sibling
dcf8beb Initial Commit
Justin French authored
58 * best practices and common patterns have to start somewhere
15e0bd9 updated the README a little to match last night's slides
Justin French authored
59 * i need a challenge
dcf8beb Initial Commit
Justin French authored
60
61
15e0bd9 updated the README a little to match last night's slides
Justin French authored
62 h2. Opinions
63
64 * it should be easier to do things the right way than the wrong way
65 * sometimes _more mark-up_ is better
66 * elements and attribute hooks are _gold_ for stylesheet authors
67 * make the common things we do easy, yet still ensure uncommon things are still possible
68
dcf8beb Initial Commit
Justin French authored
69
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
70 h2. Installation
71
72 You can (and should) get it as a gem:
73
74 <pre>
75 gem install justinfrench-formtastic
76 </pre>
77
78 And then add it as a dependency in your environment.rb file:
79
80 <pre>
81 config.gem "justinfrench-formtastic",
82 :lib => 'formtastic',
83 :source => 'http://gems.github.com',
063d8ee @justinfrench
authored
84 :version => '0.1.1'
c89e985 @justinfrench updating README with gem/plugin installation instructions
authored
85 </pre>
86
87 If you're a little more old school, install it as a plugin:
88
89 <pre>
90 ./script/install plugin git://github.com/justinfrench/formtastic.git
91 </pre>
92
93
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
94 h2. Usage
95
96 Forms are really boring to code... you want to get onto the good stuff as fast as possible.
97
98 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:
99
100 <pre>
101 <% semantic_form_for @user do |form| %>
102 <%= form.inputs %>
103 <%= form.buttons %>
104 <% end %>
105 </pre>
106
107 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@:
108
109 <pre>
110 <% semantic_form_for @user do |form| %>
111 <%= form.inputs :title, :body, :section, :categories, :created_at %>
112 <%= form.buttons :commit %>
113 <% end %>
114 </pre>
115
116 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):
117
118 <pre>
119 <% semantic_form_for @post do |form| %>
120 <% form.inputs do %>
121 <%= form.input :title %>
122 <%= form.input :body %>
123 <%= form.input :section, :as => :radio %>
124 <%= form.input :categories %>
125 <%= form.input :created_at, :as => :string %>
126 <% end %>
127 <% form.buttons do %>
128 <%= form.commit_button %>
129 <% end %>
130 <% end %>
131 </pre>
132
133 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:
134
135 <pre>
136 <% semantic_form_for @post do |form| %>
137 <% form.inputs :name => "Basic", :id => "basic" do %>
138 <%= form.input :title %>
139 <%= form.input :body %>
140 <% end %>
141 <% form.inputs :name => "Advanced Options", :id => "advanced" do %>
142 <%= form.input :slug, :label => "URL Title", :hint => "Created automatically if left blank", :required => false %>
143 <%= form.input :section, :as => :radio %>
144 <%= form.input :user, :label => "Author", :label_method => :full_name, %>
145 <%= form.input :categories, :required => false %>
146 <%= form.input :created_at, :as => :string, :label => "Publication Date", :required => false %>
147 <% end %>
148 <% form.buttons do %>
149 <%= form.commit_button %>
150 <% end %>
151 <% end %>
152 </pre>
153
154 Nested forms (Rails 2.3) are also supported:
155
156 <pre>
157 <% semantic_form_for @post do |post| %>
158 <%= post.semantic_fields_for :author do |author| %>
159 <%= author.inputs %>
160 <%= end %>
161 <%= post.buttons %>
162 <% end %>
163 </pre>
164
165
5a39443 @justinfrench bulking up the documentation and readme with the different inputs availa...
authored
166 h2. The Available Inputs
167
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
168 * :select (a select menu) - default for ActiveRecord associations (belongs_to, has_many, has_and_belongs_to_many)
169 * :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 availa...
authored
170 * :password (a password input) - default for :string column types with 'password' in the method name
171 * :text (a textarea) - default for :text column types
172 * :date (a date select) - default for :date column types
173 * :datetime (a date and time select) - default for :datetime and :timestamp column types
174 * :time (a time select) - default for :time column types
175 * :boolean (a checkbox) - default for :boolean column types
2007904 @justinfrench added a new boolean_select input, for boolean fields that work better wi...
authored
176 * :boolean_select (a yes/no select box)
5a39443 @justinfrench bulking up the documentation and readme with the different inputs availa...
authored
177 * :string (a text field) - default for :string column types
178 * :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
179 * :file (a file field) - default for paperclip or attachment_fu attributes
5a39443 @justinfrench bulking up the documentation and readme with the different inputs availa...
authored
180
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
181 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
182
183
184 h2. Configuration
185
186 If you wish, put something like this in config/initializers/formtastic_config.rb:
187
188 <pre>
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
189 # Set the default text field size when input is a string. Default is 50
190 Formtastic::SemanticFormBuilder.default_text_field_size = 30
191
2d4a72b @justinfrench big update to the README
authored
192 # Should all fields be considered "required" by default
193 # Defaults to true, see ValidationReflection notes below
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone sti...
sprsquish authored
194 Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
2d4a72b @justinfrench big update to the README
authored
195
196 # Set the string that will be appended to the labels/fieldsets which are required
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
197 # It accepts string or procs and the default is a localized version of
198 # '<abbr title="required">*</abbr>'. In other words, if you configure formtastic.required
199 # in your locale, it will replace the abbr title properly. But if you don't want to use
200 # abbr tag, you can simply give a string as below
ee26f18 @sprsquish Remove JustinFrench namespace and add deprecation message for anyone sti...
sprsquish authored
201 Formtastic::SemanticFormBuilder.required_string = "(required)"
2d4a72b @justinfrench big update to the README
authored
202
203 # Set the string that will be appended to the labels/fieldsets which are optional
6a74bc7 @josevalim Updated README with inline_order customization.
josevalim authored
204 # 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
205 Formtastic::SemanticFormBuilder.optional_string = "(optional)"
5d072fa @andypearson Updating README to include a note about configuring inline errors
andypearson authored
206
2d4a72b @justinfrench big update to the README
authored
207 # Set the way inline errors will be displayed.
d3d53d0 @justinfrench typo fix in README
authored
208 # Defaults to :sentence, valid options are :sentence, :list and :none
2d4a72b @justinfrench big update to the README
authored
209 Formtastic::SemanticFormBuilder.inline_errors = :list
282b28c @sprsquish Add I18n support
sprsquish authored
210
2d4a72b @justinfrench big update to the README
authored
211 # Set the method to call on label text to transform or format it for human-friendly reading
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
212 # Defaults to :to_s, because we are already using human_attribute_name when creating labels,
213 # but you might want to change for :titleize or another string method
282b28c @sprsquish Add I18n support
sprsquish authored
214 Formtastic::SemanticFormBuilder.label_str_method = :titleize
30cfc86 @sprsquish Add Formtastic::SemanticFormBuilder.collection_label_methods to allow fo...
sprsquish authored
215
2d4a72b @justinfrench big update to the README
authored
216 # Set the array of methods to try calling on parent objects in :select and :radio inputs
217 # for the text inside each @<option>@ tag or alongside each radio @<input>@. The first method
218 # that is found on the object will be used.
219 # Defaults to ["to_label", "display_name", "full_name", "name", "title", "username", "login", "value", "to_s"]
220 Formtastic::SemanticFormBuilder.collection_label_methods = ["title_and_author", "display_name", "login", "to_s"]
6a74bc7 @josevalim Updated README with inline_order customization.
josevalim authored
221
222 # Formtastic by default renders inside li tags the input, hints and then
223 # errors messages. Sometimes you want the hints to be rendered first than
224 # the input, in the following order: hints, input and errors. You can
225 # customize it doing just as below:
226 Formtastic::SemanticFormBuilder.inline_order = [:hints, :input, :errors]
5a39443 @justinfrench bulking up the documentation and readme with the different inputs availa...
authored
227 </pre>
228
229
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
230 h2. Internationalization (I18n)
231
232 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.
233
234 Here is an example locale file:
235
236 <pre>
237 en:
238 formtastic:
239 yes: 'Yes'
240 no: 'No'
241 create: 'Create'
242 save: 'Save'
243 year: 'Year'
244 month: 'Month'
245 day: 'Day'
246 hour: 'Hour'
247 minute: 'Minute'
248 second: 'Second'
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
249 required: 'required'
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
250 </pre>
251
252
2d4a72b @justinfrench big update to the README
authored
253 h2. ValidationReflection plugin
254
255 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).
256
5a39443 @justinfrench bulking up the documentation and readme with the different inputs availa...
authored
257
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
258 h2. Status
dcf8beb Initial Commit
Justin French authored
259
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
260 *THINGS ARE GOING TO CHANGE A BIT BEFORE WE HIT 1.0.*
dcf8beb Initial Commit
Justin French authored
261
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
262 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
263
264 On the plus side, it has a comprehensive spec suite and contributions from at least ten independent developers.
dcf8beb Initial Commit
Justin French authored
265
2d4a72b @justinfrench big update to the README
authored
266 "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
267
dcf8beb Initial Commit
Justin French authored
268
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
269 h2. Dependencies
dcf8beb Initial Commit
Justin French authored
270
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
271 There are none, but...
dcf8beb Initial Commit
Justin French authored
272
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
273 * 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)
274 * 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
275
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand version...
authored
276
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
277 h2. Compatibility
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand version...
authored
278
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
279 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
280
281
92e5fc3 @justinfrench Updates to the README with better examples and output samples.
authored
282
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
283 h2. What about Stylesheets?
2d4a72b @justinfrench big update to the README
authored
284
fcf66e4 @justinfrench burned the 'extending Formtastic' from README... will write a simpler an...
authored
285 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
286
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
287 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
288
289 <pre>
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
290 ./script/generate formtastic_stylesheets
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1/wh...
sprsquish authored
291 </pre>
282b28c @sprsquish Add I18n support
sprsquish authored
292
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
293 2. Add both formtastic.css and formtastic_changes.css to your layout:
282b28c @sprsquish Add I18n support
sprsquish authored
294
295 <pre>
9af5cc8 @justinfrench Big update and re-organization of the README:
authored
296 <%= stylesheet_link_tag "formtastic" %>
297 <%= stylesheet_link_tag "formtastic_changes" %>
282b28c @sprsquish Add I18n support
sprsquish authored
298 </pre>
085e22f @sprsquish Add support for nested forms (http://ryandaigle.com/articles/2009/2/1/wh...
sprsquish authored
299
2d4a72b @justinfrench big update to the README
authored
300
301 h2. Many thanks to Formtastic's contributors
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
302
5a39443 @justinfrench bulking up the documentation and readme with the different inputs availa...
authored
303 * "Justin French":http://justinfrench.com
304 * "Xavier Shay":http://rhnh.net
0c50ce3 @justinfrench Updated contributors list in the README. Thanks Everyone\!
authored
305 * "Bin Dong":http://github.com/dongbin
dc3ace9 @justinfrench more on the README
authored
306 * "Ben Hamill":http://blog.benhamill.com/
15ff964 @justinfrench Added Pat and negonicrac to contributors.
authored
307 * "Pat Allan":http://github.com/freelancing-god
308 * "negonicrac":http://github.com/negonicrac
0c50ce3 @justinfrench Updated contributors list in the README. Thanks Everyone\!
authored
309 * "Andy Pearson":http://github.com/andypearson
1587c56 @justinfrench Vanity commit for Mark ;)
authored
310 * "Mark Mansour":http://stateofflux.com
0c50ce3 @justinfrench Updated contributors list in the README. Thanks Everyone\!
authored
311 * "Tien Dung":http://github.com/tiendung
c8d721e @justinfrench Updated the contributors list
authored
312 * "Sascha Hoellger":http://github.com/mitnal
313 * "Jeff Smick":http://github.com/sprsquish
3a32b4a @josevalim Updated README with new configuration options.
josevalim authored
314 * "José Valim":http://github.com/josevalim
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
315
2d4a72b @justinfrench big update to the README
authored
316
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
317 h2. Project Info
318
dc3ace9 @justinfrench more on the README
authored
319 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
320
324a875 @justinfrench link to the google group from the README
authored
321 There's also a newly created "Formtastic Google Group":http://groups.google.com.au/group/formtastic.
322
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
323
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
324 Copyright (c) 2007-2008 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.