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