HTML::FormFu::Constraint(3pm)

1HTML::FormFu::ConstrainUts(e3r)Contributed Perl DocumentHaTtMiLo:n:FormFu::Constraint(3)
2
3
4

NAME

6       HTML::FormFu::Constraint - Constrain User Input
7

VERSION

9       version 2.07
10

SYNOPSIS

12           ---
13           elements:
14             - type: Text
15               name: foo
16               constraints:
17                 - type: Length
18                   min: 8
19                   when:
20                     field: bar
21                     values: [ 1, 3, 5 ]
22             - type: Text
23               name: bar
24               constraints:
25                 - Integer
26                 - Required
27           constraints:
28             - SingleValue
29

DESCRIPTION

31       User input is processed in the following order:
32
33       Filters
34       Constraints
35       Inflators
36       Validators
37       Transformers
38
39       See "FORM LOGIC AND VALIDATION" in HTML::FormFu for further details.
40
41       "constraints" in HTML::FormFu can be called on any form, block element
42       (includes fieldsets) or field element.
43
44       If called on a field element, no "name" argument should be passed.
45
46       If called on a form or block element, if no "name" argument is
47       provided, a new constraint is created for and added to every field on
48       that form or block.
49
50       See "FORM LOGIC AND VALIDATION" in HTML::FormFu for further details.
51

METHODS

53   type
54       Returns the "type" argument originally used to create the constraint.
55
56   not
57       If true, inverts the results of the constraint - such that input that
58       would otherwise fail will pass, and vise-versa.
59
60       This value is ignored by some constraints - see the documentation for
61       individual constraints for details.
62
63   only_on_reps
64       Argument: \@repeatable_count
65
66       For constraints added to fields within a Repeatable element, if
67       "only_on_reps" is set, the constraint will only be run for fields whose
68       repeatable_count matches one of these set values.
69
70       Not available for the constraints listed in "Unsupported Constraints"
71       in HTML::FormFu::Element::Repeatable.
72
73   message
74       Arguments: $string
75
76       Set the message which will be displayed if the constraint fails.
77
78   message_xml
79       Arguments: $string
80
81       Variant of "message" which ensures the value won't be XML-escaped.
82
83   message_loc
84       Arguments: $string
85
86       Variant of "message" which uses localize to create the message.
87
88   localize_args
89       Provide arguments that should be passed to localize to replace "[_1]",
90       "[_2]", etc. in the localized string.
91
92   force_errors
93       See "force_errors" in HTML::FormFu for details.
94
95   parent
96       Returns the field object that the constraint is associated with.
97
98   form
99       Returns the HTML::FormFu object that the constraint's field is attached
100       to.
101
102   name
103       Shorthand for "$constraint->parent->name"
104
105   when
106       Defines a condition for the constraint. Only when the condition is
107       fulfilled the constraint will be applied.
108
109       This method expects a hashref.
110
111       The "field" or "callback" must be supplied, all other fields are
112       optional.
113
114       If "value" or "values" is not supplied, the constraint will pass if the
115       named field's value is true.
116
117       The following keys are supported:
118
119       field
120           Nested-name of form field that shall be checked against - if
121           "when->{value}" is set, the "when" condition passes if the named
122           field's value matches that, otherwise the "when" condition passes
123           if the named field's value is true.
124
125       fields
126           Array-ref of nested-names that shall be checked. The "when"
127           condition passes if all named-fields' values pass, using the same
128           rules as "field" above.
129
130       any_field
131           Array-ref of nested-names that shall be checked. The "when"
132           condition passes if any named-fields' values pass, using the same
133           rules as "field" above.
134
135       value
136           Expected value in the form field 'field'
137
138       values
139           Array of multiple values, one must match to fulfill the condition
140
141       not Inverts the when condition - value(s) must not match
142
143       callback
144           A callback subroutine-reference or fully resolved subroutine name
145           can be supplied to perform complex checks. An hashref of all
146           parameters is passed to the callback sub. In this case all other
147           keys are ignored, including "not".  You need to return a true value
148           for the constraint to be applied or a false value to not apply it.
149
150           The callback subroutine receives 2 arguments:
151
152           1.      $params (hashref of all submitted parameters)
153
154           2.      $constraint (the Constraint object)
155

EXPERIMENTAL METHODS

157   fetch_error_message
158       Return value: $string
159
160       Attempt to return the error message that would be used if this
161       constraint generated an error.
162
163       This will generally be correct for simple constraints with a fixed
164       message or which use a placeholder from a known value, such as "min" in
165       HTML::FormFu::Constraint::Min.  This will generally "not" return the
166       correct message for constraints which use "others" in
167       HTML::FormFu::Role::Constraint::Others, where the field with an error
168       is not known without actually fully processing a form submission.
169

CORE CONSTRAINTS

171       HTML::FormFu::Constraint::AllOrNone
172       HTML::FormFu::Constraint::ASCII
173       HTML::FormFu::Constraint::AutoSet
174       HTML::FormFu::Constraint::Bool
175       HTML::FormFu::Constraint::Callback
176       HTML::FormFu::Constraint::CallbackOnce
177       HTML::FormFu::Constraint::DateTime
178       HTML::FormFu::Constraint::DependOn
179       HTML::FormFu::Constraint::Email
180       HTML::FormFu::Constraint::Equal
181       HTML::FormFu::Constraint::File
182       HTML::FormFu::Constraint::File::MIME
183       HTML::FormFu::Constraint::File::MaxSize
184       HTML::FormFu::Constraint::File::MinSize
185       HTML::FormFu::Constraint::File::Size
186       HTML::FormFu::Constraint::Integer
187       HTML::FormFu::Constraint::JSON
188       HTML::FormFu::Constraint::Length
189       HTML::FormFu::Constraint::MaxLength
190       HTML::FormFu::Constraint::MaxRange
191       HTML::FormFu::Constraint::MinLength
192       HTML::FormFu::Constraint::MinRange
193       HTML::FormFu::Constraint::MinMaxFields
194       HTML::FormFu::Constraint::Number
195       HTML::FormFu::Constraint::Printable
196       HTML::FormFu::Constraint::Range
197       HTML::FormFu::Constraint::Regex
198       HTML::FormFu::Constraint::Required
199       HTML::FormFu::Constraint::Set
200       HTML::FormFu::Constraint::SingleValue
201       HTML::FormFu::Constraint::Word
202

NON-CORE CONSTRAINTS AVAILABLE ON CPAN

204       HTML::FormFu::Constraint::reCAPTCHA
205

CAVEATS

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

AUTHOR

212       Carl Franks, "cfranks@cpan.org"
213
214       Based on the original source code of HTML::Widget::Constraint, by
215       Sebastian Riedel, "sri@oook.de".
216

LICENSE

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

AUTHOR

222       Carl Franks <cpan@fireartist.com>
223

COPYRIGHT AND LICENSE

225       This software is copyright (c) 2018 by Carl Franks.
226
227       This is free software; you can redistribute it and/or modify it under
228       the same terms as the Perl 5 programming language system itself.
229
230
231
232perl v5.36.0                      2023-01-20       HTML::FormFu::Constraint(3)