Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 213 lines (140 sloc) 8.768 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
1853549 An attempt to make the README a little more succinct (FAIL) and to get r...
Justin French 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 do 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>
10 <% semantic_form_for @article do |form| %>
11
a0e2657 added a :name option to input_fieldset which is passed along to generate...
Justin French authored
12 <% form.input_field_set :name => "Basic" do %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
13 <%= form.input :title %>
73f633d pulling some things out of the example that aren't "done" yet
Justin French authored
14 <%= form.input :body %>
15 <%= form.input :section_id %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
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 %>
20
a0e2657 added a :name option to input_fieldset which is passed along to generate...
Justin French authored
21 <% form.input_field_set :name => "Advanced" do %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
22 <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
73f633d pulling some things out of the example that aren't "done" yet
Justin French authored
23 <%= form.input :extract, :required => false %>
24 <%= form.input :description, :required => false %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
25 <%= form.input :url_title, :required => false %>
26 <% end %>
27
28 <% form.button_field_set do %>
29 <%= form.cancel_button %>
30 <%= form.commit_button %>
dcf8beb Initial Commit
Justin French authored
31 <% end %>
32
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
33 <% end %>
34 </pre>
35
dcf8beb Initial Commit
Justin French 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 <i>Learning to Love Forms</i> <http://www.slideshare.net/AaronGustafson/learning-to-love-forms-web-directions-south-07>, and then hacked together enough Ruby to prove it could be done.
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 Justin French bulking up the documentation and readme with the different inputs availa...
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
67 * :string (a text field) - default for :string column types
68 * :numeric (a text field, like string) - default for :integer, :float and :decimal column types
69
70 The documentation is pretty good for each of these (what it does, what the ouput is, etc) so go check it out.
71
72
73 h3. One day...
74
75 * calendars and other more humanized date/time selections
76 * vanilla html file selection to work well with things like ThoughtBot's "Paperclip":http://www.thoughtbot.com/projects/paperclip
77 * flash-based multi-file selection
78 * an interface for tagging and other has_many_through style associations
79
80 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.
81
82 h3. Fields without database columns
83
84 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.
85
86
87 h2. Configuration
88
89 If you wish, put something like this in config/initializers/formtastic_config.rb:
90
91 <pre>
92 JustinFrench::Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
93 JustinFrench::Formtastic::SemanticFormBuilder.required_string = "(required)"
94 JustinFrench::Formtastic::SemanticFormBuilder.optional_string = "(optional)"
95 </pre>
96
97
98
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
99 h2. Status
dcf8beb Initial Commit
Justin French authored
100
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
101 *THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A LOT.*
dcf8beb Initial Commit
Justin French authored
102
103 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 also incredibly lacking in unit tests so far, but I hope you try it and offer some suggestions and improvements any way.
104
105
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
106 h2. Roadmap
dcf8beb Initial Commit
Justin French authored
107
108 * There's plenty of TODOs in the code
109 * get the basic form_for implementation complete, proven and *well tested* (did I mention how laborious testing form builders is?)
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
110 * improve the generic, reusable, stylesheets that prove this stuff works
c336f63 more README tweaks
Justin French authored
111 * 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
112
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>
119 <% semantic_form_for @user do |form| %>
120 <% form.input_field_set do %>
121 <%= form.input :name %>
122 <%= form.input :email %>
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
123 <%= form.input :password %>
124 <%= form.input :department_id, :as => :radio %>
125 <%= form.input :date_of_birth %>
dcf8beb Initial Commit
Justin French authored
126 <% end %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
127 <% end %>
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
152
153 h2. Conventions & Prerequisites
154
155 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:
156
157 <pre>
158 class User < ActiveRecord::Base
159 #...
160 def to_label
161 "#{first_name} #{last_name} (#{login})"
162 end
163 end
164 </pre>
165
166
167
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
168 h2. What about Stylesheets?
dcf8beb Initial Commit
Justin French authored
169
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
170 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
171
ef95eff Justin French updated README to refelct the generated formtastic_changes.css
authored
172 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, not...
Justin French authored
173
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
174 <pre>
4f147ea added some stylsheet usage help to the README and to formtastic.css, not...
Justin French authored
175 ./script/generate formtastic_stylesheets
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
176 </pre>
177
ef95eff Justin French updated README to refelct the generated formtastic_changes.css
authored
178 2. Add both YUI's reset.css, formtastic.css and formtastic_changes.css to your layout:
4f147ea added some stylsheet usage help to the README and to formtastic.css, not...
Justin French authored
179
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
180 <pre>
181 <%= stylesheet_link_tag "http://yui.yahooapis.com/2.5.1/build/reset/reset-min.css" %>
182 <%= stylesheet_link_tag "formtastic" %>
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
183 <%= stylesheet_link_tag "formtastic_changes" %>
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
184 </pre>
dcf8beb Initial Commit
Justin French authored
185
9525ac2 updated the README a little to walk through stylesheet usage
Justin French authored
186
187
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
188 h2. Compatibility
dcf8beb Initial Commit
Justin French authored
189
1853549 An attempt to make the README a little more succinct (FAIL) and to get r...
Justin French authored
190 I'm only testing Formtastic with the latest Rails stable release.
dcf8beb Initial Commit
Justin French authored
191
192
09d957d textilized the README so that it looks pretty pretty on GitHub
Justin French authored
193 h2. But it doesn't do that thing I really need!
dcf8beb Initial Commit
Justin French authored
194
195 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?
196
197 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.
198
199
200
ba3ce05 Justin French updated the README a little with contributors and some other busy work
authored
201 h2. Contributors
202
5a39443 Justin French bulking up the documentation and readme with the different inputs availa...
authored
203 * "Justin French":http://justinfrench.com
204 * "Xavier Shay":http://rhnh.net
ba3ce05 Justin French updated the README a little with contributors and some other busy work
authored
205
206
207 h2. Project Info
208
209 Formtastic is hosted on Github: http://github.com/justinfrench/formtastic/, where you contributions are greatly welcomed.
210
211
dcf8beb Initial Commit
Justin French authored
212 Copyright (c) 2007 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.