.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::FormHandler::Manual::Validation 3pm"
.TH HTML::FormHandler::Manual::Validation 3pm "2022-03-25" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::FormHandler::Manual::Validation \- validating fields
.SH "VERSION"
.IX Header "VERSION"
version 0.40068
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Manual Index
.PP
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.
.SH "Field attributes for validation"
.IX Header "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.
.SS "required, required_when"
.IX Subsection "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.
.PP
.Vb 2
\&   has_field \*(Aqsection\*(Aq => ( required => 1,
\&       messages => { required => \*(AqPlease provide a section\*(Aq } );
.Ve
.PP
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.
.PP
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.
.PP
There is also the 'required_when' attribute, which works the same way as the
\&'when' key on the apply actions.
.PP
.Vb 1
\&    has_field \*(Aqfee\*(Aq => ( required_when => { \*(Aqfie\*(Aq => 2 } );
.Ve
.PP
When a 'required' or 'required_when' check fails, a 'missing' flag is set
in the result:
.PP
.Vb 1
\&    if ( $field\->missing ) { ... }
.Ve
.SS "range_start, range_end"
.IX Subsection "range_start, range_end"
Starting and ending range for number fields.
.SS "unique"
.IX Subsection "unique"
Attribute used by the \s-1DBIC\s0 model to check for uniqueness.
.SS "validate_when_empty"
.IX Subsection "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.
.SH "Validation methods"
.IX Header "Validation methods"
.SS "validate_method"
.IX Subsection "validate_method"
You can provide a validation method for a field by setting a coderef with
\&'validate_method'.
.PP
.Vb 7
\&    has_field \*(Aqfox\*(Aq => ( validate_method => \e&check_fox );
\&    sub check_fox {
\&        my $self = shift; # self is the fox field
\&        unless( $self\->value eq .... ) {
\&            $self\->add_error(\*(Aq....\*(Aq);
\&        }
\&    }
.Ve
.SS "validate_<field_name>"
.IX Subsection "validate_<field_name>"
If you provide a 'validate_<field_name>' method it will be automatically used.
.PP
.Vb 7
\&    has_field \*(Aqcat\*(Aq;
\&    sub validate_cat {
\&        my ( $self, $field ) = @_; # self is the form
\&        unless ( $field\->value eq  ... ) {
\&            $field\->add_error( \*(Aq...\*(Aq );
\&        }
\&    }
.Ve
.PP
If the field name has periods in it, they should be replaced with underscores.
.SS "form validate method"
.IX Subsection "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.
.PP
.Vb 6
\&    sub validate {
\&        my $self = shift;
\&        $self\->field(\*(Aqfoo\*(Aq)\->add_error(\*(Aq....\*(Aq)
\&            if( $self\->field(\*(Aqfoo\*(Aq)\->value eq \*(Aq..\*(Aq &&
\&                    $self\->field(\*(Aqbar\*(Aq)\->value eq \*(Aq..\*(Aq );
\&    }
.Ve
.SS "field validate method"
.IX Subsection "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.
.PP
.Vb 3
\&    package MyApp::Form::Field::Custom;
\&    use HTML::FormHandler::Moose;
\&    extends \*(AqHTML::FormHandler::Field\*(Aq; # or a subclass of Field
\&
\&    sub validate {
\&        ....
\&    }
.Ve
.SH "Apply Actions: Filters, transformations, and constraints"
.IX Header "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.
.PP
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.
.PP
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.
.PP
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:
.PP
.Vb 10
\&    has_field \*(Aqfee\*(Aq;
\&    has_field \*(Aqfie\*(Aq => ( apply => [
\&        { when => { fee => 1 }, check => qr/when/, message => \*(AqWrong fie\*(Aq },
\&    ]);
\&    has_field \*(Aqfo\*(Aq;
\&    has_field \*(Aqfum_comp\*(Aq => ( type => \*(AqCompound\*(Aq );
\&    has_field \*(Aqfum_comp.one\*(Aq;
\&    has_field \*(Aqfum_comp.two\*(Aq => ( apply => [
\&        { when => { \*(Aq+fee\*(Aq => [1,2,3] }, check => qr/when/, message => \*(AqWrong two\*(Aq },
\&    ]);
.Ve
.PP
The field name key in the 'when' hashref is assumed to be a field at the same
\&\*(L"level\*(R" 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 '+'.
.PP
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.
.PP
.Vb 4
\&     when => { foo => 3 }        # when the foo field value is 3
\&     when => { foo => [1,2,3]}   # when foo is 1, 2, or 3
\&     when => { foo => sub { $_[0] > 0 }}  # when foo is greater than 0
\&     when => { foo => sub { $_[0] ne \*(Aq\*(Aq}} # when foo is the empty string
.Ve
.PP
Transformations and coercions are called in an eval
to catch the errors. Warnings are trapped in a sigwarn handler.
.PP
If the conditions get too complicated to easily fit into a when condition, you
can always create a validation method instead.
.PP
See also HTML::FormHandler::Field and HTML::FormHandler::Validate.
See HTML::FormHandler::Manual::InflationDeflation for information
on inflation and deflation.
.SS "Moose types"
.IX Subsection "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.
.PP
FormHandler supplies a library of Moose types in HTML::FormHandler::Types.
.PP
.Vb 2
\&    use HTML::FormHandler::Types (\*(AqNotAllDigits\*(Aq);
\&    has_field \*(Aqfoo\*(Aq => ( apply => [ NotAllDigits ] );
.Ve
.PP
You can create your own library of types, too. Or you can create a type
constraint in the form:
.PP
.Vb 5
\&  use Moose::Util::TypeConstraints;
\&  subtype \*(AqGreaterThan10\*(Aq
\&     => as \*(AqInt\*(Aq
\&     => where { $_ > 10 }
\&     => message { "This number ($_) is not greater than 10" };
\&
\&  has_field \*(Aqtext_gt\*(Aq => ( apply=> [ \*(AqGreaterThan10\*(Aq ] );
.Ve
.PP
Moose types can also be used for their coercions to do transformations.
.PP
.Vb 5
\&  subtype \*(AqMyInt\*(Aq
\&      => as \*(AqInt\*(Aq;
\&  coerce \*(AqMyInt\*(Aq
\&      => from \*(AqMyStr\*(Aq
\&      => via { return $1 if /(\ed+)/ };
.Ve
.PP
You can also use the 'type' keyword with a Moose type if you want to
change the message:
.PP
.Vb 3
\&    has_field \*(Aqtext_gt\*(Aq => ( apply => [
\&        { type => \*(AqGreaterThan10\*(Aq,
\&          message => \*(AqNumber is too small\*(Aq } ] );
.Ve
.SS "transform"
.IX Subsection "transform"
A 'transform' changes the format of a field's value, and does not
need a message. It takes a coderef.
.PP
.Vb 3
\&   has_field \*(Aqanother_field\*(Aq => (
\&      apply => [ { transform => sub{ sprintf \*(Aq<%.1g>\*(Aq, $_[0] } } ]
\&   );
.Ve
.PP
Note that transformed values are not displayed in the \s-1HTML\s0 form unless
the 'fif_from_value' flag is set. The transformed values are saved
to the database or returned in \f(CW\*(C`$form\->value\*(C'\fR.
.SS "'check' regex"
.IX Subsection "'check' regex"
Checks that field value matches the regex.
.PP
.Vb 3
\&   has_field \*(Aqsome_field\*(Aq => (
\&      apply => [ { check => qr/aaa/, message => \*(AqMust contain aaa\*(Aq } ],
\&   );
.Ve
.PP
You can use regex libraries like Regexp::Common too:
.PP
.Vb 5
\&    use Regexp::Common (\*(AqURI\*(Aq);
\&    ...
\&    has_field \*(Aqmy_url\*(Aq => ( apply => [
\&        { check => qr/$RE{URI}{HTTP}/,
\&           message => \*(AqInvalid URL\*(Aq } ] );
.Ve
.SS "'check' arrayref (matches)"
.IX Subsection "'check' arrayref (matches)"
Provide an arrayref of strings to match against.
.PP
.Vb 6
\&   has_field \*(Aqset_error\*(Aq => (
\&      apply => [
\&         { check   => [ \*(Aqabc\*(Aq, \*(Aqbbb\*(Aq ],
\&            message => \*(AqMust be "aaa" or "bbb"\*(Aq }
\&      ]
\&   );
.Ve
.SS "'check' coderef"
.IX Subsection "'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.
.PP
.Vb 12
\&   has_field \*(Aqcallback_pass\*(Aq => (
\&      apply => [
\&         { check => \e&check_callback_pass,
\&             message => \*(AqMust contain number greater than 10\*(Aq, }
\&       ]
\&   );
\&   sub check_callback_pass {
\&       my ( $value, $field ) = @_;
\&       if( $value =~ /(\ed+)/ ) {
\&           return $1 > 10;
\&       }
\&   }
.Ve
.SS "message"
.IX Subsection "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.
.PP
.Vb 10
\&   has_field \*(Aqmessage_sub\*(Aq => (
\&      apply => [
\&         { check   => [ \*(Aqabc\*(Aq ],
\&            message => \e&err_message }
\&      ]
\&   );
\&   sub err_message {
\&       my ($value, $field ) = @_;
\&       return $field\->name . \*(Aq: Must be "abc"\*(Aq;
\&   }
\&   has_field \*(Aqmessage_arrayref\*(Aq => (
\&      apply => [ { check => qr/aaa/,
\&          message => [\*(AqMust contain [_1]\*(Aq, \*(Aqaaa\*(Aq] } ],
\&   );
\&   has_field \*(Aqmy_moose_type_field\*(Aq => (
\&      apply => [ { type => SomeType,
\&         message => \*(AqInvalid ...\*(Aq } ] );
.Ve
.SS "actions in a field class"
.IX Subsection "actions in a field class"
To declare actions inside a field class use HTML::FormHandler::Moose and
\&'apply' sugar:
.PP
.Vb 3
\&   package MyApp::Field::Test;
\&   use HTML::FormHandler::Moose;
\&   extends \*(AqHTML::FormHandler::Field;
\&
\&   apply [ \*(AqSomeConstraint\*(Aq, { check => ..., message => .... } ];
\&
\&   1;
.Ve
.PP
Actions specified with apply are cumulative. Actions may be specified in
field classes and additional actions added in the 'has_field' declaration.
.PP
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.
.SH "Dependency"
.IX Header "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 /\eS/ (non-blank), the 'required' flag
is set for all of the fields in the group.
.PP
.Vb 7
\&   has \*(Aq+dependency\*(Aq => ( default => sub {
\&            [
\&               [\*(Aqaddress\*(Aq, \*(Aqcity\*(Aq, \*(Aqstate\*(Aq, \*(Aqzip\*(Aq],
\&               [\*(Aqcc_no\*(Aq, \*(Aqcc_expires\*(Aq],
\&            ],
\&        },
\&    );
.Ve
.PP
You can also use the 'required_when' flag to do something similar.
.SH "AUTHOR"
.IX Header "AUTHOR"
FormHandler Contributors \- see HTML::FormHandler
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017 by Gerda Shank.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.