view release on metacpan or  search on metacpan

out.html  view on Meta::CPAN

<p>See <a href="http://search.cpan.org/perldoc?Mojolicious%3A%3APlugin%3A%3AParamExpand" class="podlinkpod"
>Mojolicious::Plugin::ParamExpand</a> for more info.</p>

<h2><a class='u'
name="SCOPING"
>SCOPING</a></h2>

<p>Fields can be scoped to a particular object/data structure via the <code><a href="#fields" class="podlinkpod"
>&#34;fields&#34;</a></code> helper</p>

<pre>  my $user = fields(&#39;user&#39;);
  $user-&#62;text(&#39;name&#39;);
  $user-&#62;hidden(&#39;id&#39;);</pre>

<p>When using <code>fields</code> you must supply the field&#39;s name to the HTML input and validation methods, otherwise the calls are the same as they are with <code>field</code>.</p>

<h2><a class='u'
name="COLLECTIONS"
>COLLECTIONS</a></h2>

<p>You can also create fields scoped to elements in a collection</p>

<pre>  my $addresses = field(&#39;user.addresses&#39;);
  for my $addr (@$addresses) {
    # field(&#39;user.addresses.N.id&#39;)-&#62;hidden
    $addr-&#62;hidden(&#39;id&#39;);

    # field(&#39;user.addresses.N.street&#39;)-&#62;text
    $addr-&#62;text(&#39;street&#39;);

    # field(&#39;user.addresses.N.city&#39;)-&#62;select([qw|OAK PHL LAX|])
    $addr-&#62;select(&#39;city&#39;, [qw|OAK PHL LAX|]);
  }</pre>

<p>Or, for fields that are already scoped</p>

<pre>  my $user = fields(&#39;user&#39;)
  $user-&#62;hidden(&#39;id&#39;);

  my $addressess = $user-&#62;fields(&#39;addresses&#39;);
  for my $addr (@$addresses) {
    $addr-&#62;hidden(&#39;id&#39;)
    # ...
  }</pre>

<p>You can also access the underlying object and its position within a collection via the <code>object</code> and <code>index</code> methods.</p>

<pre>  &#60;% for my $addr (@$addresses) {  %&#62;
    &#60;div id=&#34;&#60;%= dom_id($addr-&#62;object) %&#62;&#34;&#62;
      &#60;h3&#62;Address #&#60;%= $addr-&#62;index + 1 %&#62;&#60;/h3&#62;
      &#60;%= $addr-&#62;hidden(&#39;id&#39;) %&#62;
      ...
    &#60;/div&#62;
  &#60;% } %&#62;</pre>

<h1><a class='u'
name="VALIDATING_&#38;_FILTERING"
>VALIDATING &#38; FILTERING</a></h1>

<p>Validation rules are created by calling validation and/or filter methods on the field to be validated</p>

<pre>  # In your controller
  my $self = shift;
  $self-&#62;field(&#39;user.name&#39;)-&#62;is_required;
  $self-&#62;field(&#39;user.name&#39;)-&#62;filter(&#39;trim&#39;);</pre>

<p>These methods can be chained</p>

<pre>  $self-&#62;field(&#39;user.name&#39;)-&#62;is_required-&#62;filter(&#39;trim&#39;);</pre>

<p>To perform validation on a field call its <code>valid</code> method</p>

<pre>  $field = $self-&#62;field(&#39;user.name&#39;);
  $field-&#62;is_required;
  $field-&#62;valid;
  $field-&#62;error;</pre>

<p>This will only validate and return the error for the <code>user.name</code> field. To validate all fields and retrieve all error messages call the controller&#39;s <code>valid</code> and <code>errors</code> methods</p>

<pre>  $self-&#62;field(&#39;user.name&#39;)-&#62;is_required;
  $self-&#62;field(&#39;user.age&#39;)-&#62;is_like(qr/^\d+$/);
  $self-&#62;valid;

  my $errors = $self-&#62;errors;
  $errors-&#62;{&#39;user.name&#39;}
  # ...</pre>

<p>Of course the <code>error</code>/<code>errors</code> and <code>valid</code> methods can be used in your view too</p>

<pre>  &#60;% unless(valid()) { %&#62;
    &#60;p&#62;Hey, fix the below errors&#60;/p&#62;
  &#60;% } %&#62;

  &#60;%= field(&#39;name&#39;)-&#62;text %&#62;
  &#60;% unless(field(&#39;name&#39;)-&#62;valid) { %&#62;
    &#60;span class=&#34;error&#34;&#62;&#60;%= field(&#39;name&#39;)-&#62;error %&#62;&#60;/span&#62;
  &#60;% } %&#62;</pre>

<p>When creating validation rules for <a href="#fields" class="podlinkpod"
>&#34;fields&#34;</a> you must pass the field name as the first argument</p>

<pre>  my $user = fields(&#39;user&#39;);
  $user-&#62;is_required(&#39;password&#39;);
  $user-&#62;is_equal(password =&#62; &#39;confirm_password&#39;);
  $user-&#62;is_long_at_least(password =&#62; 8, &#39;Mais longo caipira&#39;);</pre>

<h2><a class='u'
name="AVAILABLE_RULES_&#38;_FILTERS"
>AVAILABLE RULES &#38; FILTERS</a></h2>

<p><code>Mojolicious::Plugin::FormFields</code> uses <code>Validate::Tiny</code>, see <a href="http://search.cpan.org/perldoc?Validate%3A%3ATiny#filter" class="podlinkpod"
>its docs</a> for a list.</p>

<h2><a class='u'
name="RENAMING_THE_VALIDATION_METHODS"
>RENAMING THE VALIDATION METHODS</a></h2>

<p>In the event that the <code>valid</code> and/or <code>errors</code> methods clash with exiting methods/helpers in your app you can rename them by specifying alternate names when loading the plugin</p>

<pre>  $self-&#62;plugin(&#39;FormFields&#39;, methods =&#62; { valid =&#62; &#39;form_valid&#39;, errors =&#62; &#39;form_errors&#39; });
  # ...

  $self-&#62;field(&#39;user.name&#39;)-&#62;is_required;
  $self-&#62;form_valid;
  $self-&#62;form_errors;</pre>

<p>Note that this <i>only</i> changes the methods <b>on the controller</b> and does not change the methods on the object returned by <code>field</code>.</p>

<h1><a class='u'
name="METHODS"
>METHODS</a></h1>

<h2><a class='u'
name="field"
>field</a></h2>

<pre>  field($name)-&#62;text
  field($name, $object)-&#62;text</pre>