Provided by: libhtml-formhandler-perl_0.40050-2_all bug

NAME

       HTML::FormHandler::Manual::Validation - validating fields

VERSION

       version 0.40050

SYNOPSIS

       Manual Index

       There are many options for validating fields in FormHandler. Some validation is from field
       attributes, some from form or field methods, some from 'apply' actions on the fields.

Field attributes for validation

       Each individual field may have additional attributes that relate to validation, which are
       not documented here. See the individual field documentation, linked from
       HTML::FormHandler::Manual::Fields.

   required, required_when
       Setting the 'required' flag on a field initiates a check for the existence of some value.
       If the field does not have a value, the 'required' error message is issued.

          has_field 'section' => ( required => 1,
              messages => { required => 'Please provide a section' } );

       Note that a required flag on a subfield -- a field inside a compound field or repeatable
       field -- does not cause the containing field to be required.  You need to set 'required'
       all the way up, if that's the behavior that you want.

       If a field is empty and *not* required, no other field validation will be performed unless
       the 'validate_when_empty' flag (see below) is set. The form's 'validate' method, however,
       will always be called.

       There is also the 'required_when' attribute, which works the same way as the 'when' key on
       the apply actions.

           has_field 'fee' => ( required_when => { 'fie' => 2 } );

       When a 'required' or 'required_when' check fails, a 'missing' flag is set in the result:

           if ( $field->missing ) { ... }

   range_start, range_end
       Starting and ending range for number fields.

   unique
       Attribute used by the DBIC model to check for uniqueness.

   validate_when_empty
       If its 'validate_when_empty' flag is set to a true value, then a field will always undergo
       validation when its form is processed, even when that field is empty.

Validation methods

   validate_method
       You can provide a validation method for a field by setting a coderef with
       'validate_method'.

           has_field 'fox' => ( validate_method => \&check_fox );
           sub check_fox {
               my $self = shift; # self is the fox field
               unless( $self->value eq .... ) {
                   $self->add_error('....');
               }
           }

   validate_<field_name>
       If you provide a 'validate_<field_name>' method it will be automatically used.

           has_field 'cat';
           sub validate_cat {
               my ( $self, $field ) = @_; # self is the form
               unless ( $field->value eq  ... ) {
                   $field->add_error( '...' );
               }
           }

       If the field name has periods in it, they should be replaced with underscores.

   form validate method
       A form validation method can be used to do cross-validation or validation checks that need
       information from more than one field.

           sub validate {
               my $self = shift;
               $self->field('foo')->add_error('....')
                   if( $self->field('foo')->value eq '..' &&
                           $self->field('bar')->value eq '..' );
           }

   field validate method
       You can create a custom field to contain a commonly used validation. The validation in a
       custom field can be done with 'apply' or by using a 'validate' method.

           package MyApp::Form::Field::Custom;
           use HTML::FormHandler::Moose;
           extends 'HTML::FormHandler::Field'; # or a subclass of Field

           sub validate {
               ....
           }

Apply Actions: Filters, transformations, and constraints

       The actions in the 'apply' array (stored in the 'actions' attribute) will be performed in
       the order they are specified, allowing fine-grained control over inflation and validation.
       You can check constraints after transformations and vice versa. You can weave all three
       types of actions in any order you need.

       The two valid 'apply' array elements are 1) Moose types and 2) hashrefs with one of three
       keys: 'check', 'transform', and 'type'. The hashrefs will usually also have an additional
       key, 'message', with a string, array or coderef providing an error message, which is
       localized.

       The 'check' key can point to a regex, arrayref of strings, or coderef. The value of the
       'transform' key should be a coderef. The value of the 'type' key is a Moose type.

       In addition to the check and type keys, you can provide a 'when' key to only perform this
       validation when a particular field is a particular value:

           has_field 'fee';
           has_field 'fie' => ( apply => [
               { when => { fee => 1 }, check => qr/when/, message => 'Wrong fie' },
           ]);
           has_field 'fo';
           has_field 'fum_comp' => ( type => 'Compound' );
           has_field 'fum_comp.one';
           has_field 'fum_comp.two' => ( apply => [
               { when => { '+fee' => [1,2,3] }, check => qr/when/, message => 'Wrong two' },
           ]);

       The field name key in the 'when' hashref is assumed to be a field at the same "level" as
       this field (i.e. a sibling field in a compound). If you want to specify a field name from
       the form, prepend the name with a '+'.

       The 'when' hashref can contain multiple key/value pairs. This simply extends its test
       across multiple fields; all fields named in the hashref's keys must match their respective
       values in order for the overall 'when' test to pass.

       Transformations and coercions are called in an eval to catch the errors. Warnings are
       trapped in a sigwarn handler.

       See also HTML::FormHandler::Field and HTML::FormHandler::Validate.  See
       HTML::FormHandler::Manual::Inflation::Deflation for information on inflation and
       deflation.

   Moose types
       Moose types can be used to do both constraints and transformations. If a coercion exists
       it will be applied, resulting in a transformation. After coercing, the result is checked.
       You can use type constraints from MooseX::Types libraries or defined using
       Moose::Util::TypeConstraints.

       FormHandler supplies a library of Moose types in HTML::FormHandler::Types.

           use HTML::FormHandler::Types ('NotAllDigits');
           has_field 'foo' => ( apply => [ NotAllDigits ] );

       You can create your own library of types, too. Or you can create a type constraint in the
       form:

         use Moose::Util::TypeConstraints;
         subtype 'GreaterThan10'
            => as 'Int'
            => where { $_ > 10 }
            => message { "This number ($_) is not greater than 10" };

         has_field 'text_gt' => ( apply=> [ 'GreaterThan10' ] );

       Moose types can also be used for their coercions to do transformations.

         subtype 'MyInt'
             => as 'Int';
         coerce 'MyInt'
             => from 'MyStr'
             => via { return $1 if /(\d+)/ };

       You can also use the 'type' keyword with a Moose type if you want to change the message:

           has_field 'text_gt' => ( apply => [
               { type => 'GreaterThan10',
                 message => 'Number is too small' } ] );

   transform
       A 'transform' changes the format of a field's value, and does not need a message. It takes
       a coderef.

          has_field 'another_field' => (
             apply => [ { transform => sub{ sprintf '<%.1g>', $_[0] } } ]
          );

       Note that transformed values are not displayed in the HTML form unless the
       'fif_from_value' flag is set. The transformed values are saved to the database or returned
       in "$form->value".

   'check' regex
       Checks that field value matches the regex.

          has_field 'some_field' => (
             apply => [ { check => qr/aaa/, message => 'Must contain aaa' } ],
          );

       You can use regex libraries like Regexp::Common too:

           use Regexp::Common ('URI');
           ...
           has_field 'my_url' => ( apply => [
               { check => qr/$RE{URI}{HTTP}/,
                  message => 'Invalid URL' } ] );

   'check' arrayref (matches)
       Provide an arrayref of strings to match against.

          has_field 'set_error' => (
             apply => [
                { check   => [ 'abc', 'bbb' ],
                   message => 'Must be "aaa" or "bbb"' }
             ]
          );

   'check' coderef
       Provide a validation function to check. A 'check' coderef will be passed the current value
       of the field and should return true or false. Note that the field is passed in as the
       second argument, to allow simple functions to work properly.

          has_field 'callback_pass' => (
             apply => [
                { check => \&check_callback_pass,
                    message => 'Must contain number greater than 10', }
              ]
          );
          sub check_callback_pass {
              my ( $value, $field ) = @_;
              if( $value =~ /(\d+)/ ) {
                  return $1 > 10;
              }
          }

   message
       The message for the above checks can also be an arrayref or coderef.  The arrayref is
       useful for localized messages. You can also provide error messages for Moose types.

          has_field 'message_sub' => (
             apply => [
                { check   => [ 'abc' ],
                   message => \&err_message }
             ]
          );
          sub err_message {
              my ($value, $field ) = @_;
              return $field->name . ': Must be "abc"';
          }
          has_field 'message_arrayref' => (
             apply => [ { check => qr/aaa/,
                 message => ['Must contain [_1]', 'aaa'] } ],
          );
          has_field 'my_moose_type_field' => (
             apply => [ { type => SomeType,
                message => 'Invalid ...' } ] );

   actions in a field class
       To declare actions inside a field class use HTML::FormHandler::Moose and 'apply' sugar:

          package MyApp::Field::Test;
          use HTML::FormHandler::Moose;
          extends 'HTML::FormHandler::Field;

          apply [ 'SomeConstraint', { check => ..., message => .... } ];

          1;

       Actions specified with apply are cumulative. Actions may be specified in field classes and
       additional actions added in the 'has_field' declaration.

       You can see examples of field classes with 'apply' actions in the source for
       HTML::FormHandler::Field::Money and HTML::FormHandler::Field::Email, and in
       t/constraints.t.

Dependency

       The 'dependency' attribute is an array of arrays of field names.  During validation, if
       any field in a given group has a value that matches the pattern /\S/ (non-blank), the
       'required' flag is set for all of the fields in the group.

          has '+dependency' => ( default => sub {
                   [
                      ['address', 'city', 'state', 'zip'],
                      ['cc_no', 'cc_expires'],
                   ],
               },
           );

       You can also use the 'required_when' flag to do something similar.

AUTHOR

       FormHandler Contributors - see HTML::FormHandler

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Gerda Shank.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.