hyperactiveform 0.1.0 → 0.3.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (35) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +7 -0
  3. data/README.md +35 -1
  4. data/docs/HyperActiveForm/Base.html +884 -0
  5. data/docs/HyperActiveForm/CancelFormSubmit.html +124 -0
  6. data/docs/HyperActiveForm/FormDidNotSubmitError.html +124 -0
  7. data/docs/HyperActiveForm/Generators/InstallGenerator.html +199 -0
  8. data/docs/HyperActiveForm/Generators.html +115 -0
  9. data/docs/HyperActiveForm.html +135 -0
  10. data/docs/_index.html +182 -0
  11. data/docs/class_list.html +54 -0
  12. data/docs/css/common.css +1 -0
  13. data/docs/css/full_list.css +58 -0
  14. data/docs/css/style.css +503 -0
  15. data/docs/file.README.html +271 -0
  16. data/docs/file_list.html +59 -0
  17. data/docs/frames.html +22 -0
  18. data/docs/index.html +271 -0
  19. data/docs/js/app.js +344 -0
  20. data/docs/js/full_list.js +242 -0
  21. data/docs/js/jquery.js +4 -0
  22. data/docs/method_list.html +126 -0
  23. data/docs/top-level-namespace.html +110 -0
  24. data/examples/basic.md +85 -0
  25. data/lib/generators/form/form_generator.rb +9 -0
  26. data/lib/generators/form/templates/form.rb +2 -0
  27. data/lib/{hyper_active_form/generators.rb → generators/hyper_active_form/install/install_generator.rb} +0 -2
  28. data/lib/generators/rspec/form_generator.rb +11 -0
  29. data/lib/generators/rspec/templates/form_spec.rb +5 -0
  30. data/lib/generators/test_unit/form_generator.rb +11 -0
  31. data/lib/generators/test_unit/templates/form_test.rb +7 -0
  32. data/lib/hyper_active_form/base.rb +43 -5
  33. data/lib/hyper_active_form/version.rb +1 -1
  34. data/lib/hyper_active_form.rb +0 -1
  35. metadata +44 -3
data/docs/file.README.html ADDED
@@ -0,0 +1,271 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.9.37
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" />
16
+
17
+ <script type="text/javascript">
18
+ pathId = "README";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: README</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'>
61
+ <h1 id="label-E2-9C-A8+HyperActiveForm+-E2-9C-A8">✨ HyperActiveForm ✨</h1>
62
+
63
+ <p>HyperActiveForm is a simple form object implementation for Rails.</p>
64
+
65
+ <p>Form objects are objects that encapsulate form logic and validations, they allow to extract the business logic out of the controller and models into specialized objects.</p>
66
+
67
+ <p>HyperActiveForm’s form objects mimic the ActiveModel API, so they work out of the box with Rails’ form helpers, and allow you to use the ActiveModel validations you already know.</p>
68
+
69
+ <p>This allows you to only keep strictly necessary validations in the model, and have business logic validations in the form object. This is especially useful when you want different validations to be applied depending on the context.</p>
70
+
71
+ <h2 id="label-Installation">Installation</h2>
72
+
73
+ <p>Add this line to your application’s Gemfile:</p>
74
+
75
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>hyperactiveform</span><span class='tstring_end'>&#39;</span></span>
76
+ </code></pre>
77
+
78
+ <p>And then execute:</p>
79
+
80
+ <pre class="code ruby"><code class="ruby">$ bundle install
81
+ </code></pre>
82
+
83
+ <p>Run the install generator:</p>
84
+
85
+ <pre class="code ruby"><code class="ruby">$ rails generate hyper_active_form:install
86
+ </code></pre>
87
+
88
+ <p>this will create an <code>ApplicationForm</code> class in your app/forms directory. You can use it as a base class for your form objects.</p>
89
+
90
+ <h2 id="label-Usage">Usage</h2>
91
+
92
+ <p>Here is an example of an <code>HyperActiveForm</code> form object:</p>
93
+
94
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProfileForm</span> <span class='op'>&lt;</span> <span class='const'>ApplicationForm</span>
95
+ <span class='comment'># proxy_for is used to delegate the model name to the class, and some methods to the object
96
+ </span> <span class='comment'># this helps use `form_with` in views without having to specify the url
97
+ </span> <span class='id identifier rubyid_proxy_for'>proxy_for</span> <span class='const'>User</span><span class='comma'>,</span> <span class='symbol'>:@user</span>
98
+
99
+ <span class='comment'># Define the form fields, using ActiveModel::Attributes
100
+ </span> <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:first_name</span>
101
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:last_name</span>
102
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:birth_date</span><span class='comma'>,</span> <span class='symbol'>:date</span>
103
+
104
+ <span class='comment'># Define the validations, using ActiveModel::Validations
105
+ </span> <span class='id identifier rubyid_validates'>validates</span> <span class='symbol'>:first_name</span><span class='comma'>,</span> <span class='label'>presence:</span> <span class='kw'>true</span>
106
+ <span class='id identifier rubyid_validates'>validates</span> <span class='symbol'>:last_name</span><span class='comma'>,</span> <span class='label'>presence:</span> <span class='kw'>true</span>
107
+ <span class='id identifier rubyid_validates'>validates</span> <span class='symbol'>:birth_date</span><span class='comma'>,</span> <span class='label'>presence:</span> <span class='kw'>true</span>
108
+
109
+ <span class='comment'># Pre-fill the form if needed
110
+ </span> <span class='kw'>def</span> <span class='id identifier rubyid_setup'>setup</span><span class='lparen'>(</span><span class='id identifier rubyid_user'>user</span><span class='rparen'>)</span>
111
+ <span class='ivar'>@user</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span>
112
+ <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_first_name'>first_name</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_first_name'>first_name</span>
113
+ <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_last_name'>last_name</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_last_name'>last_name</span>
114
+ <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_birth_date'>birth_date</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_birth_date'>birth_date</span>
115
+ <span class='kw'>end</span>
116
+
117
+ <span class='comment'># Perform the form logic
118
+ </span> <span class='kw'>def</span> <span class='id identifier rubyid_perform'>perform</span>
119
+ <span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_update!'>update!</span><span class='lparen'>(</span>
120
+ <span class='label'>first_name:</span> <span class='id identifier rubyid_first_name'>first_name</span><span class='comma'>,</span>
121
+ <span class='label'>last_name:</span> <span class='id identifier rubyid_last_name'>last_name</span><span class='comma'>,</span>
122
+ <span class='label'>birth_date:</span> <span class='id identifier rubyid_birth_date'>birth_date</span>
123
+ <span class='rparen'>)</span>
124
+ <span class='kw'>end</span>
125
+ <span class='kw'>end</span>
126
+ </code></pre>
127
+
128
+ <p>The controller would look like this:</p>
129
+
130
+ <pre class="code ruby"><code class="ruby">class UsersController &lt; ApplicationController
131
+
132
+ def edit
133
+ @form = ProfileForm.new(user: current_user)
134
+ end
135
+
136
+ def update
137
+ @form = ProfileForm.new(user: current_user)
138
+ if @form.submit(params[:user])
139
+ redirect_to root_path, notice: &quot;Profile updated&quot;
140
+ else
141
+ render :edit, status: :unprocessable_entity
142
+ end
143
+ end
144
+ </code></pre>
145
+
146
+ <p>And the view would look like this:</p>
147
+
148
+ <pre class="code ruby"><code class="ruby">&lt;%= form_with(model: @form) do |f| %&gt;
149
+ &lt;%= f.text_field :first_name %&gt;
150
+ &lt;%= f.text_field :last_name %&gt;
151
+ &lt;%= f.date_field :birth_date %&gt;
152
+
153
+ &lt;%= f.submit %&gt;
154
+ &lt;% end %&gt;
155
+ </code></pre>
156
+
157
+ <h3 id="label-Understanding+proxy_for">Understanding <code>proxy_for</code></h3>
158
+
159
+ <p><code>HyperActiveForm</code> mimics a model object, you can use <code>proxy_for</code> to tell it which class and object to delegate to.</p>
160
+
161
+ <p>When using <code>form_for</code> or <code>form_with</code>, Rails will choose the URL and method based on the object, according to the persisted state of the object and its model name.</p>
162
+
163
+ <p>The first argument of <code>proxy_for</code> is the class of the object, and the second argument is the name of the instance variable that holds the object.</p>
164
+
165
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProfileForm</span> <span class='op'>&lt;</span> <span class='const'>ApplicationForm</span>
166
+ <span class='id identifier rubyid_proxy_for'>proxy_for</span> <span class='const'>User</span><span class='comma'>,</span> <span class='symbol'>:@user</span> <span class='comment'># Will delegate to @user
167
+ </span><span class='kw'>end</span>
168
+ </code></pre>
169
+
170
+ <p>If you pass an url and method yourself, you don’t need to use <code>proxy_for</code>.</p>
171
+
172
+ <h3 id="label-Understanding+setup">Understanding <code>setup</code></h3>
173
+
174
+ <p><code>setup</code> is called just after the form is initialized, and is used to pre-fill the form with data from the object.</p>
175
+
176
+ <p><code>setup</code> will receive the same arguments as the initializer, so you can use it to pass any data you need to the form.</p>
177
+
178
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProfileForm</span> <span class='op'>&lt;</span> <span class='const'>ApplicationForm</span>
179
+ <span class='kw'>def</span> <span class='id identifier rubyid_setup'>setup</span><span class='lparen'>(</span><span class='id identifier rubyid_user'>user</span><span class='rparen'>)</span>
180
+ <span class='ivar'>@user</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span>
181
+ <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_first_name'>first_name</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_first_name'>first_name</span>
182
+ <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_last_name'>last_name</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_last_name'>last_name</span>
183
+ <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_birth_date'>birth_date</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_birth_date'>birth_date</span>
184
+ <span class='kw'>end</span>
185
+ <span class='kw'>end</span>
186
+ </code></pre>
187
+
188
+ <h3 id="label-Understanding+perform">Understanding <code>perform</code></h3>
189
+
190
+ <p>When using <code>submit</code> or <code>submit!</code>, <code>HyperActiveForm</code> will first assign the form attributes to the object, then perform the validations, then call <code>perform</code> on the object if the form is valid.</p>
191
+
192
+ <p>The <code>perform</code> method is where you should do the actual form logic, like updating the object or creating a new one.</p>
193
+
194
+ <p>If the return value of <code>perform</code> is not truthy, <code>HyperActiveForm</code> will consider the form encountered an error and <code>submit</code> will return <code>false</code>, or <code>submit!</code> will raise a <code>HyperActiveForm::FormDidNotSubmitError</code>.</p>
195
+
196
+ <p>At any point during the form processing, you can raise <code>HyperActiveForm::CancelForm</code> to cancel the form submission, this is the same as returning <code>false</code>.</p>
197
+
198
+ <h2 id="label-Understanding+add_errors_from">Understanding add_errors_from</h2>
199
+
200
+ <p><code>HyperActiveForm</code> provides a method to add errors from a model and apply them fo the form.</p>
201
+
202
+ <p>This is useful when the underlying model has validations that are not set up in the form object, and you want them to be applied to the form.</p>
203
+
204
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>User</span> <span class='op'>&lt;</span> <span class='const'>ApplicationRecord</span>
205
+ <span class='id identifier rubyid_validates'>validates</span> <span class='symbol'>:first_name</span><span class='comma'>,</span> <span class='label'>presence:</span> <span class='kw'>true</span>
206
+ <span class='kw'>end</span>
207
+
208
+ <span class='kw'>class</span> <span class='const'>ProfileForm</span> <span class='op'>&lt;</span> <span class='const'>ApplicationForm</span>
209
+ <span class='id identifier rubyid_proxy_for'>proxy_for</span> <span class='const'>User</span><span class='comma'>,</span> <span class='symbol'>:@user</span>
210
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:first_name</span>
211
+
212
+ <span class='kw'>def</span> <span class='id identifier rubyid_setup'>setup</span><span class='lparen'>(</span><span class='id identifier rubyid_user'>user</span><span class='rparen'>)</span>
213
+ <span class='ivar'>@user</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span>
214
+ <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_first_name'>first_name</span> <span class='op'>=</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_first_name'>first_name</span>
215
+ <span class='kw'>end</span>
216
+
217
+ <span class='kw'>def</span> <span class='id identifier rubyid_perform'>perform</span>
218
+ <span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_update!'>update!</span><span class='lparen'>(</span><span class='label'>first_name:</span> <span class='id identifier rubyid_first_name'>first_name</span><span class='rparen'>)</span> <span class='op'>||</span> <span class='id identifier rubyid_add_errors_from'>add_errors_from</span><span class='lparen'>(</span><span class='ivar'>@user</span><span class='rparen'>)</span>
219
+ <span class='kw'>end</span>
220
+ <span class='kw'>end</span>
221
+ </code></pre>
222
+
223
+ <h3 id="label-Not+all+forms+map+to+a+single+model">Not all forms map to a single model</h3>
224
+
225
+ <p>The power of <code>HyperActiveForm</code> is that you can use it to create forms that don’t map to a single model.</p>
226
+
227
+ <p>Some forms can be used to create several models at once. Doing so without form objects can be tedious especially with nested attributes.</p>
228
+
229
+ <p>Some forms dont map to any model at all, like a simple contact form that only sends an email and saves nothing in the database, or a sign in form that would only validate the credentials and return the instance of the connected user.</p>
230
+
231
+ <p>One great example of such forms are search forms. You can use a form object to encapsulate the search logic :</p>
232
+
233
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>UserSearchForm</span> <span class='op'>&lt;</span> <span class='const'>ApplicationForm</span>
234
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:name</span>
235
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:email</span>
236
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:min_age</span><span class='comma'>,</span> <span class='symbol'>:integer</span>
237
+
238
+ <span class='id identifier rubyid_attr_reader'>attr_reader</span> <span class='symbol'>:results</span> <span class='comment'># So the controller can access the results
239
+ </span>
240
+ <span class='kw'>def</span> <span class='id identifier rubyid_perform'>perform</span>
241
+ <span class='ivar'>@results</span> <span class='op'>=</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
242
+
243
+ <span class='kw'>if</span> <span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_present?'>present?</span>
244
+ <span class='ivar'>@results</span> <span class='op'>=</span> <span class='ivar'>@results</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>name:</span> <span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
245
+ <span class='kw'>end</span>
246
+ <span class='kw'>if</span> <span class='id identifier rubyid_email'>email</span><span class='period'>.</span><span class='id identifier rubyid_present?'>present?</span>
247
+ <span class='ivar'>@results</span> <span class='op'>=</span> <span class='ivar'>@results</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='id identifier rubyid_email'>email</span><span class='rparen'>)</span>
248
+ <span class='kw'>end</span>
249
+ <span class='kw'>if</span> <span class='id identifier rubyid_age'>age</span><span class='period'>.</span><span class='id identifier rubyid_present?'>present?</span>
250
+ <span class='ivar'>@results</span> <span class='op'>=</span> <span class='ivar'>@results</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>age &gt;= ?</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='id identifier rubyid_age'>age</span><span class='rparen'>)</span>
251
+ <span class='kw'>end</span>
252
+
253
+ <span class='kw'>true</span>
254
+ <span class='kw'>end</span>
255
+ <span class='kw'>end</span>
256
+ </code></pre>
257
+
258
+ <p>And in the controller:</p>
259
+
260
+ <p>“‘ruby class UsersController &lt; ApplicationController def index @form = UserSearchForm.new @<a href=":user">form.submit!(params</a>) @users = @form.results end end</p>
261
+ </div></div>
262
+
263
+ <div id="footer">
264
+ Generated on Sat Dec 14 13:22:03 2024 by
265
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
266
+ 0.9.37 (ruby-3.3.1).
267
+ </div>
268
+
269
+ </div>
270
+ </body>
271
+ </html>
data/docs/file_list.html ADDED
@@ -0,0 +1,59 @@
1
+ <!DOCTYPE html>
2
+ <html >
3
+ <head>
4
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
5
+ <meta charset="utf-8" />
6
+
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" />
8
+
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" />
10
+
11
+
12
+
13
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
+
17
+
18
+ <title>File List</title>
19
+ <base id="base_target" target="_parent" />
20
+ </head>
21
+ <body>
22
+ <div id="content">
23
+ <div class="fixed_header">
24
+ <h1 id="full_list_header">File List</h1>
25
+ <div id="full_list_nav">
26
+
27
+ <span><a target="_self" href="class_list.html">
28
+ Classes
29
+ </a></span>
30
+
31
+ <span><a target="_self" href="method_list.html">
32
+ Methods
33
+ </a></span>
34
+
35
+ <span><a target="_self" href="file_list.html">
36
+ Files
37
+ </a></span>
38
+
39
+ </div>
40
+
41
+ <div id="search">
42
+ <label for="search-class">Search:</label>
43
+ <input id="search-class" type="text" />
44
+ </div>
45
+ </div>
46
+
47
+ <ul id="full_list" class="file">
48
+
49
+
50
+ <li id="object_README" class="odd">
51
+ <div class="item"><span class="object_link"><a href="index.html" title="README">README</a></span></div>
52
+ </li>
53
+
54
+
55
+
56
+ </ul>
57
+ </div>
58
+ </body>
59
+ </html>
data/docs/frames.html ADDED
@@ -0,0 +1,22 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Documentation by YARD 0.9.37</title>
6
+ </head>
7
+ <script type="text/javascript">
8
+ var mainUrl = 'index.html';
9
+ try {
10
+ var match = decodeURIComponent(window.location.hash).match(/^#!(.+)/);
11
+ var name = match ? match[1] : mainUrl;
12
+ var url = new URL(name, location.href);
13
+ window.top.location.replace(url.origin === location.origin ? name : mainUrl);
14
+ } catch (e) {
15
+ window.top.location.replace(mainUrl);
16
+ }
17
+ </script>
18
+ <noscript>
19
+ <h1>Oops!</h1>
20
+ <h2>YARD requires JavaScript!</h2>
21
+ </noscript>
22
+ </html>