Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 193 lines (142 sloc) 7.553 kB
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
1 == SimpleForm
a7d0cc2 @carlosantoniodasilva Initial commit.
carlosantoniodasilva authored
2
3 Forms made easy!
4
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
5 SimpleForm aims to be as flexible as possible while helping you with powerful components to create your forms. The basic goal of simple form is to not touch your way of defining the layout, this way letting you find how you find the better design for your eyes.
6
7 == Instalation
8
9 sudo gem install simple_form
10
11 == Usage
12
13 SimpleForm was designed to be customized as you need to. Basically it's a stack of components that are generated to create a complete html input for you, with label + hints + errors. The best of this is that you can add any element on this stack in any place, or even remove any of them.
14
15 To start using SimpleForm you just have to use the helper it provides:
16
17 <% simple_form_for @user do |f| -%>
18 <p><%= f.input :username %></p>
19 <p><%= f.input :password %></p>
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
20 <p><%= f.button %></p>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
21 <% end -%>
22
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
23 This will generate an entire form with labels for user name and password as well, and render errors by default when you render the form with invalid data (after submitting for example).
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
24
25 You can overwrite the default label by passing it to the input method, or even add a hint:
26
27 <% simple_form_for @user do |f| -%>
28 <p><%= f.input :username, :label => 'Your username please' %></p>
29 <p><%= f.input :password, :hint => 'No special characters.' %></p>
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
30 <p><%= f.button %></p>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
31 <% end -%>
32
33 Or you can disable labels, hints and errors inside a specific input:
34
35 <% simple_form_for @user do |f| -%>
36 <p><%= f.input :username, :label => false %></p>
37 <p><%= f.input :password, :hint => false, :error => false %></p>
38 <p><%= f.input :password_confirmation, :error => false %></p>
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
39 <p><%= f.button %></p>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
40 <% end -%>
41
42 You can also pass html options for the label, input, hint or error tag:
43
44 <% simple_form_for @user do |f| -%>
45 <p><%= f.input :name, :label_html => { :class => 'my_class' } %></p>
46 <p><%= f.input :username, :input_html => { :disabled => true } %></p>
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
47 <p><%= f.input :password, :hint => 'Confirm!',
48 :hint_html => { :id => 'password_hint' } %></p>
49 <p><%= f.input :password_confirmation,
50 :error_html => { :id => 'password_error' } %></p>
51 <p><%= f.button %></p>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
52 <% end -%>
53
54 By default all inputs are required, but you can disable it in any input you want:
55
56 <% simple_form_for @user do |f| -%>
57 <p><%= f.input :name, :required => false %></p>
58 <p><%= f.input :username %></p>
59 <p><%= f.input :password %></p>
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
60 <p><%= f.button %></p>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
61 <% end -%>
62
63 This way the name input will not have the required text and css classes. SimpleForm also lets you overwrite the default input type it creates:
64
65 <% simple_form_for @user do |f| -%>
66 <p><%= f.input :username %></p>
67 <p><%= f.input :password %></p>
68 <p><%= f.input :active, :as => :radio %></p>
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
69 <p><%= f.button %></p>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
70 <% end -%>
71
72 So instead of a checkbox for the active attribute, you'll have a set of boolean radio buttons with yes/no options. You can do the same with :as => :select option for boolean attributes.
73
74 What if you want to create a select containing the age from 18 to 60 in your form? You can do it overriding the :collection option:
75
76 <% simple_form_for @user do |f| -%>
77 <p><%= f.input :user %></p>
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
78 <p><%= f.input :age, :collection => 18..60 %></p>
79 <p><%= f.button %></p>
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
80 <% end -%>
81
82 Collections can be arrays or ranges, and when a :collection is given the :select input will be rendered by default, so we don't need to pass the :as => :select option.
83
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
84 SimpleForm also allows you using label, hint and error helpers it provides:
85
86 <% simple_form_for @user do |f| -%>
87 <p><%= f.label :username, :label => 'Type your user name:' %></p>
88 <p><%= f.text_field :username %></p>
89 <p><%= f.error :username, :id => 'user_name_error' %></p>
90 <p><%= f.hint 'No special characters, please!' %></p>
91 <p><%= f.submit 'Save' %></p>
92 <% end -%>
93
94 Any extra option passed to label, hint or error will be rendered as html option.
95
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
96 == Inputs available
97
98 == I18n
99
100 SimpleForm uses all power of I18n API to lookup labels and hints for you. To customize your forms you can create a locale file like this:
101
102 en:
103 simple_form:
104 labels:
105 user:
106 username: 'User name'
107 password: 'Password'
108 hints:
109 user:
110 username: 'User name to sign in.'
111 password: 'No special characters, please.'
112
113 And your forms will use this information to render labels and hints for you.
114
115 SimpleForm also lets you be more specific, separating lookups through actions. Let's say you want a different label and hint for new and edit actions, the locale file would be something like:
116
117 en:
118 simple_form:
119 labels:
120 user:
121 new:
122 username: 'User name'
123 password: 'Password'
124 edit:
125 username: 'Change user name'
126 password: 'Change password'
127 hints:
128 user:
129 new:
130 username: 'User name to sign in.'
131 password: 'No special characters, please.'
132 edit:
133 username: 'Update your user name to sign in.'
134 password: 'Let it blank to not change your password.'
135
136 This way SimpleForm will figure out the right translation for you, based on the action being rendered. And to be a little bit DRYer with your locale file, you can skip the model information inside it:
137
138 en:
139 simple_form:
140 labels:
141 username: 'User name'
142 password: 'Password'
143 hints:
144 username: 'User name to sign in.'
145 password: 'No special characters, please.'
146
147 SimpleForm will always look for a default attribute translation if no specific is found inside the model key. In addition, SimpleForm will fallback to default human_attribute_name from Rails when no other translation is found.
148
149 Finally, you can also overwrite labels and hints inside your view, just by passing the label/hint manually. This way the I18n lookup will be skipped.
150
151 There are other options that can be configured through I18n API, such as required for labels and boolean texts, you just need to overwrite the following keys:
152
153 en:
154 simple_form:
155 true: 'Yes'
156 false: 'No'
157 required:
158 text: 'required'
159 mark: '*'
160
161 Instead of using the text and mark options from required, you can also overwrite the entire required html string as follows:
162
163 en:
164 simple_form:
165 required:
a304564 @carlosantoniodasilva Fix typos, improving readme a little, updating todo.
carlosantoniodasilva authored
166 html: '<abbr title="required">*</abbr> '
fd490a7 @carlosantoniodasilva First work on docs.
carlosantoniodasilva authored
167
168 == Configuration
169
170 You have a set of options available to configure SimpleForm:
171
172 * component_tag => default tag used in components. by default is :span.
173 * components => stack of components used in form builder to create the input.
174 You can add or remove any of this components as you need.
175 * terminator => the last component will call this terminator. By default it's
176 a lambda returning an empty string.
177 * collection_label_methods => all methods available to detect the label for a
178 collection.
179 * collection_value_methods => all methods available to detect the value for a
180 collection.
181 * wrapper_tag => wrapper tag to wrap the inputs. By default no wrapper exists.
182
183 To do it so you just need to create a file inside your initializer folder and use the configurations as follows:
184
185 SimpleForm.collection_label_methods = [:to_label, :title, :description, :name, :to_s]
186
a7d0cc2 @carlosantoniodasilva Initial commit.
carlosantoniodasilva authored
187 == TODO
188
189 Please refer to TODO file.
190
191
192 MIT License. Copyright 2009 Plataforma Tecnologia. http://blog.plataformatec.com.br
Something went wrong with that request. Please try again.