compony 0.3.3 → 0.4.0

data/doc/Compony/ModelMixin.html

@@ -264,14 +264,14 @@
       <pre class="lines">
 
 
-92
-93
-94
-95
-96</pre>
+99
+100
+101
+102
+103</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 92</span>
+      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 99</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_feasibility_messages'>feasibility_messages</span><span class='lparen'>(</span><span class='id identifier rubyid_action_name'>action_name</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_action_name'>action_name</span> <span class='op'>=</span> <span class='id identifier rubyid_action_name'>action_name</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span>
@@ -360,13 +360,6 @@
       <pre class="lines">
 
 
-71
-72
-73
-74
-75
-76
-77
 78
 79
 80
@@ -376,10 +369,17 @@
 84
 85
 86
-87</pre>
+87
+88
+89
+90
+91
+92
+93
+94</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 71</span>
+      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 78</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_feasible?'>feasible?</span><span class='lparen'>(</span><span class='id identifier rubyid_action_name'>action_name</span><span class='comma'>,</span> <span class='label'>recompute:</span> <span class='kw'>false</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_action_name'>action_name</span> <span class='op'>=</span> <span class='id identifier rubyid_action_name'>action_name</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span>
@@ -429,12 +429,12 @@
       <pre class="lines">
 
 
-109
-110
-111</pre>
+116
+117
+118</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 109</span>
+      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 116</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_field'>field</span><span class='lparen'>(</span><span class='id identifier rubyid_field_name'>field_name</span><span class='comma'>,</span> <span class='id identifier rubyid_controller'>controller</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_fields'>fields</span><span class='lbracket'>[</span><span class='id identifier rubyid_field_name'>field_name</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value_for'>value_for</span><span class='lparen'>(</span><span class='kw'>self</span><span class='comma'>,</span> <span class='label'>controller:</span><span class='rparen'>)</span>
@@ -490,14 +490,14 @@
       <pre class="lines">
 
 
-102
-103
-104
-105
-106</pre>
+109
+110
+111
+112
+113</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 102</span>
+      <pre class="code"><span class="info file"># File 'lib/compony/model_mixin.rb', line 109</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_full_feasibility_messages'>full_feasibility_messages</span><span class='lparen'>(</span><span class='id identifier rubyid_action_name'>action_name</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_text'>text</span> <span class='op'>=</span> <span class='id identifier rubyid_feasibility_messages'>feasibility_messages</span><span class='lparen'>(</span><span class='id identifier rubyid_action_name'>action_name</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>, </span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_upcase_first'>upcase_first</span>
@@ -514,7 +514,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:54 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/Compony/NaturalOrdering.html

@@ -290,7 +290,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:54 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/Compony/RequestContext.html

@@ -931,7 +931,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:54 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/Compony/Version.html

@@ -129,7 +129,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:54 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/Compony/ViewHelpers.html

@@ -433,7 +433,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:54 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/Compony.html

@@ -2129,7 +2129,7 @@
   <span class='kw'>end</span>
   <span class='id identifier rubyid_return_value'>return_value</span> <span class='op'>=</span> <span class='id identifier rubyid_block'>block</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span>
   <span class='comment'># Restore previous value
-</span>  <span class='id identifier rubyid_keys_to_overwrite'>keys_to_overwrite</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_key'>key</span><span class='comma'>,</span> <span class='id identifier rubyid__new_value'>_new_value</span><span class='op'>|</span>
+</span>  <span class='id identifier rubyid_keys_to_overwrite'>keys_to_overwrite</span><span class='period'>.</span><span class='id identifier rubyid_each_key'>each_key</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_key'>key</span><span class='op'>|</span>
     <span class='const'>RequestStore</span><span class='period'>.</span><span class='id identifier rubyid_store'>store</span><span class='lbracket'>[</span><span class='symbol'>:button_defaults</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='id identifier rubyid_key'>key</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='id identifier rubyid_old_values'>old_values</span><span class='lbracket'>[</span><span class='id identifier rubyid_key'>key</span><span class='rbracket'>]</span>
   <span class='kw'>end</span>
   <span class='comment'># Undefine keys that were not there previously
@@ -2146,7 +2146,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:54 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/ComponyController.html

@@ -114,7 +114,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:54 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/_index.html

@@ -566,7 +566,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:38 2024 by
+  Generated on Tue Jun 11 11:15:52 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/file.README.html

@@ -1305,6 +1305,8 @@ my_button = Compony.button(:index, :users, enabled: -> { |controller| control
 <span class='kw'>end</span>
 </code></pre>
 
+<p>All fields declared this way are automatically exported as Rails Model attributes. Note that this also means that you should never declare <code>password</code> and <code>password_confirmation</code> as a Compony field, as you will get the ArgumentError “One or more password arguments are required” otherwise. Read more about handling password fields in the section about <code>Compony::Components::Form</code>.</p>
+
 <p>Compony fields provide the following features:</p>
 <ul><li>
 <p>a label that lets you generate a name for the column: <code>User.fields[:first_name].label</code></p>
@@ -1446,6 +1448,45 @@ my_button = Compony.button(:index, :users, enabled: -&gt; { |controller| control
 
 <p>Note that the inputs and schema are two completely different concepts that are not auto-inferred from each other. You must make sure that they always correspond. If you forget to mention a field in <code>schema_fields</code>, posting the form will fail. Luckily, Schemacop’s excellent error messaging will explain which parameter is prohibited.</p>
 
+<p>Both calls respect Cancancan’s <code>permitted_attributes</code> directive. This means that you can safely declare <code>field</code> and <code>schema_field</code> in a form that is shared among users with different kinds of permissions. If the current user is not allowed to access a field, the input will be omitted automatically. Further, the parameter validation will exclude that field, effectively disallowing that user from submitting that parameter.</p>
+
+<h4 id="label-Handling+password+fields">Handling password fields</h4>
+
+<p>When using Rails’ <code>has_secure_password</code> method, which typically generates the attributes accessors <code>:password</code> and <code>password_confirmation</code>, do not declare these two as fields in your User model.</p>
+
+<p>There are two main reasons for this:</p>
+<ul><li>
+<p><code>password</code> and <code>password_confirmation</code> should never show up in lists and show pages, and as these kinds of components tend to iterate over all fields, it’s best to have anything that should not show up there declared as a field in the first place.</p>
+</li><li>
+<p>Rails’ <code>authenticate_by</code> does not work when <code>password</code> is declared as a model attribute.</p>
+</li></ul>
+
+<p>Instead of making these accessors Compony fields, ignore them in the User model and use the following methods in your Form:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'><span class='object_link'><a href="Components.html" title="Components (module)">Components</a></span></span><span class='op'>::</span><span class='const'>Users</span><span class='op'>::</span><span class='const'>Form</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Compony.html" title="Compony (module)">Compony</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Compony/Components.html" title="Compony::Components (module)">Components</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Compony/Components/Form.html" title="Compony::Components::Form (class)">Form</a></span></span>
+  <span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_form_fields'>form_fields</span> <span class='kw'>do</span>
+      <span class='comment'># ...
+</span>      <span class='id identifier rubyid_concat'>concat</span> <span class='id identifier rubyid_pw_field'>pw_field</span><span class='lparen'>(</span><span class='symbol'>:password</span><span class='rparen'>)</span>
+      <span class='id identifier rubyid_concat'>concat</span> <span class='id identifier rubyid_pw_field'>pw_field</span><span class='lparen'>(</span><span class='symbol'>:password_confirmation</span><span class='rparen'>)</span>
+    <span class='kw'>end</span>
+
+    <span class='comment'># ...
+</span>    <span class='id identifier rubyid_schema_pw_field'>schema_pw_field</span> <span class='symbol'>:password</span>
+    <span class='id identifier rubyid_schema_pw_field'>schema_pw_field</span> <span class='symbol'>:password_confirmation</span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>In contrast to the regular <code>field</code> and <code>schema_field</code> calls, their <code>pw_...</code> pendants do not check for per-field authorization. Instead, they check whether the current user can <code>:set_password</code> on the form’s object. Therefore, your ability may look something like:</p>
+
+<pre class="code ruby"><code class="ruby">class Ability
+  # ...
+  can :manage, User # This allows full access to all users
+  cannot :manage, User, [:user_role] # This prohibits access to user_role, thus removing the input and making the parameter invalid if passed anyway
+  cannot :set_password, User # This prohibits setting and changing passwords of any user
+</code></pre>
+
 <h3 id="label-New">New</h3>
 
 <p>This component is the Compony equivalent to a typical Rails controller’s <code>new</code> and <code>create</code> actions.</p>
@@ -1621,7 +1662,7 @@ my_button = Compony.button(:index, :users, enabled: -&gt; { |controller| control
 </div></div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:40 2024 by
+  Generated on Tue Jun 11 11:15:53 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>

data/doc/index.html

@@ -1305,6 +1305,8 @@ my_button = Compony.button(:index, :users, enabled: -> { |controller| control
 <span class='kw'>end</span>
 </code></pre>
 
+<p>All fields declared this way are automatically exported as Rails Model attributes. Note that this also means that you should never declare <code>password</code> and <code>password_confirmation</code> as a Compony field, as you will get the ArgumentError “One or more password arguments are required” otherwise. Read more about handling password fields in the section about <code>Compony::Components::Form</code>.</p>
+
 <p>Compony fields provide the following features:</p>
 <ul><li>
 <p>a label that lets you generate a name for the column: <code>User.fields[:first_name].label</code></p>
@@ -1446,6 +1448,45 @@ my_button = Compony.button(:index, :users, enabled: -&gt; { |controller| control
 
 <p>Note that the inputs and schema are two completely different concepts that are not auto-inferred from each other. You must make sure that they always correspond. If you forget to mention a field in <code>schema_fields</code>, posting the form will fail. Luckily, Schemacop’s excellent error messaging will explain which parameter is prohibited.</p>
 
+<p>Both calls respect Cancancan’s <code>permitted_attributes</code> directive. This means that you can safely declare <code>field</code> and <code>schema_field</code> in a form that is shared among users with different kinds of permissions. If the current user is not allowed to access a field, the input will be omitted automatically. Further, the parameter validation will exclude that field, effectively disallowing that user from submitting that parameter.</p>
+
+<h4 id="label-Handling+password+fields">Handling password fields</h4>
+
+<p>When using Rails’ <code>has_secure_password</code> method, which typically generates the attributes accessors <code>:password</code> and <code>password_confirmation</code>, do not declare these two as fields in your User model.</p>
+
+<p>There are two main reasons for this:</p>
+<ul><li>
+<p><code>password</code> and <code>password_confirmation</code> should never show up in lists and show pages, and as these kinds of components tend to iterate over all fields, it’s best to have anything that should not show up there declared as a field in the first place.</p>
+</li><li>
+<p>Rails’ <code>authenticate_by</code> does not work when <code>password</code> is declared as a model attribute.</p>
+</li></ul>
+
+<p>Instead of making these accessors Compony fields, ignore them in the User model and use the following methods in your Form:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'><span class='object_link'><a href="Components.html" title="Components (module)">Components</a></span></span><span class='op'>::</span><span class='const'>Users</span><span class='op'>::</span><span class='const'>Form</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Compony.html" title="Compony (module)">Compony</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Compony/Components.html" title="Compony::Components (module)">Components</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Compony/Components/Form.html" title="Compony::Components::Form (class)">Form</a></span></span>
+  <span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_form_fields'>form_fields</span> <span class='kw'>do</span>
+      <span class='comment'># ...
+</span>      <span class='id identifier rubyid_concat'>concat</span> <span class='id identifier rubyid_pw_field'>pw_field</span><span class='lparen'>(</span><span class='symbol'>:password</span><span class='rparen'>)</span>
+      <span class='id identifier rubyid_concat'>concat</span> <span class='id identifier rubyid_pw_field'>pw_field</span><span class='lparen'>(</span><span class='symbol'>:password_confirmation</span><span class='rparen'>)</span>
+    <span class='kw'>end</span>
+
+    <span class='comment'># ...
+</span>    <span class='id identifier rubyid_schema_pw_field'>schema_pw_field</span> <span class='symbol'>:password</span>
+    <span class='id identifier rubyid_schema_pw_field'>schema_pw_field</span> <span class='symbol'>:password_confirmation</span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>In contrast to the regular <code>field</code> and <code>schema_field</code> calls, their <code>pw_...</code> pendants do not check for per-field authorization. Instead, they check whether the current user can <code>:set_password</code> on the form’s object. Therefore, your ability may look something like:</p>
+
+<pre class="code ruby"><code class="ruby">class Ability
+  # ...
+  can :manage, User # This allows full access to all users
+  cannot :manage, User, [:user_role] # This prohibits access to user_role, thus removing the input and making the parameter invalid if passed anyway
+  cannot :set_password, User # This prohibits setting and changing passwords of any user
+</code></pre>
+
 <h3 id="label-New">New</h3>
 
 <p>This component is the Compony equivalent to a typical Rails controller’s <code>new</code> and <code>create</code> actions.</p>
@@ -1621,7 +1662,7 @@ my_button = Compony.button(:index, :users, enabled: -&gt; { |controller| control
 </div></div>
 
       <div id="footer">
-  Generated on Mon Jun  3 15:20:39 2024 by
+  Generated on Tue Jun 11 11:15:53 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.36 (ruby-3.2.2).
 </div>