1HTML::FormHandler::FielUds(e3r)Contributed Perl DocumentHaTtMiLo:n:FormHandler::Field(3)
2
6 HTML::FormHandler::Field - base class for fields
7
9 version 0.40068
10
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 use HTML::FormHandler::Field::Text;
18 my $field = HTML::FormHandler::Field::Text->new( name => $name, ... );
19 In your custom field class:
21 package MyApp::Field::MyText;
23 use HTML::FormHandler::Moose;
24 extends 'HTML::FormHandler::Field::Text';
25 has 'my_attribute' => ( isa => 'Str', is => 'rw' );
27 apply [ { transform => sub { ... } },
29 { check => ['fighter', 'bard', 'mage' ], message => '....' }
30 ];
31 1;
32
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 See HTML::FormHandler::Manual::Fields for a list of the fields and
40 brief descriptions of their structure.
41
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 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 accessor
54 If the name of your field is different than your database accessor,
55 use this attribute to provide the accessor.
56 full_name
58 The name of the field with all parents:
59 'event.start_date.month'
61 full_accessor
63 The field accessor with all parents.
64 html_name
66 The full_name plus the form name if 'html_prefix' is set.
67 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 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 You can use the is_inactive and is_active methods to check whether
83 this particular field is active.
84 if( $form->field('foo')->is_active ) { ... }
86 input
88 The input string from the parameters passed in.
89 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 See also HTML::FormHandler::Manual::InflationDeflation.
97 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 [% form.field('title').fif %]
103 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 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 Form, parent
114 form
115 A reference to the containing form.
116 parent
118 A reference to the parent of this field. Compound fields are the
119 parents for the fields they contain.
120 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 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 return $field->add_error( 'bad data' ) if $bad;
134 error_fields
136 Compound fields will have an array of errors from the subfields.
137 localize_meth
139 Set the method used to localize.
140 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 has_field 'foo' => ( element_attr => { readonly => 1, my_attr => 'abc' } );
146 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 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 A 'javascript' key in one of the '_attr' hashes will be inserted into
156 the element as-is.
157 The following are used in rendering HTML, but are handled specially.
159 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 The order attribute may be used to set the order in which fields are
171 rendered.
172 order - Used for sorting errors and fields. Built automatically,
174 but may also be explicitly set
175 The following are discouraged. Use 'element_attr', 'label_attr', and
177 'wrapper_attr' instead.
178 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 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 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 ('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 sub html_attributes {
205 my ( $self, $field, $type, $attr ) = @_;
206 $attr->{class} = 'label' if $type eq 'label';
207 return $attr;
208 }
209 The 'process_attrs' function will also handle an array of strings, such
211 as for the 'class' attribute.
212 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 Retrieve a tag with 'get_tag'. It returns a '' if the tag doesn't
220 exist.
221 This attribute used to be named 'widget_tags', which is deprecated.
223 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 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 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 has_field 'my_field' => ( widget => 'MyWidget' );
241 If you are using a template based rendering system you will want to
243 create a widget template. (see HTML::FormHandler::Manual::Templates)
244 Widget types for some of the provided field classes:
246 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 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 You can create your own widget roles and specify the namespace in
268 'widget_name_space'. In the form:
269 has '+widget_name_space' => ( default => sub { ['MyApp::Widget'] } );
271 If you want to use a fully specified role name for a widget, you can
273 prefix it with a '+':
274 widget => '+MyApp::Widget::SomeWidget'
276 For more about widgets, see HTML::FormHandler::Manual::Rendering.
278 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 Defaults
285 See also the documentation on "Defaults" in
286 HTML::FormHandler::Manual::Intro.
287 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 default
296 Provide an initial value just like the 'set_default' method, except
297 in the field declaration:
298 has_field 'bax' => ( default => 'Default bax' );
300 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 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 You could also put your defaults into your row or init_object
316 instead.
317 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 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 has_field 'quux' => ( default_over_obj => 'default quux' );
328 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
336 See also HTML::FormHandler::Manual::Validation.
337 Constraints set in attributes
339 required
340 Flag indicating whether this field must have a value
341 unique
343 For DB field - check for uniqueness. Action is performed by the DB
344 model.
345 messages
347 messages => { required => '...', unique => '...' }
348 Set messages created by FormHandler by setting in the 'messages'
350 hashref. Some field subclasses have additional settable messages.
351 required: Error message text added to errors if required field is
353 not present. The default is "Field <field label> is required".
354 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 The IntRange field uses this range to create a select list with a
362 range of integers.
363 In a FormHandler field_list:
365 age => {
367 type => 'Integer',
368 range_start => 18,
369 range_end => 120,
370 }
371 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 has_field 'description' => (
380 type => 'TextArea',
381 not_nullable => 1,
382 );
383 This attribute is also used when you want an empty array to stay an
385 empty array and not be set to undef.
386 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 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 has_field 'test' => (
396 apply => [ 'MooseType',
397 { check => sub {...}, message => { } },
398 { transform => sub { ... lc(shift) ... } }
399 ],
400 );
401 See more documentation in HTML::FormHandler::Manual::Validation.
403 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 trim => { transform => sub {
410 my $string = shift;
411 $string =~ s/^\s+//;
412 $string =~ s/\s+$//;
413 return $string;
414 } }
415 trim => { type => MyTypeConstraint }
416 Trimming is performed before any other defined actions.
418 Inflation/deflation
420 There are a number of methods to provide finely tuned inflation and
421 deflation:
422 inflate_method
424 Inflate to a data format desired for validation.
425 deflate_method
427 Deflate to a string format for presenting in HTML.
428 inflate_default_method
430 Modify the 'default' provided by an 'item' or 'init_object'.
431 deflate_value_method
433 Modify the value returned by "$form->value".
434 deflation
436 Another way of providing a deflation method.
437 transform
439 Another way of providing an inflation method.
440 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 See HTML::FormHandler::Manual::InflationDeflation.
448
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 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 sub validate {
461 my $field = shift;
462 my $value = $field->value;
463 return $field->add_error( ... ) if ( ... );
464 }
465 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 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 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
481 FormHandler Contributors - see HTML::FormHandler
482
484 This software is copyright (c) 2017 by Gerda Shank.
485 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.
488perl v5.28.0 2017-07-20 HTML::FormHandler::Field(3)