.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTML::FormFu::Constraint 3pm"
.TH HTML::FormFu::Constraint 3pm "2014-05-05" "perl v5.18.2" "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::FormFu::Constraint \- Constrain User Input
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    \-\-\-
\&    elements:
\&      \- type: Text
\&        name: foo
\&        constraints:
\&          \- type: Length
\&            min: 8
\&            when:
\&              field: bar
\&              values: [ 1, 3, 5 ]
\&      \- type: Text
\&        name: bar
\&        constraints:
\&          \- Integer
\&          \- Required
\&    constraints:
\&      \- SingleValue
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
User input is processed in the following order:
.IP "Filters" 4
.IX Item "Filters"
.PD 0
.IP "Constraints" 4
.IX Item "Constraints"
.IP "Inflators" 4
.IX Item "Inflators"
.IP "Validators" 4
.IX Item "Validators"
.IP "Transformers" 4
.IX Item "Transformers"
.PD
.PP
See \*(L"\s-1FORM LOGIC AND VALIDATION\*(R"\s0 in HTML::FormFu for further details.
.PP
\&\*(L"constraints\*(R" in HTML::FormFu can be called on any form,
block element (includes fieldsets) or
field element.
.PP
If called on a field element, no \f(CW\*(C`name\*(C'\fR argument should be passed.
.PP
If called on a form or
block element, if no \f(CW\*(C`name\*(C'\fR argument is
provided, a new constraint is created for and added to every field on that
form or block.
.PP
See \*(L"\s-1FORM LOGIC AND VALIDATION\*(R"\s0 in HTML::FormFu for further details.
.SH "METHODS"
.IX Header "METHODS"
.SS "type"
.IX Subsection "type"
Returns the \f(CW\*(C`type\*(C'\fR argument originally used to create the constraint.
.SS "not"
.IX Subsection "not"
If true, inverts the results of the constraint \- such that input that would
otherwise fail will pass, and vise-versa.
.PP
This value is ignored by some constraints \- see the documentation for
individual constraints for details.
.SS "only_on_reps"
.IX Subsection "only_on_reps"
Argument: \e@repeatable_count
.PP
For constraints added to fields within a
Repeatable element, if \f(CW\*(C`only_on_reps\*(C'\fR
is set, the constraint will only be run for fields whose
repeatable_count
matches one of these set values.
.PP
Not available for the constraints listed in
\&\*(L"Unsupported Constraints\*(R" in HTML::FormFu::Element::Repeatable.
.SS "message"
.IX Subsection "message"
Arguments: \f(CW$string\fR
.PP
Set the message which will be displayed if the constraint fails.
.SS "message_xml"
.IX Subsection "message_xml"
Arguments: \f(CW$string\fR
.PP
Variant of \*(L"message\*(R" which ensures the value won't be XML-escaped.
.SS "message_loc"
.IX Subsection "message_loc"
Arguments: \f(CW$string\fR
.PP
Variant of \*(L"message\*(R" which uses localize to
create the message.
.SS "localize_args"
.IX Subsection "localize_args"
Provide arguments that should be passed to localize
to replace \f(CW\*(C`[_1]\*(C'\fR, \f(CW\*(C`[_2]\*(C'\fR, etc. in the localized string.
.SS "force_errors"
.IX Subsection "force_errors"
See \*(L"force_errors\*(R" in HTML::FormFu for details.
.SS "parent"
.IX Subsection "parent"
Returns the field object that the constraint
is associated with.
.SS "form"
.IX Subsection "form"
Returns the HTML::FormFu object that the constraint's field is attached
to.
.SS "name"
.IX Subsection "name"
Shorthand for \f(CW\*(C`$constraint\->parent\->name\*(C'\fR
.SS "when"
.IX Subsection "when"
Defines a condition for the constraint. Only when the condition is fullfilled
the constraint will be applied.
.PP
This method expects a hashref.
.PP
The \f(CW\*(C`field\*(C'\fR or \f(CW\*(C`callback\*(C'\fR must be supplied, all other fields are optional.
.PP
If \f(CW\*(C`value\*(C'\fR or \f(CW\*(C`values\*(C'\fR is not supplied, the constraint will pass if the
named field's value is true.
.PP
The following keys are supported:
.IP "field" 4
.IX Item "field"
Nested-name of form field that shall be checked against \- if \f(CW\*(C`when\-\*(C'\fR{value}>
is set, the \f(CW\*(C`when\*(C'\fR condition passes if the named field's value matches that,
otherwise the \f(CW\*(C`when\*(C'\fR condition passes if the named field's value is true.
.IP "fields" 4
.IX Item "fields"
Array-ref of nested-names that shall be checked. The \f(CW\*(C`when\*(C'\fR condition passes
if all named\-fields' values pass, using the same rules as \f(CW\*(C`field\*(C'\fR above.
.IP "any_field" 4
.IX Item "any_field"
Array-ref of nested-names that shall be checked. The \f(CW\*(C`when\*(C'\fR condition passes
if any named\-fields' values pass, using the same rules as \f(CW\*(C`field\*(C'\fR above.
.IP "value" 4
.IX Item "value"
Expected value in the form field 'field'
.IP "values" 4
.IX Item "values"
Array of multiple values, one must match to fullfill the condition
.IP "not" 4
.IX Item "not"
Inverts the when condition \- value(s) must not match
.IP "callback" 4
.IX Item "callback"
A callback subroutine-reference or fully resolved subroutine name can be
supplied to perform complex checks. An hashref of all parameters is passed
to the callback sub. In this case all other keys are ignored, including not.
You need to return a true value for the constraint to be applied or a false
value to not apply it.
.Sp
The callback subroutine receives 2 arguments:
.RS 4
.IP "1." 8
\&\f(CW$params\fR (hashref of all submitted parameters)
.IP "2." 8
\&\f(CW$constraint\fR (the Constraint object)
.RE
.RS 4
.RE
.SH "EXPERIMENTAL METHODS"
.IX Header "EXPERIMENTAL METHODS"
.SS "fetch_error_message"
.IX Subsection "fetch_error_message"
Return value: \f(CW$string\fR
.PP
Attempt to return the error message that would be used if this constraint 
generated an error.
.PP
This will generally be correct for simple constraints with a fixed message or
which use a placeholder from a known value, such as 
\&\*(L"min\*(R" in HTML::FormFu::Constraint::Min.
This will generally \f(CW\*(C`not\*(C'\fR return the correct message for constraints which
use \*(L"others\*(R" in HTML::FormFu::Role::Constraint::Others, where the field with an
error is not known without actually fully processing a form submission.
.SH "CORE CONSTRAINTS"
.IX Header "CORE CONSTRAINTS"
.IP "HTML::FormFu::Constraint::AllOrNone" 4
.IX Item "HTML::FormFu::Constraint::AllOrNone"
.PD 0
.IP "HTML::FormFu::Constraint::ASCII" 4
.IX Item "HTML::FormFu::Constraint::ASCII"
.IP "HTML::FormFu::Constraint::AutoSet" 4
.IX Item "HTML::FormFu::Constraint::AutoSet"
.IP "HTML::FormFu::Constraint::Bool" 4
.IX Item "HTML::FormFu::Constraint::Bool"
.IP "HTML::FormFu::Constraint::Callback" 4
.IX Item "HTML::FormFu::Constraint::Callback"
.IP "HTML::FormFu::Constraint::CallbackOnce" 4
.IX Item "HTML::FormFu::Constraint::CallbackOnce"
.IP "HTML::FormFu::Constraint::DateTime" 4
.IX Item "HTML::FormFu::Constraint::DateTime"
.IP "HTML::FormFu::Constraint::DependOn" 4
.IX Item "HTML::FormFu::Constraint::DependOn"
.IP "HTML::FormFu::Constraint::Email" 4
.IX Item "HTML::FormFu::Constraint::Email"
.IP "HTML::FormFu::Constraint::Equal" 4
.IX Item "HTML::FormFu::Constraint::Equal"
.IP "HTML::FormFu::Constraint::File" 4
.IX Item "HTML::FormFu::Constraint::File"
.IP "HTML::FormFu::Constraint::File::MIME" 4
.IX Item "HTML::FormFu::Constraint::File::MIME"
.IP "HTML::FormFu::Constraint::File::MaxSize" 4
.IX Item "HTML::FormFu::Constraint::File::MaxSize"
.IP "HTML::FormFu::Constraint::File::MinSize" 4
.IX Item "HTML::FormFu::Constraint::File::MinSize"
.IP "HTML::FormFu::Constraint::File::Size" 4
.IX Item "HTML::FormFu::Constraint::File::Size"
.IP "HTML::FormFu::Constraint::Integer" 4
.IX Item "HTML::FormFu::Constraint::Integer"
.IP "HTML::FormFu::Constraint::Length" 4
.IX Item "HTML::FormFu::Constraint::Length"
.IP "HTML::FormFu::Constraint::MaxLength" 4
.IX Item "HTML::FormFu::Constraint::MaxLength"
.IP "HTML::FormFu::Constraint::MaxRange" 4
.IX Item "HTML::FormFu::Constraint::MaxRange"
.IP "HTML::FormFu::Constraint::MinLength" 4
.IX Item "HTML::FormFu::Constraint::MinLength"
.IP "HTML::FormFu::Constraint::MinRange" 4
.IX Item "HTML::FormFu::Constraint::MinRange"
.IP "HTML::FormFu::Constraint::MinMaxFields" 4
.IX Item "HTML::FormFu::Constraint::MinMaxFields"
.IP "HTML::FormFu::Constraint::Number" 4
.IX Item "HTML::FormFu::Constraint::Number"
.IP "HTML::FormFu::Constraint::Printable" 4
.IX Item "HTML::FormFu::Constraint::Printable"
.IP "HTML::FormFu::Constraint::Range" 4
.IX Item "HTML::FormFu::Constraint::Range"
.IP "HTML::FormFu::Constraint::Regex" 4
.IX Item "HTML::FormFu::Constraint::Regex"
.IP "HTML::FormFu::Constraint::Required" 4
.IX Item "HTML::FormFu::Constraint::Required"
.IP "HTML::FormFu::Constraint::Set" 4
.IX Item "HTML::FormFu::Constraint::Set"
.IP "HTML::FormFu::Constraint::SingleValue" 4
.IX Item "HTML::FormFu::Constraint::SingleValue"
.IP "HTML::FormFu::Constraint::Word" 4
.IX Item "HTML::FormFu::Constraint::Word"
.PD
.SH "NON-CORE CONSTRAINTS AVAILABLE ON CPAN"
.IX Header "NON-CORE CONSTRAINTS AVAILABLE ON CPAN"
.IP "HTML::FormFu::Constraint::reCAPTCHA" 4
.IX Item "HTML::FormFu::Constraint::reCAPTCHA"
.SH "CAVEATS"
.IX Header "CAVEATS"
See \*(L"Unsupported Constraints\*(R" in HTML::FormFu::Element::Repeatable
for a list of constraints that won't work within
HTML::FormFu::Element::Repeatable.
.SH "AUTHOR"
.IX Header "AUTHOR"
Carl Franks, \f(CW\*(C`cfranks@cpan.org\*(C'\fR
.PP
Based on the original source code of HTML::Widget::Constraint, by
Sebastian Riedel, \f(CW\*(C`sri@oook.de\*(C'\fR.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.