Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 225 lines (150 sloc) 9.536 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
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
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
20
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
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
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
26b1248 @negonicrac add basic file input with specs. This is a very simple addition that …
negonicrac authored
78 * -vanilla html file selection to work well with things like ThoughtBot's "Paperclip":http://www.thoughtbot.com/projects/paperclip-
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
79 * flash-based multi-file selection
80 * an interface for tagging and other has_many_through style associations
81
dc3ace9 @justinfrench more on the README
authored
82 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
83
84 h3. Fields without database columns
85
86 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.
87
88
89 h2. Configuration
90
91 If you wish, put something like this in config/initializers/formtastic_config.rb:
92
93 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
94 JustinFrench::Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
95 JustinFrench::Formtastic::SemanticFormBuilder.required_string = "(required)"
96 JustinFrench::Formtastic::SemanticFormBuilder.optional_string = "(optional)"
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
97 </pre>
98
99
100
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
101 h2. Status
dcf8beb Initial Commit
Justin French authored
102
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
103 *THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A LOT.*
dcf8beb Initial Commit
Justin French authored
104
f33efe3 @justinfrench updating the readme a little, especially now that the specs crash for…
authored
105 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
106
107
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
108 h2. Roadmap to 1.0
dcf8beb Initial Commit
Justin French authored
109
c7ce9a2 @justinfrench It's now possible to customize the options in :select and :radio belo…
authored
110 * there's a few of TODOs left in the code
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
111 * improve the generated sample stylesheets
112 * add a shortcut method like <code><%= form.inputs :name, :login, :email, :bio %></code> for those that want the form with zero configuration
113 * reconsider the naming of button_field_set and input_field_set
114 * take a look at a DSL for the validation errors heading and messages typically placed at the top of a form
d78390d @justinfrench updated TODO list in README (yeah yeah, wiki would be better)
authored
115 * loop through a few methods like to_s and name on ActiveRecord objects (in addition to the existing to_label) so that the belongs_to associations "just work" a little more often, rather than depending on to_label
252d792 @justinfrench added another TODO for 1.0
authored
116 * maybe get rid of the JustinFrench:: module namespace
dcf8beb Initial Commit
Justin French authored
117
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
118 h2. Usage
dcf8beb Initial Commit
Justin French authored
119
120 The smallest example:
121
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
122 <pre>
7e3874a @justinfrench trying to fix README formatting of <'s at the start of lines
authored
123 <% semantic_form_for @user do |form| %>
124 <% form.input_field_set do %>
125 <%= form.input :name %>
126 <%= form.input :email %>
127 <%= form.input :password %>
128 <%= form.input :department_id, :as => :radio %>
129 <%= form.input :date_of_birth %>
130 <% end %>
dcf8beb Initial Commit
Justin French authored
131 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
132 </pre>
dcf8beb Initial Commit
Justin French authored
133
134 With an output something like:
135
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
136 <pre>
137 <form id="new-article-form" action="#" method="post">
138 <fieldset>
139 <legend><span>Create a new User</span></legend>
140 <fieldset class="inputs">
141 <ol>
142 <li id="user_name_input" class="required string">
143 <label for="user_name">Name <abbr title="required">*</abbr></label>
144 <input type="text" id="user_name" name="user[name]" size="50" />
145 </li>
146 <li id="user_email_input" class="required string">
147 <label for="user_email">Email <abbr title="required">*</abbr></label>
148 <input type="text" id="user_email" name="user[email]" size="50" />
149 </li>
150 </ol>
dcf8beb Initial Commit
Justin French authored
151 </fieldset>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
152 </fieldset>
153 </form>
154 </pre>
0c71a46 mentioned to_label in the README
Justin French authored
155
156
157 h2. Conventions & Prerequisites
158
159 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:
160
161 <pre>
162 class User < ActiveRecord::Base
163 #...
164 def to_label
165 "#{first_name} #{last_name} (#{login})"
166 end
167 end
168 </pre>
169
170
b03d5b7 @justinfrench Cleaned up the code and specs around the validation_reflection, inclu…
authored
171 h2. Dependencies
172
49485da @justinfrench updated the dependencies in the README to cover the test suite
authored
173 There are none, but...
174
175 * 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)
176 * 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
177
0c71a46 mentioned to_label in the README
Justin French authored
178
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
179 h2. What about Stylesheets?
dcf8beb Initial Commit
Justin French authored
180
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
181 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
182
ef95eff @justinfrench updated README to refelct the generated formtastic_changes.css
authored
183 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
184
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
185 <pre>
4f147ea added some stylsheet usage help to the README and to formtastic.css, …
Justin French authored
186 ./script/generate formtastic_stylesheets
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
187 </pre>
188
519b640 @justinfrench no need for yahoo's reset.css any more... doing my own resets
authored
189 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
190
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
191 <pre>
192 <%= stylesheet_link_tag "formtastic" %>
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
193 <%= stylesheet_link_tag "formtastic_changes" %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
194 </pre>
dcf8beb Initial Commit
Justin French authored
195
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
196
197
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
198 h2. Compatibility
dcf8beb Initial Commit
Justin French authored
199
6a3161d @justinfrench updated README to nuke the 2.2.x note
authored
200 I'm only testing Formtastic with the latest Rails 2.2.x stable release.
dcf8beb Initial Commit
Justin French authored
201
202
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
203 h2. But it doesn't do that thing I really need!
dcf8beb Initial Commit
Justin French authored
204
205 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?
206
207 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.
208
209
210
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
211 h2. Contributors
212
5a39443 @justinfrench bulking up the documentation and readme with the different inputs ava…
authored
213 * "Justin French":http://justinfrench.com
214 * "Xavier Shay":http://rhnh.net
276b443 @justinfrench The semantic_form_for (and fields_for, etc) helpers can now be calle…
authored
215 * Bin Dong
dc3ace9 @justinfrench more on the README
authored
216 * "Ben Hamill":http://blog.benhamill.com/
ba3ce05 @justinfrench updated the README a little with contributors and some other busy work
authored
217
218
219 h2. Project Info
220
dc3ace9 @justinfrench more on the README
authored
221 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
222
223
25d0c7a @justinfrench fleshed out a 'roadmap to 1.0' in the README
authored
224 Copyright (c) 2007-2008 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.