1HTML::FormHandler::ManuUasle:r:ICnotnrtor(i3b)uted PerlHDToMcLu:m:eFnotramtHiaonndler::Manual::Intro(3)
2
3
4

NAME

6       HTML::FormHandler::Manual::Intro - introduction to using FormHandler
7

VERSION

9       version 0.40068
10

SYNOPSIS

12       Manual Index
13
14       HTML::FormHandler is a form handling package that validates HTML form
15       data and, for database forms, saves it to the database on validation.
16       It has field classes that match various data types and HTML form
17       elements, and rendering roles that can be used to render forms in many
18       different ways, from hand-built forms to totally automated rendering.
19       It can, of course, be used to validate data even if you are not
20       interested in the rendering capabilities.
21
22       A FormHandler 'form' is a Perl subclass of HTML::FormHandler for non-
23       database forms, or a subclass of HTML::FormHandler::Model::DBIC for
24       database forms, and in it you define your fields and validation
25       routines. Because it's a Perl class written in Moose, you have a lot of
26       flexibility and control.
27
28       You can validate with Perl methods or Moose type constraints; you can
29       use your own validation libraries. You can define your own field
30       classes that perform specialized validation.
31
32       When the form is validated, you can get the validated values back with
33       "$form->value".
34
35       A working example of a Catalyst app using FormHandler forms is
36       available on github at <https://github.com/gshank/formhandler-example>.
37

Basics

39   Create a form class
40       The most common way of using FormHandler is to create a form package.
41       You must 'use' "HTML::FormHandler::Moose" and 'extend' FormHandler:
42
43           package MyApp::Form::Sample;
44           use HTML::FormHandler::Moose;
45           extends 'HTML::FormHandler';
46
47       Then you add some fields with 'has_field', and a field 'type' (the
48       short name of the field package). (Fields with no type have type
49       'Text'.)
50
51           has_field 'foo';
52           has_field 'bar' => ( type => 'Select' );
53
54       Basic field types are Text, Select, Checkbox, Submit, Hidden, Reset,
55       TextArea, Password, Upload. See HTML::FormHandler::Manual::Fields for
56       more information.
57
58   Or create a form class dynamically
59       You can also create a form class 'dynamically', by creating a 'new'
60       HTML::FormHandler object. Use a 'field_list' parameter to create the
61       fields instead of 'has_field'.
62
63           my $form = HTML::FormHandler->new( field_list => [
64                   'username' => { type => 'Text' },
65                   'selections' => { type => 'Select' },
66               ]
67           );
68
69       Some features will not be available using this method (like the
70       automatic use of 'validate_<field_name>' methods) and it's not as easy
71       to test, of course.
72
73   Process the form
74       The form's 'process' method should be run on each request, passing in
75       the request parameters:
76
77           $form->process( params => $c->request->body_parameters,
78               action => $action,
79           );
80
81       If the parameters are not empty, then validation will be performed. The
82       corollary is that you should not pass in extra parameters when the form
83       has not been posted. A special 'posted' flag can be used if the form
84       consists entirely of fields like checkboxes that do not include names
85       in params if unchecked, and also works to prevent validation from being
86       performed if there are extra params:
87
88           $form->process( posted => ( $c->req->method eq 'POST' ),
89               params => $c->request->parameters, action => $action );
90
91       There is an alternative method for processing the form, which is
92       sometimes preferred for persistent forms. It returns a 'result' object,
93       and clears the form:
94
95           my $result = $form->run( params => $c->request->body_parameters );
96
97       You can also set most other FormHandler attributes on the 'process'
98       call., One useful feature is that you can activate or inactivate
99       fields:
100
101           $form->process( params => $params, active => ['field1', 'field2'] );
102
103       See also HTML::FormHandler.
104
105   Or process a database form
106       A database form inherits from HTML::FormHandler::Model::DBIC instead of
107       HTML::FormHandler. You must either pass in the DBIC row object or give
108       FormHandler information to retrieve the row object.
109
110           $form->process( item => $row, params => $params );
111           -- or --
112           $form->process( item_id => $id, schema => $schema,
113               item_class => 'MyRow', params => $params );
114
115       'item_class' is often set in the form class.
116
117       See also HTML::FormHandler::Manual::Database and
118       HTML::FormHandler::TraitFor::Model::DBIC.
119
120   After processing the form
121       A database form will have saved the data or created a new row, so often
122       no more processing is necessary. You can get the structured field
123       values from "$form->value", and do whatever you want with them.
124
125       If the validation succeeded, you may want to redirect:
126
127           $form->process( params => $params );
128           return unless $form->validated
129           $c->res->redirect( .... );
130           -- or --
131           return unless $form->process( params => params );
132           $c->res->redirect;
133
134   Rendering the form
135       At its simplest, all you need to do is "$form->render" in a template.
136
137           [% form.render %]
138
139       The automatic rendering is powerful and flexible -- you can do almost
140       anything with the right settings. Or you can render the form with a
141       template.
142
143       The form object will give you a hashref of values suitable for filling
144       in the form with "$form->fif".
145
146       By default FormHandler structures fields (and renders them) in a way
147       that matches the database. If you want to organize the rendering output
148       in different ways, you can use blocks to organize your fields.
149
150          has_block 'fieldset1' => ( render_list => ['foo', 'bar'] );
151
152       For more rendering info, see HTML::FormHandler::Manual::Rendering.
153
154   Defaults for form fields
155       The simplest way to provide defaults is by setting the default
156       attribute in a field definition:
157
158          has_field 'my_foo' => ( default => 'my_foo' );
159
160       The database row ('item') that is passed in will provide initial values
161       for the form, of course. You can also provide default values with an
162       'init_object', which acts kind of like a database object:
163
164          $form->process( init_object => { foo => '...', bar => '...' } );
165
166       There are a number of other flags and methods for providing defaults.
167       See HTML::FormHandler::Manual::Defaults.
168
169   Validation
170       You can validate a field with a method in the form
171       'validate_<field_name>':
172
173           has_field 'foo';
174           sub validate_foo {
175               my ( $self, $field ) = @_; # self is the form
176               unless( $field->value == .... ) {
177                   $field->add_error( .... );
178               }
179           }
180
181       You can provide a validation coderef that will be a field method:
182
183           has_field 'foo' => ( validate_method => \&check_foo );
184           sub check_foo {
185               my $self = shift; # self is field
186               unless( $self->value == ... ) {
187                   $self->add_error( ... );
188               }
189           }
190
191       You can use 'apply' to use Moose types for validation, from
192       HTML::FormHandler::Types or another Moose type collection:
193
194           use HTML::FormHandler::Types ('NotAllDigits');
195           ...
196           has_field 'my_field' => ( apply => [NotAllDigits] );
197
198       Or create validators with check:
199
200           has_field 'quux' => (
201               apply => [ { check => qr/abc/, message => 'Not a valid quux' } ] );
202
203       You can also create custom fields with custom validation, or use an
204       existing field that does the validation you need.
205
206       See HTML::FormHandler::Manual::Validation for more information on
207       validation or HTML::FormHandler::Manual::Fields for more information on
208       fields.
209
210   Organizing your form code
211       You can use 'has_field' and 'has_block' in Moose roles:
212
213           package MyApp::Form::Role::Address;
214           use HTML::FormHandler::Moose::Role;
215
216           has_field 'foo';
217           has_block 'bar';
218
219       Your forms can inherit from base classes that set common application
220       defaults. You can override field definitions with '+'.
221
222       You can create 'compound' fields and include them in a form:
223
224           package MyApp::Form::Field::Complex;
225           use HTML::FormHandler::Moose;
226           extends 'HTML::FormHandler::Field::Compound';
227           has_field 'field1' => ( validate_method => \&validate_field1 );
228           has_field 'field2' => ( type => 'Select',
229               options_method => \&options_field2 );
230           sub validate_field1 { ... }
231           sub options_field2 { ... }
232           ...
233           package MyApp::Form::Complex;
234           use HTML::FormHandler::Moose;
235           extends 'HTML::FormHandler';
236           has '+field_name_space' => ( default => 'MyApp::Form::Field' );
237           has_field 'compound1' => ( type => 'Complex' );
238           has_field 'compound2' => ( type => 'Complex' );
239
240   Testing
241       It's much easier to write unit tests for FormHandler forms than for
242       Catalyst controllers. The 't' directory of the downloaded distribution
243       has lots of examples. See HTML::FormHandler::Manual::Testing for more
244       information.
245

Localization

247       FormHandler's built-in errors are added to the form fields with
248       "$field->add_error", and to the form with "$form->add_form_error".
249       These methods call a "$self->_localize" method which is a coderef set
250       from the field's default_localize sub, the field's 'localize_meth'
251       attribute with "localize_meth => sub {}", or a form's sub
252       localize_meth. The default localize uses Locale::Maketext.  You can
253       also use duck_type classes for localization.  See the documentation in
254       HTML::FormHandler::TraitFor::I18N and the tests in xt/locale.t.
255
256       If you wish to skip localization for a particular message (such as for
257       system errors) you can use "$field->push_errors" or
258       "$form->push_form_errors".
259
260       See also HTML::FormHandler::TraitFor::I18N.
261

Performance

263       FormHandler makes heavy use of Moose, so almost all of FormHandler's
264       profiled time will actually be in Moose methods, mostly constructing
265       form and field attributes.  Some people prefer to use a persistent form
266       class (in a Moose attribute) in order to skip the form building step on
267       each call. Other people don't like that solution because state will
268       remain in the form until the next process call. The 'clear' method is
269       called at the beginning of each 'process', but additional Moose
270       attributes in the form, etc, will have to cleared by the programmer.
271
272       If you are loading options from the database and you don't need to have
273       them refreshed each time, you can set the 'do_not_reload' flag in the
274       Select/Multiple field.  If you're not using the field widget roles, you
275       can set the 'no_widgets' flag.  If you always use 'process' on each
276       call (recommended) then you can set the 'no_preload' flag in the form
277       to skip building results in BUILD (new).
278

AUTHOR

280       FormHandler Contributors - see HTML::FormHandler
281
283       This software is copyright (c) 2017 by Gerda Shank.
284
285       This is free software; you can redistribute it and/or modify it under
286       the same terms as the Perl 5 programming language system itself.
287
288
289
290perl v5.36.0                      2023-01-20HTML::FormHandler::Manual::Intro(3)
Impressum