1HTML::FormHandler::FielUds(e3r)Contributed Perl DocumentHaTtMiLo:n:FormHandler::Field(3)
2
3
4

NAME

6       HTML::FormHandler::Field - base class for fields
7

VERSION

9       version 0.40068
10

SYNOPSIS

12       Instances of Field subclasses are generally built by HTML::FormHandler
13       from 'has_field' declarations or the field_list, but they can also be
14       constructed using new for test purposes (since there's no standard way
15       to add a field to a form after construction).
16
17           use HTML::FormHandler::Field::Text;
18           my $field = HTML::FormHandler::Field::Text->new( name => $name, ... );
19
20       In your custom field class:
21
22           package MyApp::Field::MyText;
23           use HTML::FormHandler::Moose;
24           extends 'HTML::FormHandler::Field::Text';
25
26           has 'my_attribute' => ( isa => 'Str', is => 'rw' );
27
28           apply [ { transform => sub { ... } },
29                   { check => ['fighter', 'bard', 'mage' ], message => '....' }
30                 ];
31           1;
32

DESCRIPTION

34       This is the base class for form fields. The 'type' of a field class is
35       used in the FormHandler field_list or has_field to identify which field
36       class to load from the 'field_name_space' (or directly, when prefixed
37       with '+').  If the type is not specified, it defaults to Text.
38
39       See HTML::FormHandler::Manual::Fields for a list of the fields and
40       brief descriptions of their structure.
41

ATTRIBUTES

43   Names, types, accessor
44       name
45           The name of the field. Used in the HTML form. Often a db accessor.
46           The only required attribute.
47
48       type
49           The class or type of the field. The 'type' of
50           HTML::FormHandler::Field::Money is 'Money'. Classes that you define
51           yourself are prefixed with '+'.
52
53       accessor
54           If the name of your field is different than your database accessor,
55           use this attribute to provide the accessor.
56
57       full_name
58           The name of the field with all parents:
59
60              'event.start_date.month'
61
62       full_accessor
63           The field accessor with all parents.
64
65       html_name
66           The full_name plus the form name if 'html_prefix' is set.
67
68       input_param
69           By default we expect an input parameter based on the field name.
70           This allows you to look for a different input parameter.
71
72   Field data
73       inactive, is_inactive, is_active
74           Set the 'inactive' attribute to 1 if this field is inactive. The
75           'inactive' attribute that isn't set or is set to 0 will make a
76           field 'active'.  This provides a way to define fields in the form
77           and selectively set them to inactive.  There is also an '_active'
78           attribute, for internal use to indicate that the field has been
79           activated/inactivated on 'process' by the form's
80           'active'/'inactive' attributes.
81
82           You can use the is_inactive and is_active methods to check whether
83           this particular field is active.
84
85              if( $form->field('foo')->is_active ) { ... }
86
87       input
88           The input string from the parameters passed in.
89
90       value
91           The value as it would come from or go into the database, after
92           being acted on by inflations/deflations and transforms. Used to
93           construct the "$form->values" hash. Validation and constraints act
94           on 'value'.
95
96           See also HTML::FormHandler::Manual::InflationDeflation.
97
98       fif Values used to fill in the form. Read only. Use a deflation to get
99           from 'value' to 'fif' if an inflator was used. Use 'fif_from_value'
100           attribute if you want to use the field 'value' to fill in the form.
101
102              [% form.field('title').fif %]
103
104       init_value
105           Initial value populated by init_from_object. You can tell if a
106           field has changed by comparing 'init_value' and 'value'. Read only.
107
108       input_without_param
109           Input for this field if there is no param. Set by default for
110           Checkbox, and Select, since an unchecked checkbox or unselected
111           pulldown does not return a parameter.
112
113   Form, parent
114       form
115           A reference to the containing form.
116
117       parent
118           A reference to the parent of this field. Compound fields are the
119           parents for the fields they contain.
120
121   Errors
122       errors
123           Returns the error list for the field. Also provides 'num_errors',
124           'has_errors', 'push_errors' and 'clear_errors' from Array trait.
125           Use 'add_error' to add an error to the array if you want to use a
126           MakeText language handle. Default is an empty list.
127
128       add_error
129           Add an error to the list of errors. Error message will be localized
130           using '_localize' method.  See also
131           HTML::FormHandler::TraitFor::I18N.
132
133               return $field->add_error( 'bad data' ) if $bad;
134
135       error_fields
136           Compound fields will have an array of errors from the subfields.
137
138       localize_meth
139           Set the method used to localize.
140
141   Attributes for creating HTML
142       The 'element_attr' hashref attribute can be used to set arbitrary HTML
143       attributes on a field's input tag.
144
145          has_field 'foo' => ( element_attr => { readonly => 1, my_attr => 'abc' } );
146
147       Note that the 'id' and 'type' attributes are not set using
148       element_attr. Use the field's 'id' attribute (or 'build_id_method') to
149       set the id.
150
151       The 'label_attr' hashref is for label attributes, and the
152       'wrapper_attr' is for attributes on the wrapping element (a 'div' for
153       the standard 'simple' wrapper).
154
155       A 'javascript' key in one of the '_attr' hashes will be inserted into
156       the element as-is.
157
158       The following are used in rendering HTML, but are handled specially.
159
160          label       - Text label for this field. Defaults to ucfirst field name.
161          build_label_method - coderef for constructing the label
162          wrap_label_method - coderef for constructing a wrapped label
163          id          - Useful for javascript (default is html_name. to prefix with
164                        form name, use 'html_prefix' in your form)
165          build_id_method - coderef for constructing the id
166          render_filter - Coderef for filtering fields before rendering. By default
167                        changes >, <, &, " to the html entities
168          disabled    - Boolean to set field disabled
169
170       The order attribute may be used to set the order in which fields are
171       rendered.
172
173          order       - Used for sorting errors and fields. Built automatically,
174                        but may also be explicitly set
175
176       The following are discouraged. Use 'element_attr', 'label_attr', and
177       'wrapper_attr' instead.
178
179          title       - instead use element_attr => { title => '...' }
180          style       - instead use element_attr => { style => '...' }
181          tabindex    - instead use element_attr => { tabindex => 1 }
182          readonly    - instead use element_attr => { readonly => 'readonly' }
183
184       Rendering of the various HTML attributes is done by calling the
185       'process_attrs' function (from HTML::FormHandler::Render::Util) and
186       passing in a method that adds in error classes, provides backward
187       compatibility with the deprecated attributes, etc.
188
189           attribute hashref  class attribute        wrapping method
190           =================  =================      ================
191           element_attr       element_class          element_attributes
192           label_attr         label_class            label_attributes
193           wrapper_attr       wrapper_class          wrapper_attributes
194                              element_wrapper_class  element_wrapper_attributes
195
196       ('element_wrapper' is for an inner div around the input element, not
197       including the label. Used for Bootstrap3 rendering, but also available
198       in the Simple wrapper.)  The slots for the class attributes are
199       arrayrefs; they will coerce a string into an arrayref.  In addition,
200       these 'wrapping methods' call a hook method in the form class,
201       'html_attributes', which you can use to customize and localize the
202       various attributes. (Field types: 'element', 'wrapper', 'label')
203
204          sub html_attributes {
205              my ( $self, $field, $type, $attr ) = @_;
206              $attr->{class} = 'label' if $type eq 'label';
207              return $attr;
208          }
209
210       The 'process_attrs' function will also handle an array of strings, such
211       as for the 'class' attribute.
212
213   tags
214       A hashref containing flags and strings for use in the rendering code.
215       The value of a tag can be a string, a coderef (accessed as a method on
216       the field) or a block specified with a percent followed by the
217       blockname ('%blockname').
218
219       Retrieve a tag with 'get_tag'. It returns a '' if the tag doesn't
220       exist.
221
222       This attribute used to be named 'widget_tags', which is deprecated.
223
224   html5_type_attr [string]
225       This string is used when rendering an input element as the value for
226       the type attribute.  It is used when the form has the is_html5 flag on.
227
228   widget
229       The 'widget' attribute is used in rendering, so if you are not using
230       FormHandler's rendering facility, you don't need this attribute.  It is
231       used in generating HTML, in templates and the rendering roles. Fields
232       of different type can use the same widget.
233
234       This attribute is set in the field classes, or in the fields defined in
235       the form. If you want a new widget type, create a widget role, such as
236       MyApp::Form::Widget::Field::MyWidget. Provide the name space in the
237       'widget_name_space' attribute, and set the 'widget' of your field to
238       the package name after the Field/Form/Wrapper:
239
240          has_field 'my_field' => ( widget => 'MyWidget' );
241
242       If you are using a template based rendering system you will want to
243       create a widget template.  (see HTML::FormHandler::Manual::Templates)
244
245       Widget types for some of the provided field classes:
246
247           Widget                 : Field classes
248           -----------------------:---------------------------------
249           Text                   : Text, Integer
250           Checkbox               : Checkbox, Boolean
251           RadioGroup             : Select, Multiple, IntRange (etc)
252           Select                 : Select, Multiple, IntRange (etc)
253           CheckboxGroup          : Multiple select
254           TextArea               : TextArea
255           Compound               : Compound, Repeatable, DateTime
256           Password               : Password
257           Hidden                 : Hidden
258           Submit                 : Submit
259           Reset                  : Reset
260           NoRender               :
261           Upload                 : Upload
262
263       Widget roles are automatically applied to field classes unless they
264       already have a 'render' method, and if the 'no_widgets' flag in the
265       form is not set.
266
267       You can create your own widget roles and specify the namespace in
268       'widget_name_space'. In the form:
269
270           has '+widget_name_space' => ( default => sub { ['MyApp::Widget'] } );
271
272       If you want to use a fully specified role name for a widget, you can
273       prefix it with a '+':
274
275          widget => '+MyApp::Widget::SomeWidget'
276
277       For more about widgets, see HTML::FormHandler::Manual::Rendering.
278
279   Flags
280          password  - prevents the entered value from being displayed in the form
281          writeonly - The initial value is not taken from the database
282          noupdate  - Do not update this field in the database (does not appear in $form->value)
283
284   Defaults
285       See also the documentation on "Defaults" in
286       HTML::FormHandler::Manual::Intro.
287
288       default_method, set_default
289           Supply a coderef (which will be a method on the field) with
290           'default_method' or the name of a form method with 'set_default'
291           (which will be a method on the form). If not specified and a form
292           method with a name of "default_<field_name>" exists, it will be
293           used.
294
295       default
296           Provide an initial value just like the 'set_default' method, except
297           in the field declaration:
298
299             has_field 'bax' => ( default => 'Default bax' );
300
301           FormHandler has flipped back and forth a couple of times about
302           whether a default specified in the has_field definition should
303           override values provided in an initial item or init_object.
304           Sometimes people want one behavior, and sometimes the other. Now
305           'default' does *not* override.
306
307           If you pass in a model object with "item => $row" or an initial
308           object with "init_object => {....}" the values in that object will
309           be used instead of values provided in the field definition with
310           'default' or 'default_fieldname'.  If you want defaults that
311           override or supplement the item/init_object, you can use the form
312           flags 'use_defaults_over_obj', 'use_init_obj_over_item', and
313           'use_init_obj_when_no_accessor_in_item'.
314
315           You could also put your defaults into your row or init_object
316           instead.
317
318       default_over_obj
319           This is deprecated; look into using 'use_defaults_over_obj' or
320           'use_init_obj_over_item' flags instead. They allow using the
321           standard 'default' attribute.
322
323           Allows setting defaults which will override values provided with an
324           item/init_object.  (And only those. Will not be used for defaults
325           without an item/init_object.)
326
327              has_field 'quux' => ( default_over_obj => 'default quux' );
328
329           At this time there is no equivalent of 'set_default', but the type
330           of the attribute is not defined so you can provide default values
331           in a variety of other ways, including providing a trait which does
332           'build_default_over_obj'. For examples, see tests in the
333           distribution.
334

Constraints and Validations

336       See also HTML::FormHandler::Manual::Validation.
337
338   Constraints set in attributes
339       required
340           Flag indicating whether this field must have a value
341
342       unique
343           For DB field - check for uniqueness. Action is performed by the DB
344           model.
345
346       messages
347               messages => { required => '...', unique => '...' }
348
349           Set messages created by FormHandler by setting in the 'messages'
350           hashref. Some field subclasses have additional settable messages.
351
352           required:  Error message text added to errors if required field is
353           not present.  The default is "Field <field label> is required".
354
355       range_start
356       range_end
357           Field values are validated against the specified range if one or
358           both of range_start and range_end are set and the field does not
359           have 'options'.
360
361           The IntRange field uses this range to create a select list with a
362           range of integers.
363
364           In a FormHandler field_list:
365
366               age => {
367                   type            => 'Integer',
368                   range_start     => 18,
369                   range_end       => 120,
370               }
371
372       not_nullable
373           Fields that contain 'empty' values such as '' are changed to undef
374           in the validation process.  If this flag is set, the value is not
375           changed to undef. If your database column requires an empty string
376           instead of a null value (such as a NOT NULL column), set this
377           attribute.
378
379               has_field 'description' => (
380                   type => 'TextArea',
381                   not_nullable => 1,
382               );
383
384           This attribute is also used when you want an empty array to stay an
385           empty array and not be set to undef.
386
387           It's also used when you have a compound field and you want the
388           'value' returned to contain subfields with undef, instead of the
389           whole field to be undef.
390
391   apply
392       Use the 'apply' keyword to specify an ArrayRef of constraints and
393       coercions to be executed on the field at validate_field time.
394
395          has_field 'test' => (
396             apply => [ 'MooseType',
397                        { check => sub {...}, message => { } },
398                        { transform => sub { ... lc(shift) ... } }
399                      ],
400          );
401
402       See more documentation in HTML::FormHandler::Manual::Validation.
403
404   trim
405       An action to trim the field. By default this contains a transform to
406       strip beginning and trailing spaces.  Set this attribute to null to
407       skip trimming, or supply a different transform.
408
409         trim => { transform => sub {
410             my $string = shift;
411             $string =~ s/^\s+//;
412             $string =~ s/\s+$//;
413             return $string;
414         } }
415         trim => { type => MyTypeConstraint }
416
417       Trimming is performed before any other defined actions.
418
419   Inflation/deflation
420       There are a number of methods to provide finely tuned inflation and
421       deflation:
422
423       inflate_method
424           Inflate to a data format desired for validation.
425
426       deflate_method
427           Deflate to a string format for presenting in HTML.
428
429       inflate_default_method
430           Modify the 'default' provided by an 'item' or 'init_object'.
431
432       deflate_value_method
433           Modify the value returned by "$form->value".
434
435       deflation
436           Another way of providing a deflation method.
437
438       transform
439           Another way of providing an inflation method.
440
441       Normally if you have a deflation, you will need a matching inflation.
442       There are two different flavors of inflation/deflation: one for
443       inflating values to a format needed for validation and deflating for
444       output, the other for inflating the initial provided values (usually
445       from a database row) and deflating them for the 'values' returned.
446
447       See HTML::FormHandler::Manual::InflationDeflation.
448

Processing and validating the field

450   validate_field
451       This is the base class validation routine. Most users will not do
452       anything with this. It might be useful for method modifiers, if you
453       want code that executed before or after the validation process.
454
455   validate
456       This field method can be used in addition to or instead of 'apply'
457       actions in custom field classes.  It should validate the field data and
458       set error messages on errors with "$field->add_error".
459
460           sub validate {
461               my $field = shift;
462               my $value = $field->value;
463               return $field->add_error( ... ) if ( ... );
464           }
465
466   validate_method, set_validate
467       Supply a coderef (which will be a method on the field) with
468       'validate_method' or the name of a form method with 'set_validate'
469       (which will be a method on the form). If not specified and a form
470       method with a name of "validate_<field_name>" exists, it will be used.
471
472       Periods in field names will be replaced by underscores, so that the
473       field 'addresses.city' will use the 'validate_addresses_city' method
474       for validation.
475
476          has_field 'my_foo' => ( validate_method => \&my_foo_validation );
477          sub my_foo_validation { ... }
478          has_field 'title' => ( isa => 'Str', set_validate => 'check_title' );
479

AUTHOR

481       FormHandler Contributors - see HTML::FormHandler
482
484       This software is copyright (c) 2017 by Gerda Shank.
485
486       This is free software; you can redistribute it and/or modify it under
487       the same terms as the Perl 5 programming language system itself.
488
489
490
491perl v5.32.1                      2021-01-27       HTML::FormHandler::Field(3)
Impressum