view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

  $id = $self->param('id');

The flattened parameter can also be used

  $name = $self->param('user.name');

See L<Mojolicious::Plugin::ParamExpand> for more info.

=head2 SCOPING

Fields can be scoped to a particular object/data structure via the C<< L</fields> >> helper

  my $user = fields('user');
  $user->text('name');
  $user->hidden('id');

When using C<fields> you must supply the field's name to the HTML input and validation methods, otherwise
the calls are the same as they are with C<field>.

=head2 COLLECTIONS

You can also create fields scoped to elements in a collection

  my $addresses = field('user.addresses');
  for my $addr (@$addresses) {
    # field('user.addresses.N.id')->hidden
    $addr->hidden('id');

    # field('user.addresses.N.street')->text
    $addr->text('street');

    # field('user.addresses.N.city')->select([qw|OAK PHL LAX|])
    $addr->select('city', [qw|OAK PHL LAX|]);
  }

Or, for fields that are already scoped

  my $user = fields('user')
  $user->hidden('id');

  my $addressess = $user->fields('addresses');
  for my $addr (@$addresses) {
    $addr->hidden('id')
    # ...
  }

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

  <% for my $addr (@$addresses) {  %>
    <div id="<%= dom_id($addr->object) %>">
      <h3>Address #<%= $addr->index + 1 %></h3>
      <%= $addr->hidden('id') %>
      ...
    </div>
  <% } %>

=head1 VALIDATING & FILTERING

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

  # In your controller
  my $self = shift;
  $self->field('user.name')->is_required;
  $self->field('user.name')->filter('trim');

These methods can be chained

  $self->field('user.name')->is_required->filter('trim');

To perform validation on a field call its C<valid> method

  $field = $self->field('user.name');
  $field->is_required;
  $field->valid;
  $field->error;

This will only validate and return the error for the C<user.name> field. To validate all fields and retrieve all error messages call the controller's C<valid> and C<errors> methods

  $self->field('user.name')->is_required;
  $self->field('user.age')->is_like(qr/^\d+$/);
  $self->valid;

  my $errors = $self->errors;
  $errors->{'user.name'}
  # ...

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

  <% unless(valid()) { %>
    <p>Hey, fix the below errors</p>
  <% } %>

  <%= field('name')->text %>
  <% unless(field('name')->valid) { %>
    <span class="error"><%= field('name')->error %></span>
  <% } %>

When creating validation rules for L</fields> you must pass the field name as the first argument

  my $user = fields('user');
  $user->is_required('password');
  $user->is_equal(password => 'confirm_password');
  $user->is_long_at_least(password => 8, 'Mais longo caipira');

=head2 AVAILABLE RULES & FILTERS

C<Mojolicious::Plugin::FormFields> uses C<Validate::Tiny>, see L<its docs|Validate::Tiny/filter> for a list.

=head2 RENAMING THE VALIDATION METHODS

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

  $self->plugin('FormFields', methods => { valid => 'form_valid', errors => 'form_errors' });
  # ...

  $self->field('user.name')->is_required;
  $self->form_valid;
  $self->form_errors;

Note that this I<only> changes the methods B<on the controller> and does not change the methods on the object returned by C<field>.

=head1 METHODS

=head2 field

  field($name)->text
  field($name, $object)->text

=head3 Arguments

C<$name>

The field's name, which can also be the path to its value in the stash. See L</CREATING FIELDS>.

C<$object>