Skip to content
Newer
Older
100644 221 lines (145 sloc) 8.95 KB
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
1 h1. Formtastic Sneaky Preview
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
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 Apr 29, 2008
5 h2. The Story
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
6
6734cfd @justinfrench sme typos and cleanups in the readme
authored Jul 21, 2008
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 Apr 7, 2008
8
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
9 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored Aug 13, 2008
10 <% semantic_form_for @article do |form| %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
11
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored Aug 14, 2008
12 <% form.input_field_set :name => "Basic" do %>
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 Apr 29, 2008
20
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored Aug 14, 2008
21 <% form.input_field_set :name => "Advanced" do %>
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 Apr 29, 2008
32
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
33 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
34 </pre>
35
6734cfd @justinfrench sme typos and cleanups in the readme
authored Jul 20, 2008
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 Apr 7, 2008
37
38
15e0bd9 updated the README a little to match last night's slides
Justin French authored May 30, 2008
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 Apr 7, 2008
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 May 29, 2008
46 * i need a challenge
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
47
48
15e0bd9 updated the README a little to match last night's slides
Justin French authored May 29, 2008
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 Apr 7, 2008
56
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored Jun 28, 2008
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 Jul 6, 2008
67 * :boolean_select (a yes/no select box)
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored Jun 28, 2008
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
70
827d9ac @justinfrench typo fix
authored Nov 2, 2008
71 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 Jun 28, 2008
72
73
74 h3. One day...
75
76 * calendars and other more humanized date/time selections
77 * vanilla html file selection to work well with things like ThoughtBot's "Paperclip":http://www.thoughtbot.com/projects/paperclip
78 * flash-based multi-file selection
79 * an interface for tagging and other has_many_through style associations
80
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.
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 Aug 14, 2008
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 Jun 28, 2008
96 </pre>
97
98
99
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
100 h2. Status
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
101
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
102 *THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A LOT.*
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
103
f33efe3 @justinfrench updating the readme a little, especially now that the specs crash for…
authored Nov 22, 2008
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 Apr 7, 2008
105
106
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
107 h2. Roadmap
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
108
f33efe3 @justinfrench updating the readme a little, especially now that the specs crash for…
authored Nov 23, 2008
109 * there's plenty of TODOs in the code
110 * completing the spec/test suite is a top priority
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored Jun 28, 2008
111 * improve the generic, reusable, stylesheets that prove this stuff works
c336f63 more README tweaks
Justin French authored May 4, 2008
112 * probably do a shortcut like <code><%= form.inputs :name, :login, :email, :bio %></code> for those that want the form with zero configuration
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
113
114
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
115 h2. Usage
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
116
117 The smallest example:
118
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
119 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored Aug 14, 2008
120 <% semantic_form_for @user do |form| %>
121 <% form.input_field_set do %>
122 <%= form.input :name %>
123 <%= form.input :email %>
124 <%= form.input :password %>
125 <%= form.input :department_id, :as => :radio %>
126 <%= form.input :date_of_birth %>
127 <% end %>
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
128 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
129 </pre>
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
130
131 With an output something like:
132
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
133 <pre>
134 <form id="new-article-form" action="#" method="post">
135 <fieldset>
136 <legend><span>Create a new User</span></legend>
137 <fieldset class="inputs">
138 <ol>
139 <li id="user_name_input" class="required string">
140 <label for="user_name">Name <abbr title="required">*</abbr></label>
141 <input type="text" id="user_name" name="user[name]" size="50" />
142 </li>
143 <li id="user_email_input" class="required string">
144 <label for="user_email">Email <abbr title="required">*</abbr></label>
145 <input type="text" id="user_email" name="user[email]" size="50" />
146 </li>
147 </ol>
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
148 </fieldset>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
149 </fieldset>
150 </form>
151 </pre>
0c71a46 mentioned to_label in the README
Justin French authored May 4, 2008
152
153
154 h2. Conventions & Prerequisites
155
156 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> 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:
157
158 <pre>
159 class User < ActiveRecord::Base
160 #...
161 def to_label
162 "#{first_name} #{last_name} (#{login})"
163 end
164 end
165 </pre>
166
167
b03d5b7 @justinfrench Cleaned up the code and specs around the validation_reflection, inclu…
authored Nov 2, 2008
168 h2. Dependencies
169
49485da @justinfrench updated the dependencies in the README to cover the test suite
authored Nov 15, 2008
170 There are none, but...
171
172 * 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)
173 * 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 Nov 2, 2008
174
0c71a46 mentioned to_label in the README
Justin French authored May 4, 2008
175
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
176 h2. What about Stylesheets?
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
177
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored May 4, 2008
178 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 Apr 7, 2008
179
ef95eff @justinfrench updated README to refelct the generated formtastic_changes.css
authored Jul 4, 2008
180 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 Apr 20, 2008
181
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored May 4, 2008
182 <pre>
4f147ea added some stylsheet usage help to the README and to formtastic.css, …
Justin French authored Apr 19, 2008
183 ./script/generate formtastic_stylesheets
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored May 4, 2008
184 </pre>
185
519b640 @justinfrench no need for yahoo's reset.css any more... doing my own resets
authored Jul 4, 2008
186 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 Apr 19, 2008
187
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
188 <pre>
189 <%= stylesheet_link_tag "formtastic" %>
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored May 4, 2008
190 <%= stylesheet_link_tag "formtastic_changes" %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
191 </pre>
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
192
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored May 4, 2008
193
194
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
195 h2. Compatibility
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
196
f33efe3 @justinfrench updating the readme a little, especially now that the specs crash for…
authored Nov 23, 2008
197 I'm only testing Formtastic with the latest Rails 2.1 stable release. Bringing the specs and compatibility up to Rails 2.2 will be a strong focus for the next few weeks.
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
198
199
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored Apr 29, 2008
200 h2. But it doesn't do that thing I really need!
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
201
202 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?
203
204 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.
205
206
207
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored Jun 27, 2008
208 h2. Contributors
209
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored Jun 28, 2008
210 * "Justin French":http://justinfrench.com
211 * "Xavier Shay":http://rhnh.net
276b443 @justinfrench The semantic_form_for (and fields_for, etc) helpers can now be called…
authored Sep 16, 2008
212 * Bin Dong
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored Jun 27, 2008
213
214
215 h2. Project Info
216
217 Formtastic is hosted on Github: http://github.com/justinfrench/formtastic/, where you contributions are greatly welcomed.
218
219
dcf8beb Initial Commit
Justin French authored Apr 7, 2008
220 Copyright (c) 2007 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.