1HTML::FormHandler::ManuUasle:r:FCioenltdrsi(b3u)ted PerlHTDMoLc:u:mFeonrtmaHtainodnler::Manual::Fields(3)
2
3
4

NAME

6       HTML::FormHandler::Manual::Fields - brief documentation of available
7       fields
8

VERSION

10       version 0.40068
11

SYNOPSIS

13       Manual Index
14
15       See also HTML::FormHandler::Field for a description of the base field
16       attributes.
17
18       The inheritance hierarchy of HTML::FormHandler Fields
19
20          Text
21             Money
22             Password
23             Hidden
24             Integer
25                PosInteger
26             Float
27             Date
28                DateMDY
29             Email
30             TextCSV
31          TextArea
32          Select
33             Multiple
34             SelectCSV
35             BoolSelect
36             IntRange
37                Hour
38                Minute
39                MonthDay
40                Month
41                Second
42                Year
43             MonthName
44             Weekday
45          Checkbox
46             Boolean
47          Compound
48             Repeatable
49             Duration
50             DateTime
51          NoValue
52             Submit
53             Reset
54             Button
55             Display
56             AddElement
57             RmElement
58             NonEditable
59          PrimaryKey
60          Upload
61          File
62

DESCRIPTION

64       A form's fields are created from the 'has_field' and 'field_list'
65       definitions.  FormHandler processes the field lists and creates an
66       array of HTML::FormHandler::Field objects. The "type" of a field
67       determines which field class to use. The field class determines which
68       attributes are valid for a particular field. A number of field classes
69       are provided by FormHandler. You can customize the validation in your
70       form on a per field basis, but validation that will be used for more
71       than one field might be more easily handled in a custom field class.
72
73       Fields are accessed with "form->field('name')".  Field errors are in
74       "$field->errors".
75
76       If the 'field_name_space' is not set, fields will be loaded from the
77       HTML::FormHandler::Field name space. If you provide a
78       'field_name_space' it will be searched before FormHandler. If you want
79       to explicitly list the field's package, prefix it with a plus sign. The
80       field_name_space plus the default name spaces
81       'HTML::FormHandler::Field' and 'HTML::FormHandlerX::Field' will be
82       searched for fields.
83
84           has '+field_name_space' => ( default => 'MyApp::Form::Field' );
85           has_field 'name' => ( type => 'Text' ); # HTML::FormHandler::Field::Text
86           has_field 'name' => ( type => '+My::FieldType' ); # My::Fieldtype
87           has_field 'foo'  => ( type => '+Foo' );  # MyApp::Form::Field::Foo
88             or
89           has_field 'foo'  => ( type => 'Foo' );  # MyApp::Form::Field::Foo
90
91       The most basic type is "Text", which is usually a 'text' HTML element
92       and a string data type. (If the type of a field is not specified, it
93       will be set to 'Text'.)  A "Select" field type is a HTML select
94       element, and validates against the list of values provided in the
95       'options'. A "Multiple" type is like "Select" but it allows selecting
96       more than one value at a time.
97
98       Many field classes contain only a list of constraints and
99       transformations to apply. Some use the 'validate' method, which is
100       called after the actions are applied. Some build a custom select list
101       using 'build_options'.
102
103       There are two rough categories of Field classes: those that do extra
104       processing and those that are simple validators. The 'Compound',
105       'Repeatable', and 'Select' fields are fields that are functional.
106

Field names

108       The standard way to use FormHandler is with field names that match your
109       database accessors. If you want to prepend the HTML field names with a
110       name plus dot, you can set the form 'name' and use the 'html_prefix'
111       flag. "$name." will be stripped from the beginning of the HTML fields
112       before processing by HFH, and will be added back in 'fif'. The field's
113       'html_name' convenience attribute will return this name for use in
114       templates.
115
116       If you want the FormHandler field name to be different than the
117       database accessor, set 'accessor' on your fields. (It defaults to the
118       field name.) You could then use any name that you want for your field.
119
120       There are a number of name-related field attributes. The 'name' is the
121       name used to identify this particular field in this fields array.  The
122       'full_name' includes the names of all parents of this field, like
123       'address.street.streetname'. The 'html_name' is the same as the
124       'full_name' unless you have set the 'html_prefix' flag, in which case
125       it includes the form name: 'myform.address.street.streetname'.
126
127       To retrieve a field by name, you can use either the full_name or a
128       chain: "$form->field('address')->field('street')->field('streetname')"
129       or: "$form->field('address.street.streetname')".
130

Creating custom fields

132       Subclass a custom field from HTML::FormHandler::Field, or one of the
133       existing subclasses. Almost everything that is done in a custom field
134       class can also be done in a form. The advantage of a field class is
135       that it can simplify declaration of often-repeated sets of attributes.
136
137       The simplest subclasses contain only a 'validate' routine or an 'apply'
138       attribute, which is called by the base Field class from 'process'. Look
139       at HTML::FormHandler::Field::Email, for example.
140
141       If the field's value will be an object instead of a simple scalar, such
142       as a DateTime, and you want to use the transformed value to fill in the
143       form, then you will also need a deflation or field class 'deflate'
144       method to reformat the object into a form suitable for an HTML form
145       field.  See HTML::FormHandler::Manual::InflationDeflation for more
146       info.
147
148       Some custom fields might only require setting certain attributes to
149       defaults, such as the HTML::FormHandler::Field::Hour field, which set
150       'range_start' to 0 and 'range_end' to 23. A 'select' field might
151       override the 'build_options' builder for the 'options' array, like
152       HTML::FormHandler::Field::IntRange. A field may add additional
153       attributes, such as 'label_format' in
154       HTML::FormHandler::Field::IntRange, or set the 'required' message.
155
156       An alternative to new field classes for many field validations might be
157       roles with collections of validations.
158

Other field packages

160       Some custom fields are supplied as CPAN packages, in the
161       HTML::FormHandlerX name space.
162
163       reCAPTCHA
164
165       DateTimeNatural
166
167       URI::HTTP
168

Fields supplied by FormHandler

170   Basic Fields
171       Although there are a lot of fields provided (probably too many) a lot
172       of them are "convenience" fields or "name" fields, where the main
173       benefit is that the field type is a name that gives the main purpose of
174       the field.  Most of these fields could be replaced by a basic field
175       with a bit of validation or some select options. A few of the fields
176       are special purpose fields that won't be used very often.
177
178       The fields in this section are the basic fields, the commonly used
179       fields that will be most often used in a form.
180
181       Text
182
183       A string data type that will be formatted as an HTML text field. Has
184       'minlength' and 'maxlength' attributes.
185
186       HTML::FormHandler::Field::Text
187
188       Select
189
190       A field formatted as a select element.
191
192       HTML::FormHandler::Field::Select
193
194       Checkbox
195
196       A field formatted as a checkbox. If not in params, will be forced to
197       'false' value by 'input_without_param' attribute (0 by default).
198
199       HTML::FormHandler::Field::Checkbox
200
201       Hidden
202
203       A hidden field.
204
205       HTML::FormHandler::Field::Hidden
206
207       Password
208
209       A password field. The value is not re-displayed.
210
211       HTML::FormHandler::Field::Password
212
213       TextArea
214
215       A textarea field.  Has 'cols' and 'rows' attributes.
216
217       HTML::FormHandler::Field::TextArea
218
219       Upload
220
221       A file upload field that takes a filehandle or a Catalyst upload object
222       (an object with a 'size' method).
223
224       HTML::FormHandler::Field::Upload
225
226       Submit
227
228       A submit field.
229
230       HTML::FormHandler::Field::Submit
231
232       Reset
233
234       A reset field.
235
236       HTML::FormHandler::Field::Reset
237
238   Complex Fields (Compound and Repeatable)
239       These fields are complex fields which contain a fair amount of special
240       code. They do not map to a single HTML element; they contain multiple
241       subfields.
242
243       Compound
244
245       A compound field is a field that has sub-fields. Compound fields can be
246       created in two ways: 1) using a field class, 2) by declaration.
247
248       To create a compound field class, you must extend
249       HTML::FormHandler::Field::Compound and use HTML::FormHandler::Moose to
250       allow declaring fields:
251
252         package MyApp::Field::Duration;
253
254         use HTML::FormHandler::Moose;
255         extends 'HTML::FormHandler::Field::Compound';
256
257         has_field 'month' => (type => 'Integer');
258         has_field 'day' => ( type => 'Integer' );
259         has_field 'minutes' => ( type => 'Integer' );
260
261       Then in the form:
262
263         has_field 'my_duration' => ( type => '+Duration' );
264
265       To create a compound field by declaration, declare the containing
266       compound field and subfields, prefixing the subfield names with the
267       name of the containing compound field plus a dot:
268
269          package MyApp::Form;
270
271          use HTML::FormHandler::Moose;
272          extends 'HTML::FormHandler';
273
274          has_field 'duration' => ( type => 'Compound' );
275          has_field 'duration.month' => ( type => 'Integer' );
276          has_field 'duration.day' => ( type => 'Integer' );
277          has_field 'duration.year' => ( type => 'Integer' );
278
279       In an HTML form the name of the field must be the complete name with
280       dots. The 'html_name' field attribute can be used to get this name,
281       "$field->html_name".
282
283       A compound field can be used for a database relation that will have
284       only one row (belongs_to or has_one). If the relation has a compound
285       primary key, you may need to provide the primary key columns, either
286       through hidden fields or by setting them in the "$form->value" hash
287       before 'update_model' is called.
288
289       See also HTML::FormHandler::Field::Compound.
290
291       Repeatable
292
293       Repeatable fields are used for arrays of compound fields.
294
295          has_field 'addresses' => ( type => 'Repeatable' );
296          has_field 'addresses.address_id' => ( type => 'PrimaryKey' );
297          has_field 'addresses.street';
298          has_field 'addresses.city';
299          has_field 'addresses.country' => ( type => 'Select' );
300
301       The arrays will be built from arrays passed in the params, or from
302       related ('has_many') rows in the database.
303
304       It is also used for arrays of single fields using the 'contains'
305       keyword:
306
307         has_field 'tags' => ( type => 'Repeatable' );
308         has_field 'tags.contains' => ( type => '+Tag' );
309
310       See HTML::FormHandler::Field::Repeatable for more information.
311
312   Text Fields
313       Fields subclassed from the Text field.
314
315       Text
316
317       Text field.
318
319       HTML::FormHandler::Field::Text
320
321       Money
322
323       Positive or negative real value, formatted to two decimal places.
324
325       HTML::FormHandler::Field::Money
326
327       Date
328
329       Date field that can be used by jQuery datepicker plugin.
330
331       HTML::FormHandler::Field::Date
332
333       DateMDY
334
335       A subclass of 'Date' with the "%m/%d/%Y" format.
336
337       HTML::FormHandler::Field::DateMDY
338
339       Email
340
341       Uses Email::Valid for validation.
342
343       HTML::FormHandler::Field::Email
344
345       Integer
346
347       Positive and negative integers. Can use range_start and range_end.
348
349       HTML::FormHandler::Field::Integer
350
351       PosInteger
352
353       A positive integer field.
354
355       HTML::FormHandler::Field::PosInteger
356
357       Float
358
359       Float field that allows you to set size, precision, decimal_symbol, and
360       decimal_symbol_for_db.
361
362       HTML::FormHandler::Field::Float
363
364       TextCSV
365
366       A text field that takes multiple values from a database and converts
367       them to comma-separated values. This is intended for javascript fields
368       that require that, such as 'select2'. This is the only 'multiple' text
369       field. This text field would be a select-type field for the user.
370
371       HTML::FormHandler::Field::TextCSV
372
373   Compound Fields
374       Fields subclassed from 'Compound'.
375
376       Compound
377
378       HTML::FormHandler::Field::Compound
379
380       Repeatable
381
382       HTML::FormHandler::Field::Repeatable
383
384       Duration
385
386       Compound field with possible subfields: years, months, weeks, days,
387       hours, minutes, seconds, nanoseconds.
388
389       HTML::FormHandler::Field::Duration
390
391       DateTime
392
393       A compound field that requires you to provide the subfields that you
394       want. (month/day/year/hour/minutes)
395
396       HTML::FormHandler::Field::DateTime
397
398   Checkbox Fields
399       Fields that inherit from 'Checkbox'.
400
401       Checkbox
402
403       HTML::FormHandler::Field::Checkbox
404
405       Boolean
406
407       Checkbox that return 1 or 0.
408
409       HTML::FormHandler::Field::Boolean
410
411   Select Fields
412       Fields that inherit from 'Select'.
413
414       Select
415
416       HTML::FormHandler::Field::Select
417
418       Multiple
419
420       Multiple select. Also sorts the selected options to the top of the
421       select list.
422
423       HTML::FormHandler::Field::Multiple
424
425   SelectCSV
426       A multiple select field for comma-separated values in the database.  It
427       expects database values like: '1,5,7'. The string will be inflated into
428       an arrayref for validation and form filling, and will be deflated into
429       a comma-separated string in the output value.
430
431       HTML::FormHandler::Field::SelectCSV
432
433       BoolSelect
434
435       A field with three possible values: empty/0/1.
436
437       HTML::FormHandler::Field::BoolSelect
438
439       Hour
440
441       Integer select range field from 0-23.
442
443       HTML::FormHandler::Field::Hour
444
445       Second
446
447       Select field with range from 0-59.
448
449       HTML::FormHandler::Field::Second
450
451       IntRange
452
453       An integer select field. Can set label format with 'label_format'.
454
455       HTML::FormHandler::Field::IntRange
456
457       Month
458
459       Select field with range from 1 - 12.
460
461       HTML::FormHandler::Field::Month
462
463       MonthDay
464
465       Select field with range from 1 - 31.
466
467       HTML::FormHandler::Field::MonthDay
468
469       MonthName
470
471       Select field with month name labels, value 1-12.
472
473       HTML::FormHandler::Field::MonthName
474
475       Minute
476
477       Select field with range from 0-59.
478
479       HTML::FormHandler::Field::Minute
480
481       Weekday
482
483       A select field where the labels are the names of the week, and the
484       values are 0-6.
485
486       HTML::FormHandler::Field::Weekday
487
488       Year
489
490       Select field providing year list 5 years back and 10 years forward.
491
492       HTML::FormHandler::Field::Year
493
494   NoValue fields
495       Fields that inherit from 'NoValue'. None of these fields will provide a
496       'value' in the "$form->value" hashref.
497
498       NoValue
499
500       Base class for fields that don't produce a 'value'.
501
502       HTML::FormHandler::Field::NoValue
503
504       Submit
505
506       HTML::FormHandler::Field::Submit
507
508       Reset
509
510       HTML::FormHandler::Field::Reset
511
512       Button
513
514       Button field that is rendered by the Button widget.
515
516       HTML::FormHandler::Field::Button
517
518       Display
519
520       Non-data field used for inserting HTML into the form. Probably now
521       better handled by a Block or a rendering tag.
522
523       HTML::FormHandler::Field::Display
524
525       AddElement
526
527       Example field for adding a repeatable element.
528
529       HTML::FormHandler::Field::AddElement
530
531       RmElement
532
533       Example field for removing a repeatable element
534
535       HTML::FormHandler::Field::RmElement
536
537       NonEditable
538
539       For Bootstrap-style non-editable fields.
540
541   TextArea fields
542       Fields that inherit from 'TextArea'.
543
544       TextArea
545
546       HTML::FormHandler::Field::TextArea
547
548   Password fields
549       Password
550
551       Password field. Sets 'noupdate' flag if empty and not required.
552
553       HTML::FormHandler::Field::Password
554
555       PasswordConf
556
557       Password confirmation field.
558
559       HTML::FormHandler::Field::PasswordConf
560
561   Other fields
562       These fields inherit just from 'Field'.
563
564       File
565
566       A file field that does no processing. Most people probably want to use
567       'Upload' instead.
568
569       HTML::FormHandler::Field::File
570
571       PrimaryKey
572
573       Hidden field that provides the primary key for Repeatable fields.
574
575       HTML::FormHandler::Field::PrimaryKey
576
577       Captcha
578
579       A Captcha field using GD::SecurityImage. Requires the use of the
580       HTML::FormHandler::TraitFor::Captcha role, or similar code.
581
582       HTML::FormHandler::Field::Captcha
583

AUTHOR

585       FormHandler Contributors - see HTML::FormHandler
586

588       This software is copyright (c) 2017 by Gerda Shank.
589
590       This is free software; you can redistribute it and/or modify it under
591       the same terms as the Perl 5 programming language system itself.
592
593
594
595perl v5.34.0                      2022-01-2H1TML::FormHandler::Manual::Fields(3)
Impressum