1HTML::FormHandler::ManuUasle:r:ICnotnrtor(i3b)uted PerlHDToMcLu:m:eFnotramtHiaonndler::Manual::Intro(3)
2
6 HTML::FormHandler::Manual::Intro - introduction to using FormHandler
7
9 version 0.40068
10
12 Manual Index
13 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 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 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 When the form is validated, you can get the validated values back with
33 "$form->value".
34 A working example of a Catalyst app using FormHandler forms is
36 available on github at <https://github.com/gshank/formhandler-example>.
37
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 package MyApp::Form::Sample;
44 use HTML::FormHandler::Moose;
45 extends 'HTML::FormHandler';
46 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 has_field 'foo';
52 has_field 'bar' => ( type => 'Select' );
53 Basic field types are Text, Select, Checkbox, Submit, Hidden, Reset,
55 TextArea, Password, Upload. See HTML::FormHandler::Manual::Fields for
56 more information.
57 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 my $form = HTML::FormHandler->new( field_list => [
64 'username' => { type => 'Text' },
65 'selections' => { type => 'Select' },
66 ]
67 );
68 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 Process the form
74 The form's 'process' method should be run on each request, passing in
75 the request parameters:
76 $form->process( params => $c->request->body_parameters,
78 action => $action,
79 );
80 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 $form->process( posted => ( $c->req->method eq 'POST' ),
89 params => $c->request->parameters, action => $action );
90 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 my $result = $form->run( params => $c->request->body_parameters );
96 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 $form->process( params => $params, active => ['field1', 'field2'] );
102 See also HTML::FormHandler.
104 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 $form->process( item => $row, params => $params );
111 -- or --
112 $form->process( item_id => $id, schema => $schema,
113 item_class => 'MyRow', params => $params );
114 'item_class' is often set in the form class.
116 See also HTML::FormHandler::Manual::Database and
118 HTML::FormHandler::TraitFor::Model::DBIC.
119 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 If the validation succeeded, you may want to redirect:
126 $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 Rendering the form
135 At its simplest, all you need to do is "$form->render" in a template.
136 [% form.render %]
138 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 The form object will give you a hashref of values suitable for filling
144 in the form with "$form->fif".
145 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 has_block 'fieldset1' => ( render_list => ['foo', 'bar'] );
151 For more rendering info, see HTML::FormHandler::Manual::Rendering.
153 Defaults for form fields
155 The simplest way to provide defaults is by setting the default
156 attribute in a field definition:
157 has_field 'my_foo' => ( default => 'my_foo' );
159 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 $form->process( init_object => { foo => '...', bar => '...' } );
165 There are a number of other flags and methods for providing defaults.
167 See HTML::FormHandler::Manual::Defaults.
168 Validation
170 You can validate a field with a method in the form
171 'validate_<field_name>':
172 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 You can provide a validation coderef that will be a field method:
182 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 You can use 'apply' to use Moose types for validation, from
192 HTML::FormHandler::Types or another Moose type collection:
193 use HTML::FormHandler::Types ('NotAllDigits');
195 ...
196 has_field 'my_field' => ( apply => [NotAllDigits] );
197 Or create validators with check:
199 has_field 'quux' => (
201 apply => [ { check => qr/abc/, message => 'Not a valid quux' } ] );
202 You can also create custom fields with custom validation, or use an
204 existing field that does the validation you need.
205 See HTML::FormHandler::Manual::Validation for more information on
207 validation or HTML::FormHandler::Manual::Fields for more information on
208 fields.
209 Organizing your form code
211 You can use 'has_field' and 'has_block' in Moose roles:
212 package MyApp::Form::Role::Address;
214 use HTML::FormHandler::Moose::Role;
215 has_field 'foo';
217 has_block 'bar';
218 Your forms can inherit from base classes that set common application
220 defaults. You can override field definitions with '+'.
221 You can create 'compound' fields and include them in a form:
223 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 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
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 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 See also HTML::FormHandler::TraitFor::I18N.
261
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 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
280 FormHandler Contributors - see HTML::FormHandler
281
283 This software is copyright (c) 2017 by Gerda Shank.
284 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.
287perl v5.36.0 2023-01-20HTML::FormHandler::Manual::Intro(3)