NAME

       HTML::FormFu::Constraint - Constrain User Input

VERSION

       version 2.07

SYNOPSIS

           ---
           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

DESCRIPTION

       User input is processed in the following order:

       Filters
       Constraints
       Inflators
       Validators
       Transformers

       See "FORM LOGIC AND VALIDATION" in HTML::FormFu for further details.

       "constraints"  in  HTML::FormFu  can  be  called on any form, block element (includes fieldsets) or field
       element.

       If called on a field element, no "name" argument should be passed.

       If called on a form or block element, if no "name" argument is provided, a new constraint is created  for
       and added to every field on that form or block.

       See "FORM LOGIC AND VALIDATION" in HTML::FormFu for further details.

METHODS

   type
       Returns the "type" argument originally used to create the constraint.

   not
       If true, inverts the results of the constraint - such that input that would otherwise fail will pass, and
       vise-versa.

       This value is ignored by some constraints - see the documentation for individual constraints for details.

   only_on_reps
       Argument: \@repeatable_count

       For  constraints  added  to  fields within a Repeatable element, if "only_on_reps" is set, the constraint
       will only be run for fields whose repeatable_count matches one of these set values.

       Not    available    for    the     constraints     listed     in     "Unsupported     Constraints"     in
       HTML::FormFu::Element::Repeatable.

   message
       Arguments: $string

       Set the message which will be displayed if the constraint fails.

   message_xml
       Arguments: $string

       Variant of "message" which ensures the value won't be XML-escaped.

   message_loc
       Arguments: $string

       Variant of "message" which uses localize to create the message.

   localize_args
       Provide  arguments  that  should  be  passed to localize to replace "[_1]", "[_2]", etc. in the localized
       string.

   force_errors
       See "force_errors" in HTML::FormFu for details.

   parent
       Returns the field object that the constraint is associated with.

   form
       Returns the HTML::FormFu object that the constraint's field is attached to.

   name
       Shorthand for "$constraint->parent->name"

   when
       Defines a condition for the constraint. Only when the condition  is  fulfilled  the  constraint  will  be
       applied.

       This method expects a hashref.

       The "field" or "callback" must be supplied, all other fields are optional.

       If "value" or "values" is not supplied, the constraint will pass if the named field's value is true.

       The following keys are supported:

       field
           Nested-name  of  form  field  that  shall  be checked against - if "when->{value}" is set, the "when"
           condition passes if the named field's value matches that, otherwise the "when"  condition  passes  if
           the named field's value is true.

       fields
           Array-ref  of  nested-names  that  shall be checked. The "when" condition passes if all named-fields'
           values pass, using the same rules as "field" above.

       any_field
           Array-ref of nested-names that shall be checked. The "when" condition  passes  if  any  named-fields'
           values pass, using the same rules as "field" above.

       value
           Expected value in the form field 'field'

       values
           Array of multiple values, one must match to fulfill the condition

       not Inverts the when condition - value(s) must not match

       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.

           The callback subroutine receives 2 arguments:

           1.      $params (hashref of all submitted parameters)

           2.      $constraint (the Constraint object)

EXPERIMENTAL METHODS

   fetch_error_message
       Return value: $string

       Attempt to return the error message that would be used if this constraint generated an error.

       This will generally be correct for simple constraints with a fixed message or  which  use  a  placeholder
       from a known value, such as "min" in HTML::FormFu::Constraint::Min.  This will generally "not" return the
       correct  message  for constraints which use "others" in HTML::FormFu::Role::Constraint::Others, where the
       field with an error is not known without actually fully processing a form submission.

CORE CONSTRAINTS

       HTML::FormFu::Constraint::AllOrNone
       HTML::FormFu::Constraint::ASCII
       HTML::FormFu::Constraint::AutoSet
       HTML::FormFu::Constraint::Bool
       HTML::FormFu::Constraint::Callback
       HTML::FormFu::Constraint::CallbackOnce
       HTML::FormFu::Constraint::DateTime
       HTML::FormFu::Constraint::DependOn
       HTML::FormFu::Constraint::Email
       HTML::FormFu::Constraint::Equal
       HTML::FormFu::Constraint::File
       HTML::FormFu::Constraint::File::MIME
       HTML::FormFu::Constraint::File::MaxSize
       HTML::FormFu::Constraint::File::MinSize
       HTML::FormFu::Constraint::File::Size
       HTML::FormFu::Constraint::Integer
       HTML::FormFu::Constraint::JSON
       HTML::FormFu::Constraint::Length
       HTML::FormFu::Constraint::MaxLength
       HTML::FormFu::Constraint::MaxRange
       HTML::FormFu::Constraint::MinLength
       HTML::FormFu::Constraint::MinRange
       HTML::FormFu::Constraint::MinMaxFields
       HTML::FormFu::Constraint::Number
       HTML::FormFu::Constraint::Printable
       HTML::FormFu::Constraint::Range
       HTML::FormFu::Constraint::Regex
       HTML::FormFu::Constraint::Required
       HTML::FormFu::Constraint::Set
       HTML::FormFu::Constraint::SingleValue
       HTML::FormFu::Constraint::Word

NON-CORE CONSTRAINTS AVAILABLE ON CPAN

       HTML::FormFu::Constraint::reCAPTCHA

CAVEATS

       See "Unsupported Constraints" in HTML::FormFu::Element::Repeatable for a list of constraints  that  won't
       work within HTML::FormFu::Element::Repeatable.

AUTHOR

       Carl Franks, "cfranks@cpan.org"

       Based on the original source code of HTML::Widget::Constraint, by Sebastian Riedel, "sri@oook.de".

LICENSE

       This  library  is  free  software,  you can redistribute it and/or modify it under the same terms as Perl
       itself.

AUTHOR

       Carl Franks <cpan@fireartist.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2018 by Carl Franks.

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

perl v5.28.1                                       2019-01-12                      HTML::FormFu::Constraint(3pm)