NAME

HTML::FormFu::Constraint - Constrain User Input

VERSION

version 2.03

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 fullfilled 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 fullfill 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::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.