Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 239 lines (160 sloc) 9.532 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
6734cfd @justinfrench sme typos and cleanups in the readme
authored
7 Hacked together forms were easy, but awesome forms with decent semantics, rich mark-up and plenty of CSS hooks were incredibly painful. I was discouraged from doing things properly because it was too much mark-up and code to write. 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| %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
11
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
12 <% form.inputs :name => "Basic" do %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
13 <%= form.input :title %>
14 <%= form.input :body %>
15 <%= form.input :section_id %>
16 <%= form.input :publication_state_id, :as => :radio %>
17 <%= form.input :author_id, :as => :select %>
18 <%= form.input :allow_comments, :label => "Allow commenting on this article" %>
19 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
20
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
21 <% form.inputs :name => "Advanced" do %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
22 <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
23 <%= form.input :extract, :required => false %>
24 <%= form.input :description, :required => false %>
25 <%= form.input :url_title, :required => false %>
26 <% end %>
27
28 <% form.button_field_set do %>
29 <%= form.cancel_button %>
30 <%= form.commit_button %>
31 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
32
dcf8beb Initial Commit
Justin French authored
33 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
34 </pre>
35
6734cfd @justinfrench sme typos and cleanups in the readme
authored
36 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
37
38
15e0bd9 updated the README a little to match last night's slides
Justin French authored
39 h2. Why?
40
41 * web apps = lots of forms
42 * forms are so friggin' boring to code
43 * semantically rich & accessible forms really are possible
44 * the "V" is way behind the "M" and "C" in Rails' MVC – it's the ugly sibling
dcf8beb Initial Commit
Justin French authored
45 * best practices and common patterns have to start somewhere
15e0bd9 updated the README a little to match last night's slides
Justin French authored
46 * i need a challenge
dcf8beb Initial Commit
Justin French authored
47
48
15e0bd9 updated the README a little to match last night's slides
Justin French authored
49 h2. Opinions
50
51 * it should be easier to do things the right way than the wrong way
52 * sometimes _more mark-up_ is better
53 * elements and attribute hooks are _gold_ for stylesheet authors
54 * make the common things we do easy, yet still ensure uncommon things are still possible
55
dcf8beb Initial Commit
Justin French authored
56
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
57 h2. The Available Inputs
58
59 * :select (a select menu for belongs_to associations) - default for columns ending in '_id'
60 * :radio (a set of radio inputs for belongs_to associations) - alternative for columns ending in '_id'
61 * :password (a password input) - default for :string column types with 'password' in the method name
62 * :text (a textarea) - default for :text column types
63 * :date (a date select) - default for :date column types
64 * :datetime (a date and time select) - default for :datetime and :timestamp column types
65 * :time (a time select) - default for :time column types
66 * :boolean (a checkbox) - default for :boolean column types
2007904 @justinfrench added a new boolean_select input, for boolean fields that work better…
authored
67 * :boolean_select (a yes/no select box)
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
68 * :string (a text field) - default for :string column types
69 * :numeric (a text field, like string) - default for :integer, :float and :decimal column types
26b1248 @negonicrac add basic file input with specs. This is a very simple addition that …
negonicrac authored
70 * :file (a file field)
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
71
827d9ac @justinfrench typo fix
authored
72 The documentation is pretty good for each of these (what it does, what the output is, etc) so go check it out.
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
73
74
75 h3. One day...
76
77 * calendars and other more humanized date/time selections
78 * flash-based multi-file selection
79 * an interface for tagging and other has_many_through style associations
80
dc3ace9 @justinfrench more on the README
authored
81 In the meantime, there's nothing stopping you from mixing some old fashioned HTML and ERB for custom widgets in with the Formtastic DLS stuff in your views, and I'd love to hear what others are finding a need for.
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
82
83 h3. Fields without database columns
84
85 Formtastic is pretty tightly coupled to ActiveRecord database columns, but it will at least _attempt_ to play nicely with your models other methods (like a virtual column 'full_name' which is split into first_name and last_name in a before save callback), and I'd like this to continue and improve.
86
87
88 h2. Configuration
89
90 If you wish, put something like this in config/initializers/formtastic_config.rb:
91
92 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
93 JustinFrench::Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
94 JustinFrench::Formtastic::SemanticFormBuilder.required_string = "(required)"
95 JustinFrench::Formtastic::SemanticFormBuilder.optional_string = "(optional)"
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
96 </pre>
97
98
99
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
100 h2. Status
dcf8beb Initial Commit
Justin French authored
101
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
102 *THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A BIT.*
dcf8beb Initial Commit
Justin French authored
103
f33efe3 @justinfrench updating the readme a little, especially now that the specs crash for…
authored
104 It's incredibly opinionated, incomplete, a work in progress, messy around the edges, messy in the middle too, tightly coupled to the database, tightly coupled to "my way" of doing things and has an incomplete (but fast-growing) test suite, but I hope you try it and offer some suggestions and improvements any way.
dcf8beb Initial Commit
Justin French authored
105
106
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
107 h2. Roadmap to 1.0
dcf8beb Initial Commit
Justin French authored
108
c7ce9a2 @justinfrench It's now possible to customize the options in :select and :radio belo…
authored
109 * there's a few of TODOs left in the code
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
110 * improve the generated sample stylesheets
111 * take a look at a DSL for the validation errors heading and messages typically placed at the top of a form
252d792 @justinfrench added another TODO for 1.0
authored
112 * maybe get rid of the JustinFrench:: module namespace
dcf8beb Initial Commit
Justin French authored
113
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
114 h2. Usage
dcf8beb Initial Commit
Justin French authored
115
116 The smallest example:
117
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
118 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
119 <% semantic_form_for @user do |form| %>
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
120 <% form.inputs do %>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
121 <%= form.input :name %>
122 <%= form.input :email %>
123 <%= form.input :password %>
124 <%= form.input :department_id, :as => :radio %>
125 <%= form.input :date_of_birth %>
126 <% end %>
dcf8beb Initial Commit
Justin French authored
127 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
128 </pre>
dcf8beb Initial Commit
Justin French authored
129
130 With an output something like:
131
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
132 <pre>
133 <form id="new-article-form" action="#" method="post">
134 <fieldset>
135 <legend><span>Create a new User</span></legend>
136 <fieldset class="inputs">
137 <ol>
138 <li id="user_name_input" class="required string">
139 <label for="user_name">Name <abbr title="required">*</abbr></label>
140 <input type="text" id="user_name" name="user[name]" size="50" />
141 </li>
142 <li id="user_email_input" class="required string">
143 <label for="user_email">Email <abbr title="required">*</abbr></label>
144 <input type="text" id="user_email" name="user[email]" size="50" />
145 </li>
146 </ol>
dcf8beb Initial Commit
Justin French authored
147 </fieldset>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
148 </fieldset>
149 </form>
150 </pre>
0c71a46 mentioned to_label in the README
Justin French authored
151
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
152 If you're happy to accept the default input types and labels, there's a shorthand version too:
153
154 <pre>
155 <% semantic_form_for @user do |form| %>
156 <%= form.inputs :name, :email, :password, :department_id, :date_of_birth %>
157 <% end %>
158 </pre>
159
160 You don't even have to specify the field list (Formtastic will simply render and input for each column in the database table):
161
162 <pre>
163 <% semantic_form_for @user do |form| %>
164 <%= form.inputs %>
165 <% end %>
166 </pre>
167
0c71a46 mentioned to_label in the README
Justin French authored
168
169 h2. Conventions & Prerequisites
170
0b370ba @justinfrench Renamed input_field_set() to just inputs() and added a shorthand vers…
authored
171 In a few places (like radio or select widgets for belongs_to associations) Formtastic expects your ActiveRecord instances to respond to the <code>to_label</code> or <code>to_s</code> method (returning a String). You can easily add this to your models: For example, a User object might want to return the user's first name, last name and login:
0c71a46 mentioned to_label in the README
Justin French authored
172
173 <pre>
174 class User < ActiveRecord::Base
175 #...
176 def to_label
177 "#{first_name} #{last_name} (#{login})"
178 end
179 end
180 </pre>
181
182
b03d5b7 @justinfrench Cleaned up the code and specs around the validation_reflection, inclu…
authored
183 h2. Dependencies
184
49485da @justinfrench updated the dependencies in the README to cover the test suite
authored
185 There are none, but...
186
187 * 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)
188 * rspec, rspec_hpricot_matchers and rcov gems (plus any of their own dependencies) are required for the test suite
b03d5b7 @justinfrench Cleaned up the code and specs around the validation_reflection, inclu…
authored
189
0c71a46 mentioned to_label in the README
Justin French authored
190
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
191 h2. What about Stylesheets?
dcf8beb Initial Commit
Justin French authored
192
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
193 A proof-of-concept (very much a work-in-progress) stylesheet is provided which you can include in your layout. Customisation is best achieved by overriding these styles in an additional stylesheet so that the formtastic styles can be updated without clobbering your changes.
dcf8beb Initial Commit
Justin French authored
194
ef95eff @justinfrench updated README to refelct the generated formtastic_changes.css
authored
195 1. Use the generator to copy the formtastic.css and formtastic_changes.css into your public directory
4f147ea added some stylsheet usage help to the README and to formtastic.css, …
Justin French authored
196
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
197 <pre>
4f147ea added some stylsheet usage help to the README and to formtastic.css, …
Justin French authored
198 ./script/generate formtastic_stylesheets
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
199 </pre>
200
519b640 @justinfrench no need for yahoo's reset.css any more... doing my own resets
authored
201 2. Add both formtastic.css and formtastic_changes.css to your layout:
4f147ea added some stylsheet usage help to the README and to formtastic.css, …
Justin French authored
202
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
203 <pre>
204 <%= stylesheet_link_tag "formtastic" %>
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
205 <%= stylesheet_link_tag "formtastic_changes" %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
206 </pre>
dcf8beb Initial Commit
Justin French authored
207
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
208
209
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
210 h2. Compatibility
dcf8beb Initial Commit
Justin French authored
211
6a3161d @justinfrench updated README to nuke the 2.2.x note
authored
212 I'm only testing Formtastic with the latest Rails 2.2.x stable release.
dcf8beb Initial Commit
Justin French authored
213
214
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
215 h2. But it doesn't do that thing I really need!
dcf8beb Initial Commit
Justin French authored
216
217 Oh noes! It might not ever do it either. We'll see. This is not a silver bullet. I want to make the usual stuff easy, and the unusual stuff possible. That might mean that some of the inputs on your form still have to be hard-coded, but some is better than all, right?
218
219 I really hope the plugin will soon be clean and extensible enough to invite others to contribute more complex input types (calendars, etc) to the core.
220
221
222
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
223 h2. Contributors
224
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
225 * "Justin French":http://justinfrench.com
226 * "Xavier Shay":http://rhnh.net
276b443 @justinfrench The semantic_form_for (and fields_for, etc) helpers can now be calle…
authored
227 * Bin Dong
dc3ace9 @justinfrench more on the README
authored
228 * "Ben Hamill":http://blog.benhamill.com/
15ff964 @justinfrench Added Pat and negonicrac to contributors.
authored
229 * "Pat Allan":http://github.com/freelancing-god
230 * "negonicrac":http://github.com/negonicrac
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
231
232
233 h2. Project Info
234
dc3ace9 @justinfrench more on the README
authored
235 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
236
237
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
238 Copyright (c) 2007-2008 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.