Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 128 lines (80 sloc) 5.727 kB
51b13fe @rpheath updated README
authored
1 h1. FormAssistant
bd9829d @rpheath basic infrastructure for form assistant
authored
2
48dbba2 @rpheath updated README to reflect new changes
authored
3 This is a Rails plugin that provides a custom form builder that attempts to make forms somewhat friendly.
53c7c16 @rpheath updated README
authored
4
3f69e5b @rpheath updated README
authored
5 h2. Usage
6
48dbba2 @rpheath updated README to reflect new changes
authored
7 Once installed, use the form assistant just like #form_for():
bd9829d @rpheath basic infrastructure for form assistant
authored
8
40d52f6 @rpheath updated README
authored
9 <pre><code><% form_assistant_for @project do |form| %>
10 // typical form_for stuff
48dbba2 @rpheath updated README to reflect new changes
authored
11 <% end %></code></pre>
51b13fe @rpheath updated README
authored
12
48dbba2 @rpheath updated README to reflect new changes
authored
13 Or if you'd rather use #form_for() everywhere, you can set the form assistant's builder to be your default across the entire application like so:
51b13fe @rpheath updated README
authored
14
48dbba2 @rpheath updated README to reflect new changes
authored
15 <pre><code>ActionView::Base.default_form_builder = RPH::FormAssistant::FormBuilder</code></pre>
e4d33d2 @rpheath updated README
authored
16
3f69e5b @rpheath updated README
authored
17 h2. Defaults and Configuration
51b13fe @rpheath updated README
authored
18
3f69e5b @rpheath updated README
authored
19 Things you can customize...
51b13fe @rpheath updated README
authored
20
3f69e5b @rpheath updated README
authored
21 <pre><code># config/initializers/form_assistant.rb
31d36d8 @rpheath updated README
authored
22
3f69e5b @rpheath updated README
authored
23 RPH::FormAssistant::FormBuilder.ignore_templates = true # defaults to false
f79e60b @rpheath added ability to toggle label's on and off globally
authored
24 RPH::FormAssistant::FormBuilder.ignore_labels = true # defaults to false
0312b5f @rpheath cattr_accessor consistency
authored
25 RPH::FormAssistant::FormBuilder.ignore_errors = true # defaults to false
3f69e5b @rpheath updated README
authored
26 RPH::FormAssistant::FormBuilder.template_root = '...' # defaults to app/views/forms
27 </code></pre>
51b13fe @rpheath updated README
authored
28
31d36d8 @rpheath updated README
authored
29 The only thing worth mentioning deals with ignoring templates. If you ignore the templates, you will still get access to all of the custom helpers and your form helpers (@text_field@, @text_area@, etc) will automatically have labels attached to them. The form assistant considers trailing labels, too, meaning if you have a @check_box@ the label will be _after_ the check box instead of before it. It will also be given a CSS class of 'inline'.
30
40d52f6 @rpheath updated README
authored
31 h2. Examples
51b13fe @rpheath updated README
authored
32
e4d33d2 @rpheath updated README
authored
33 Here are a few reasons why it's worth using the form assistant.
34
35 I'm going to refer to a @form@ object in the examples. Assume this object is yielded back to the block of a form assistant call, like so:
36
48dbba2 @rpheath updated README to reflect new changes
authored
37 <pre><code><% form_assistant_for @project do |form| %>
12946c5 @rpheath updated README
authored
38 // the 'form' object would be used in here
e4d33d2 @rpheath updated README
authored
39 <% end %>
40 </code></pre>
41
fc9359f @rpheath use alias_method_chain to keep a more traditional API for fields_for()
authored
42 And just to be clear, the regular @fields_for()@ doesn't inherit the builder from the builder object, but as long as you're using the form assistant, this problem has been taken care of automatically. Just call the @fields_for()@ helper on the builder object, like so:
67f36a5 @rpheath added fields_assistant_for() helper that will automatically use the f…
authored
43
fc9359f @rpheath use alias_method_chain to keep a more traditional API for fields_for()
authored
44 <pre><code><% form_assistant_for @project do |form| %>
45 <% form.fields_for :tasks do |task_fields| %>
46 <%= task_fields.text_field :name %>
47 <% end %>
67f36a5 @rpheath added fields_assistant_for() helper that will automatically use the f…
authored
48 <% end %>
49 </code></pre>
50
3f69e5b @rpheath updated README
authored
51 h3. Form Templates
52
53 The new and improved form assistant uses partials to format your fields, labels, errors (if any), and tips. To get started, run...
54
55 <pre><code>$> rake form_assistant:install</code></pre>
56
57 ...from your project root. That will put some example form partials in app/views/forms/*.
e4d33d2 @rpheath updated README
authored
58
f22ea33 @rpheath updated README
authored
59 By default, the form assistant will try to render a template based on the name of the helper. For instance, calling <pre><code><%= form.text_field :title %></code></pre> will look for a template called _text_field.html.erb located in app/views/forms. However, you can specify a different template easily:
60
61 <pre><code><%= form.text_field :title, :template => 'custom_template' %></code></pre>
62
3f69e5b @rpheath updated README
authored
63 If a specified template doesn't exist, a fallback template will be used (called '_field.html.erb').
f22ea33 @rpheath updated README
authored
64
3f69e5b @rpheath updated README
authored
65 There's also a @#fieldset()@ helper available to you, although it doesn't belong to the form object (it's mixed into action view itself).
66
67 <pre><code><% fieldset 'User Registration' do %>
68 <%= form.text_field :name %>
69 <%= form.text_field :username %>
70 <%= form.text_field :password %>
71 <% end %>
72 </code></pre>
73
74 The nice thing about that is it's also controlled by a template (cleverly called '_fieldset.html.erb').
8a81085 @rpheath updated README
authored
75
968f52d @rpheath added ability to mark a field as required
authored
76 h3. Required Fields
77
78 You can now pass a @:required@ flag to the field helpers, and it will be available within the templates.
79
80 <pre><code><%= form.text_field :title, :required => true %></code></pre>
81
82 Then you can check the 'required' local variable and handle it accordingly. Naturally, this defaults to false.
83
3f69e5b @rpheath updated README
authored
84 h3. Form Labels
85
86 Another convenient thing about the form assistant is the ability to control labels from their respective helper. For example...
c05cafe @rpheath updated README
authored
87
ff54330 @rpheath now also allowing label text to be set via :label => 'Text'
authored
88 <pre><code><%= form.text_field :title, :label => 'Project Title' %>
89 <%= form.text_field :title, :label_text => 'Project Title' %>
e4d33d2 @rpheath updated README
authored
90 <%= form.text_field :title, :label_class => 'required' %>
c05cafe @rpheath updated README
authored
91 <%= form.text_field :title, :label_id => 'dom_id' %>
92 <%= form.text_field :title, :label => { :text => 'Project Title', :id => 'dom_id', :class => 'required' } %>
6f72d8e @rpheath added ability to ignore labels on a per-helper basis
authored
93 <%= form.text_field :title, :label => false %>
e4d33d2 @rpheath updated README
authored
94 </code></pre>
95
c05cafe @rpheath updated README
authored
96 That works for all form helpers (text_area, check_box, etc). And by default, the label will be the humanized version of the field name, so that's what you'll get if you ignore the label options altogether.
e4d33d2 @rpheath updated README
authored
97
8d95b73 @scharfie Updated README
scharfie authored
98 h3. Form Widgets
99
100 Sometimes, a single form field isn't enough. Form assistant provides a construct to help you
101 with this, called widget:
102
103 <pre><code><% form.widget :expiration_date, :label => 'Card expiration date' do %>
104 <%= form.select :expiration_month, (1..12) %>
105 <%= form.select :expiration_month, (1..12) %>
106 <% end %></code></pre>
107
108 There are a few things to note about this new feature:
109
110 * error messages will come from the errors on the field name ('expiration_date' in the above example)
111 * templates and labels are disabled for the duration of the block
112 * the default template for widgets is the fallback template (===_field.html.erb=== unless configured otherwise)
113
3f69e5b @rpheath updated README
authored
114 h3. Custom Helpers
115
4a2142b @scharfie less magic
scharfie authored
116 @#partial()@ helper:
4652f19 @rpheath updated README
authored
117
118 <pre><code><%= form.partial 'shared/new', :locals => { ... } %></code></pre>
119
120 The builder variable will be automatically passed as a local called 'form'.
121
3f69e5b @rpheath updated README
authored
122 h2. Requirements
123
124 The form assistant requires _at least_ Rails version 2.1.0. This is mainly due to the usage of the convenience methods now included in the Rails module (for things like @Rails.version@ and @Rails.root@).
125
40d52f6 @rpheath updated README
authored
126 h2. Licensing
51b13fe @rpheath updated README
authored
127
128 (c) 2008 Ryan Heath, released under the MIT license
Something went wrong with that request. Please try again.