1package HTML::FormHandler::Manual::Fields;
2# ABSTRACT: brief documentation of available fields
3
4__END__
5
6=pod
7
8=encoding UTF-8
9
10=head1 NAME
11
12HTML::FormHandler::Manual::Fields - brief documentation of available fields
13
14=head1 VERSION
15
16version 0.40068
17
18=head1 SYNOPSIS
19
20L<Manual Index|HTML::FormHandler::Manual>
21
22See also L<HTML::FormHandler::Field> for a description of the base
23field attributes.
24
25The inheritance hierarchy of HTML::FormHandler Fields
26
27   Text
28      Money
29      Password
30      Hidden
31      Integer
32         PosInteger
33      Float
34      Date
35         DateMDY
36      Email
37      TextCSV
38   TextArea
39   Select
40      Multiple
41      SelectCSV
42      BoolSelect
43      IntRange
44         Hour
45         Minute
46         MonthDay
47         Month
48         Second
49         Year
50      MonthName
51      Weekday
52   Checkbox
53      Boolean
54   Compound
55      Repeatable
56      Duration
57      DateTime
58   NoValue
59      Submit
60      Reset
61      Button
62      Display
63      AddElement
64      RmElement
65      NonEditable
66   PrimaryKey
67   Upload
68   File
69
70=head1 DESCRIPTION
71
72A form's fields are created from the 'has_field' and 'field_list' definitions.
73FormHandler processes the field lists and creates an array of
74L<HTML::FormHandler::Field> objects. The "type" of a field
75determines which field class to use. The field class determines which
76attributes are valid for a particular field. A number of field classes are
77provided by FormHandler. You can customize the validation in your form on a
78per field basis, but validation that will be used for more than one field
79might be more easily handled in a custom field class.
80
81Fields are accessed with C<< form->field('name') >>.
82Field errors are in C<< $field->errors >>.
83
84If the 'field_name_space' is not set, fields will be loaded from the
85HTML::FormHandler::Field name space. If you provide a 'field_name_space'
86it will be searched before FormHandler. If you want to explicitly list the
87field's package, prefix it with a plus sign. The field_name_space plus the
88default name spaces 'HTML::FormHandler::Field' and 'HTML::FormHandlerX::Field'
89will be searched for fields.
90
91    has '+field_name_space' => ( default => 'MyApp::Form::Field' );
92    has_field 'name' => ( type => 'Text' ); # HTML::FormHandler::Field::Text
93    has_field 'name' => ( type => '+My::FieldType' ); # My::Fieldtype
94    has_field 'foo'  => ( type => '+Foo' );  # MyApp::Form::Field::Foo
95      or
96    has_field 'foo'  => ( type => 'Foo' );  # MyApp::Form::Field::Foo
97
98The most basic type is "Text", which is usually a 'text' HTML element and
99a string data type. (If the type of a field is not specified, it will be set to
100'Text'.)  A "Select" field type is a HTML select element, and validates against
101the list of values provided in the 'options'. A "Multiple" type is like "Select"
102but it allows selecting more than one value at a time.
103
104Many field classes contain only a list of constraints and transformations
105to apply. Some use the 'validate' method, which is called after the actions
106are applied. Some build a custom select list using 'build_options'.
107
108There are two rough categories of Field classes: those that do extra processing
109and those that are simple validators. The 'Compound', 'Repeatable', and
110'Select' fields are fields that are functional.
111
112=head1 Field names
113
114The standard way to use FormHandler is with field names that match your
115database accessors. If you want to prepend the HTML field names with a
116name plus dot, you can set the form 'name' and use the 'html_prefix'
117flag. "$name." will be stripped from the beginning of the HTML fields
118before processing by HFH, and will be added back in 'fif'. The field's
119'html_name' convenience attribute will return this name for use in templates.
120
121If you want the FormHandler field name to be different than the
122database accessor, set 'accessor' on your fields. (It defaults to the field
123name.) You could then use any name that you want for your field.
124
125There are a number of name-related field attributes. The 'name' is
126the name used to identify this particular field in this fields array.
127The 'full_name' includes the names of all parents of this field,
128like 'address.street.streetname'. The 'html_name' is the same as the
129'full_name' unless you have set the 'html_prefix' flag, in which case
130it includes the form name: 'myform.address.street.streetname'.
131
132To retrieve a field by name, you can use either the full_name or a
133chain: C<< $form->field('address')->field('street')->field('streetname') >>
134or: C<< $form->field('address.street.streetname') >>.
135
136=head1 Creating custom fields
137
138Subclass a custom field from L<HTML::FormHandler::Field>, or one of the
139existing subclasses. Almost everything that is done in a custom field
140class can also be done in a form. The advantage of a field class
141is that it can simplify declaration of often-repeated sets of attributes.
142
143The simplest subclasses contain only a 'validate' routine or an 'apply' attribute,
144which is called by the base Field class from 'process'. Look at
145L<HTML::FormHandler::Field::Email>, for example.
146
147If the field's value will be an object instead of a simple scalar, such
148as a DateTime, and you want to use the transformed value to fill in the
149form, then you will also need a deflation or field class 'deflate' method
150to reformat the object into a form suitable for an HTML form field.
151See L<HTML::FormHandler::Manual::InflationDeflation> for more info.
152
153Some custom fields might only require setting certain attributes to
154defaults, such as the L<HTML::FormHandler::Field::Hour> field, which
155set 'range_start' to 0 and 'range_end' to 23. A 'select' field might
156override the 'build_options' builder for the 'options' array, like
157L<HTML::FormHandler::Field::IntRange>. A field may add additional
158attributes, such as 'label_format' in L<HTML::FormHandler::Field::IntRange>,
159or set the 'required' message.
160
161An alternative to new field classes for many field validations might
162be roles with collections of validations.
163
164=head1 Other field packages
165
166Some custom fields are supplied as CPAN packages, in the HTML::FormHandlerX
167name space.
168
169L<reCAPTCHA|HTML::FormHandlerX::Field::reCAPTCHA>
170
171L<DateTimeNatural|HTML::FormHandlerX::Field::DateTimeNatural>
172
173L<URI::HTTP|HTML::FormHandlerX::Field::URI::HTTP>
174
175=head1 Fields supplied by FormHandler
176
177=head2 Basic Fields
178
179Although there are a lot of fields provided (probably too many) a lot of them
180are "convenience" fields or "name" fields, where the main benefit is
181that the field type is a name that gives the main purpose of the field.
182Most of these fields could be replaced by a basic field with a bit of validation
183or some select options. A few of the fields are special purpose fields
184that won't be used very often.
185
186The fields in this section are the basic fields, the commonly used fields
187that will be most often used in a form.
188
189=head3 Text
190
191A string data type that will be formatted as an HTML text field. Has 'minlength'
192and 'maxlength' attributes.
193
194L<HTML::FormHandler::Field::Text>
195
196=head3 Select
197
198A field formatted as a select element.
199
200L<HTML::FormHandler::Field::Select>
201
202=head3 Checkbox
203
204A field formatted as a checkbox. If not in params, will be forced to
205'false' value by 'input_without_param' attribute (0 by default).
206
207L<HTML::FormHandler::Field::Checkbox>
208
209=head3 Hidden
210
211A hidden field.
212
213L<HTML::FormHandler::Field::Hidden>
214
215=head3 Password
216
217A password field. The value is not re-displayed.
218
219L<HTML::FormHandler::Field::Password>
220
221=head3 TextArea
222
223A textarea field.  Has 'cols' and 'rows' attributes.
224
225L<HTML::FormHandler::Field::TextArea>
226
227=head3 Upload
228
229A file upload field that takes a filehandle or a Catalyst upload object (an
230object with a 'size' method).
231
232L<HTML::FormHandler::Field::Upload>
233
234=head3 Submit
235
236A submit field.
237
238L<HTML::FormHandler::Field::Submit>
239
240=head3 Reset
241
242A reset field.
243
244L<HTML::FormHandler::Field::Reset>
245
246=head2 Complex Fields (Compound and Repeatable)
247
248These fields are complex fields which contain a fair amount of
249special code. They do not map to a single HTML element; they contain
250multiple subfields.
251
252=head3 Compound
253
254A compound field is a field that has sub-fields. Compound fields can be
255created in two ways: 1) using a field class, 2) by declaration.
256
257To create a compound field class, you must extend
258L<HTML::FormHandler::Field::Compound> and use L<HTML::FormHandler::Moose> to
259allow declaring fields:
260
261  package MyApp::Field::Duration;
262
263  use HTML::FormHandler::Moose;
264  extends 'HTML::FormHandler::Field::Compound';
265
266  has_field 'month' => (type => 'Integer');
267  has_field 'day' => ( type => 'Integer' );
268  has_field 'minutes' => ( type => 'Integer' );
269
270Then in the form:
271
272  has_field 'my_duration' => ( type => '+Duration' );
273
274To create a compound field by declaration, declare the containing
275compound field and subfields, prefixing the subfield names
276with the name of the containing compound field plus a dot:
277
278   package MyApp::Form;
279
280   use HTML::FormHandler::Moose;
281   extends 'HTML::FormHandler';
282
283   has_field 'duration' => ( type => 'Compound' );
284   has_field 'duration.month' => ( type => 'Integer' );
285   has_field 'duration.day' => ( type => 'Integer' );
286   has_field 'duration.year' => ( type => 'Integer' );
287
288In an HTML form the name of the field must be the complete name
289with dots. The 'html_name' field attribute can be used to get
290this name, C<< $field->html_name >>.
291
292A compound field can be used for a database relation that will have only
293one row (belongs_to or has_one). If the relation has a compound primary
294key, you may need to provide the primary key columns, either through
295hidden fields or by setting them in the C<< $form->value >> hash before
296'update_model' is called.
297
298See also L<HTML::FormHandler::Field::Compound>.
299
300=head3 Repeatable
301
302Repeatable fields are used for arrays of compound fields.
303
304   has_field 'addresses' => ( type => 'Repeatable' );
305   has_field 'addresses.address_id' => ( type => 'PrimaryKey' );
306   has_field 'addresses.street';
307   has_field 'addresses.city';
308   has_field 'addresses.country' => ( type => 'Select' );
309
310The arrays will be built from arrays passed in the params, or from
311related ('has_many') rows in the database.
312
313It is also used for arrays of single fields using the 'contains' keyword:
314
315  has_field 'tags' => ( type => 'Repeatable' );
316  has_field 'tags.contains' => ( type => '+Tag' );
317
318See L<HTML::FormHandler::Field::Repeatable> for more information.
319
320=head2 Text Fields
321
322Fields subclassed from the Text field.
323
324=head3 Text
325
326Text field.
327
328L<HTML::FormHandler::Field::Text>
329
330=head3 Money
331
332Positive or negative real value, formatted to two decimal places.
333
334L<HTML::FormHandler::Field::Money>
335
336=head3 Date
337
338Date field that can be used by jQuery datepicker plugin.
339
340L<HTML::FormHandler::Field::Date>
341
342=head3 DateMDY
343
344A subclass of 'Date' with the "%m/%d/%Y" format.
345
346L<HTML::FormHandler::Field::DateMDY>
347
348=head3 Email
349
350Uses Email::Valid for validation.
351
352L<HTML::FormHandler::Field::Email>
353
354=head3 Integer
355
356Positive and negative integers. Can use range_start and range_end.
357
358L<HTML::FormHandler::Field::Integer>
359
360=head3 PosInteger
361
362A positive integer field.
363
364L<HTML::FormHandler::Field::PosInteger>
365
366=head3 Float
367
368Float field that allows you to set size, precision, decimal_symbol, and
369decimal_symbol_for_db.
370
371L<HTML::FormHandler::Field::Float>
372
373=head3 TextCSV
374
375A text field that takes multiple values from a database and converts
376them to comma-separated values. This is intended for javascript fields
377that require that, such as 'select2'. This is the only 'multiple' text
378field. This text field would be a select-type field for the user.
379
380L<HTML::FormHandler::Field::TextCSV>
381
382=head2 Compound Fields
383
384Fields subclassed from 'Compound'.
385
386=head3 Compound
387
388L<HTML::FormHandler::Field::Compound>
389
390=head3 Repeatable
391
392L<HTML::FormHandler::Field::Repeatable>
393
394=head3 Duration
395
396Compound field with possible subfields: years, months, weeks, days, hours,
397minutes, seconds, nanoseconds.
398
399L<HTML::FormHandler::Field::Duration>
400
401=head3 DateTime
402
403A compound field that requires you to provide the subfields that
404you want. (month/day/year/hour/minutes)
405
406L<HTML::FormHandler::Field::DateTime>
407
408=head2 Checkbox Fields
409
410Fields that inherit from 'Checkbox'.
411
412=head3 Checkbox
413
414L<HTML::FormHandler::Field::Checkbox>
415
416=head3 Boolean
417
418Checkbox that return 1 or 0.
419
420L<HTML::FormHandler::Field::Boolean>
421
422=head2 Select Fields
423
424Fields that inherit from 'Select'.
425
426=head3 Select
427
428L<HTML::FormHandler::Field::Select>
429
430=head3 Multiple
431
432Multiple select. Also sorts the selected options to the top of
433the select list.
434
435L<HTML::FormHandler::Field::Multiple>
436
437=head2 SelectCSV
438
439A multiple select field for comma-separated values in the database.
440It expects database values like: '1,5,7'. The string will be inflated
441into an arrayref for validation and form filling, and will be deflated
442into a comma-separated string in the output value.
443
444L<HTML::FormHandler::Field::SelectCSV>
445
446=head3 BoolSelect
447
448A field with three possible values: empty/0/1.
449
450L<HTML::FormHandler::Field::BoolSelect>
451
452=head3 Hour
453
454Integer select range field from 0-23.
455
456L<HTML::FormHandler::Field::Hour>
457
458=head3 Second
459
460Select field with range from 0-59.
461
462L<HTML::FormHandler::Field::Second>
463
464=head3 IntRange
465
466An integer select field. Can set label format with 'label_format'.
467
468L<HTML::FormHandler::Field::IntRange>
469
470=head3 Month
471
472Select field with range from 1 - 12.
473
474L<HTML::FormHandler::Field::Month>
475
476=head3 MonthDay
477
478Select field with range from 1 - 31.
479
480L<HTML::FormHandler::Field::MonthDay>
481
482=head3 MonthName
483
484Select field with month name labels, value 1-12.
485
486L<HTML::FormHandler::Field::MonthName>
487
488=head3 Minute
489
490Select field with range from 0-59.
491
492L<HTML::FormHandler::Field::Minute>
493
494=head3 Weekday
495
496A select field where the labels are the names of the week, and the
497values are 0-6.
498
499L<HTML::FormHandler::Field::Weekday>
500
501=head3 Year
502
503Select field providing year list 5 years back and 10 years forward.
504
505L<HTML::FormHandler::Field::Year>
506
507=head2 NoValue fields
508
509Fields that inherit from 'NoValue'. None of these fields will
510provide a 'value' in the C<< $form->value >> hashref.
511
512=head3 NoValue
513
514Base class for fields that don't produce a 'value'.
515
516L<HTML::FormHandler::Field::NoValue>
517
518=head3 Submit
519
520L<HTML::FormHandler::Field::Submit>
521
522=head3 Reset
523
524L<HTML::FormHandler::Field::Reset>
525
526=head3 Button
527
528Button field that is rendered by the Button widget.
529
530L<HTML::FormHandler::Field::Button>
531
532=head3 Display
533
534Non-data field used for inserting HTML into the form. Probably
535now better handled by a Block or a rendering tag.
536
537L<HTML::FormHandler::Field::Display>
538
539=head3 AddElement
540
541Example field for adding a repeatable element.
542
543L<HTML::FormHandler::Field::AddElement>
544
545=head3 RmElement
546
547Example field for removing a repeatable element
548
549L<HTML::FormHandler::Field::RmElement>
550
551=head3 NonEditable
552
553For Bootstrap-style non-editable fields.
554
555=head2 TextArea fields
556
557Fields that inherit from 'TextArea'.
558
559=head3 TextArea
560
561L<HTML::FormHandler::Field::TextArea>
562
563=head2 Password fields
564
565=head3 Password
566
567Password field. Sets 'noupdate' flag if empty and not required.
568
569L<HTML::FormHandler::Field::Password>
570
571=head3 PasswordConf
572
573Password confirmation field.
574
575L<HTML::FormHandler::Field::PasswordConf>
576
577=head2 Other fields
578
579These fields inherit just from 'Field'.
580
581=head3 File
582
583A file field that does no processing. Most people probably want to
584use 'Upload' instead.
585
586L<HTML::FormHandler::Field::File>
587
588=head3 PrimaryKey
589
590Hidden field that provides the primary key for Repeatable fields.
591
592L<HTML::FormHandler::Field::PrimaryKey>
593
594=head3 Captcha
595
596A Captcha field using GD::SecurityImage. Requires the use of the
597L<HTML::FormHandler::TraitFor::Captcha> role, or similar code.
598
599L<HTML::FormHandler::Field::Captcha>
600
601=head1 AUTHOR
602
603FormHandler Contributors - see HTML::FormHandler
604
605=head1 COPYRIGHT AND LICENSE
606
607This software is copyright (c) 2017 by Gerda Shank.
608
609This is free software; you can redistribute it and/or modify it under
610the same terms as the Perl 5 programming language system itself.
611
612=cut
613