Skip to content
This repository
Newer
Older
100644 173 lines (116 sloc) 6.848 kb
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
1 h1. Formtastic Sneaky Preview
dcf8bebb » Justin French
2008-04-07 Initial Commit
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
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
5 h2. The Story
dcf8bebb » Justin French
2008-04-07 Initial Commit
6
18535490 » Justin French
2008-04-14 An attempt to make the README a little more succinct (FAIL) and to ge…
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:
dcf8bebb » Justin French
2008-04-07 Initial Commit
8
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
9 <pre>
10 <% semantic_form_for @article do |form| %>
11
a0e26578 » Justin French
2008-05-21 added a :name option to input_fieldset which is passed along to gener…
12 <% form.input_field_set :name => "Basic" do %>
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
13 <%= form.input :title %>
73f633db » Justin French
2008-05-30 pulling some things out of the example that aren't "done" yet
14 <%= form.input :body %>
15 <%= form.input :section_id %>
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
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
a0e26578 » Justin French
2008-05-21 added a :name option to input_fieldset which is passed along to gener…
21 <% form.input_field_set :name => "Advanced" do %>
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
22 <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
73f633db » Justin French
2008-05-30 pulling some things out of the example that aren't "done" yet
23 <%= form.input :extract, :required => false %>
24 <%= form.input :description, :required => false %>
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
25 <%= form.input :url_title, :required => false %>
26 <% end %>
27
28 <% form.button_field_set do %>
29 <%= form.cancel_button %>
30 <%= form.commit_button %>
dcf8bebb » Justin French
2008-04-07 Initial Commit
31 <% end %>
32
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
33 <% end %>
34 </pre>
35
dcf8bebb » Justin French
2008-04-07 Initial Commit
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
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
39 h2. Configuration
dcf8bebb » Justin French
2008-04-07 Initial Commit
40
41 If you wish, put something like this in config/initializers/formtastic_config.rb:
42
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
43 <pre>
44 JustinFrench::Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
45 JustinFrench::Formtastic::SemanticFormBuilder.required_string = "(required)"
46 JustinFrench::Formtastic::SemanticFormBuilder.optional_string = "(optional)"
47 </pre>
dcf8bebb » Justin French
2008-04-07 Initial Commit
48
15e0bd98 » Justin French
2008-05-30 updated the README a little to match last night's slides
49
50 h2. Why?
51
52 * web apps = lots of forms
53 * forms are so friggin' boring to code
54 * semantically rich & accessible forms really are possible
55 * the "V" is way behind the "M" and "C" in Rails' MVC – it's the ugly sibling
dcf8bebb » Justin French
2008-04-07 Initial Commit
56 * best practices and common patterns have to start somewhere
15e0bd98 » Justin French
2008-05-30 updated the README a little to match last night's slides
57 * i need a challenge
dcf8bebb » Justin French
2008-04-07 Initial Commit
58
59
15e0bd98 » Justin French
2008-05-30 updated the README a little to match last night's slides
60 h2. Opinions
61
62 * it should be easier to do things the right way than the wrong way
63 * sometimes _more mark-up_ is better
64 * elements and attribute hooks are _gold_ for stylesheet authors
65 * make the common things we do easy, yet still ensure uncommon things are still possible
66
dcf8bebb » Justin French
2008-04-07 Initial Commit
67
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
68 h2. Status
dcf8bebb » Justin French
2008-04-07 Initial Commit
69
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
70 *THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A LOT.*
dcf8bebb » Justin French
2008-04-07 Initial Commit
71
72 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.
73
74 * Justin's Weblog: http://justinfrench.com
18535490 » Justin French
2008-04-14 An attempt to make the README a little more succinct (FAIL) and to ge…
75 * Github: http://github.com/justinfrench/formtastic/
dcf8bebb » Justin French
2008-04-07 Initial Commit
76
77
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
78 h2. Roadmap
dcf8bebb » Justin French
2008-04-07 Initial Commit
79
80 * There's plenty of TODOs in the code
81 * get the basic form_for implementation complete, proven and *well tested* (did I mention how laborious testing form builders is?)
82 * provide generic, reusable, stylesheets that prove this stuff works
83 * go back and ensure it works for remote_form_for, etc
c336f63b » Justin French
2008-05-04 more README tweaks
84 * probably do a shortcut like <code><%= form.inputs :name, :login, :email, :bio %></code> for those that want the form with zero configuration
dcf8bebb » Justin French
2008-04-07 Initial Commit
85
86
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
87 h2. Usage
dcf8bebb » Justin French
2008-04-07 Initial Commit
88
89 The smallest example:
90
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
91 <pre>
92 <% semantic_form_for @user do |form| %>
93 <% form.input_field_set do %>
94 <%= form.input :name %>
95 <%= form.input :email %>
dcf8bebb » Justin French
2008-04-07 Initial Commit
96 <% end %>
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
97 <% end %>
98 </pre>
dcf8bebb » Justin French
2008-04-07 Initial Commit
99
100 With an output something like:
101
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
102 <pre>
103 <form id="new-article-form" action="#" method="post">
104 <fieldset>
105 <legend><span>Create a new User</span></legend>
106 <fieldset class="inputs">
107 <ol>
108 <li id="user_name_input" class="required string">
109 <label for="user_name">Name <abbr title="required">*</abbr></label>
110 <input type="text" id="user_name" name="user[name]" size="50" />
111 </li>
112 <li id="user_email_input" class="required string">
113 <label for="user_email">Email <abbr title="required">*</abbr></label>
114 <input type="text" id="user_email" name="user[email]" size="50" />
115 </li>
116 </ol>
dcf8bebb » Justin French
2008-04-07 Initial Commit
117 </fieldset>
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
118 </fieldset>
119 </form>
120 </pre>
0c71a468 » Justin French
2008-05-04 mentioned to_label in the README
121
122
123 h2. Conventions & Prerequisites
124
125 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:
126
127 <pre>
128 class User < ActiveRecord::Base
129 #...
130 def to_label
131 "#{first_name} #{last_name} (#{login})"
132 end
133 end
134 </pre>
135
136
137
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
138 h2. What about Stylesheets?
dcf8bebb » Justin French
2008-04-07 Initial Commit
139
9525ac2c » Justin French
2008-05-04 updated the README a little to walk through stylesheet usage
140 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.
dcf8bebb » Justin French
2008-04-07 Initial Commit
141
9525ac2c » Justin French
2008-05-04 updated the README a little to walk through stylesheet usage
142 1. Use the generator to copy the formtastic.css into your public directory
4f147ea7 » Justin French
2008-04-20 added some stylsheet usage help to the README and to formtastic.css, …
143
9525ac2c » Justin French
2008-05-04 updated the README a little to walk through stylesheet usage
144 <pre>
4f147ea7 » Justin French
2008-04-20 added some stylsheet usage help to the README and to formtastic.css, …
145 ./script/generate formtastic_stylesheets
9525ac2c » Justin French
2008-05-04 updated the README a little to walk through stylesheet usage
146 </pre>
147
148 2. Create an empty file public/stylesheets/formtastic_changes.css for your custom styles
4f147ea7 » Justin French
2008-04-20 added some stylsheet usage help to the README and to formtastic.css, …
149
9525ac2c » Justin French
2008-05-04 updated the README a little to walk through stylesheet usage
150 3. Add both YUI's reset.css, formtastic.css and formtastic_changes.css to your layout:
4f147ea7 » Justin French
2008-04-20 added some stylsheet usage help to the README and to formtastic.css, …
151
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
152 <pre>
153 <%= stylesheet_link_tag "http://yui.yahooapis.com/2.5.1/build/reset/reset-min.css" %>
154 <%= stylesheet_link_tag "formtastic" %>
9525ac2c » Justin French
2008-05-04 updated the README a little to walk through stylesheet usage
155 <%= stylesheet_link_tag "formtastic_changes" %>
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
156 </pre>
dcf8bebb » Justin French
2008-04-07 Initial Commit
157
9525ac2c » Justin French
2008-05-04 updated the README a little to walk through stylesheet usage
158
159
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
160 h2. Compatibility
dcf8bebb » Justin French
2008-04-07 Initial Commit
161
18535490 » Justin French
2008-04-14 An attempt to make the README a little more succinct (FAIL) and to ge…
162 I'm only testing Formtastic with the latest Rails stable release.
dcf8bebb » Justin French
2008-04-07 Initial Commit
163
164
09d957d0 » Justin French
2008-04-29 textilized the README so that it looks pretty pretty on GitHub
165 h2. But it doesn't do that thing I really need!
dcf8bebb » Justin French
2008-04-07 Initial Commit
166
167 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?
168
169 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.
170
171
172
173 Copyright (c) 2007 Justin French, released under the MIT license.
Something went wrong with that request. Please try again.