1HTML::FormHandler::ManuUasle:r:TCuotnotrriiablu(t3e)d PeHrTlMLD:o:cFuomremnHtaantdiloenr::Manual::Tutorial(3)
2
6 HTML::FormHandler::Manual::Tutorial - how to use FormHandler with
7 Catalyst
8
10 version 0.40068
11
13 Manual Index
14 A tutorial for beginners to HTML::FormHandler
16
18 This tutorial demonstrates how you can use HTML::FormHandler to manage
19 forms, validate form input, and interface your forms with the database.
20
22 Use CPAN to install HTML::FormHandler
23
25 We'll use the files that were created in the
26 Catalyst::Manual::Tutorial, in order to concentrate on just the bits
27 where HTML::FormHandler is useful. You can download a tar file of the
28 tutorial files from the Catalyst code repository. (See
29 Catalyst::Manual::Tutorial::Intro.)
30 Create an HTML::FormHandler form
32 Untar the tutorial and make a lib/MyApp/Form directory. In that
33 directory create the file Book.pm.
34 package MyApp::Form::Book;
36 use utf8; # if using non-latin1 languages
38 use HTML::FormHandler::Moose;
40 extends 'HTML::FormHandler::Model::DBIC';
41 has '+item_class' => ( default => 'Book' );
43 has_field 'title' => ( type => 'Text' );
44 has_field 'rating' => ( type => 'Integer' );
45 has_field 'authors' => ( type => 'Multiple', label_column => 'last_name' );
46 has_field 'submit' => ( type => 'Submit', value => 'Submit' );
47 no HTML::FormHandler::Moose;
49 1;
50 This is your Form class. The form initializes the 'item_class' to the
52 source name of your DBIx::Class result class. The form's fields are
53 defined with the 'has_field' sugar, or in a 'field_list'. The names of
54 the fields should match a column, relationship, or other accessor in
55 your DBIx::Class result class.
56 The basic fields have only a 'type', such as 'Text', or 'Integer'.
58 These types are actually the names of HTML::FormHandler::Field classes.
59 'Text' and 'Integer' are types that are provided by HTML::FormHandler,
60 in HTML::FormHandler::Field::Text and
61 HTML::FormHandler::Field::Integer.
62 The 'Multiple' type will allow you to easily create a multiple select
64 list from the 'authors' relationship. The 'label_column' attribute
65 must be defined because the column in the 'authors' table which is used
66 to create the select list does not have the default column name
67 ('name').
68 The 'submit' field is necessary if you are going to use FormHandler to
70 render your form. It wouldn't be necessary for hand-built templates or
71 HTML.
72 Eventually you will want to create your own field classes, but for this
74 simple form the default types are adequate.
75 Connect HTML::FormHandler to your controller
77 Edit lib/MyApp/Controller/Books.pm. Add use Moose:
78 use Moose;
80 BEGIN { extends 'Catalyst::Controller' }
81 use MyApp::Form::Book;
82 Create an attribute to hold your form:
84 has 'form' => ( isa => 'MyApp::Form::Book', is => 'rw',
86 lazy => 1, default => sub { MyApp::Form::Book->new } );
87 Add Action to Display and Save the Form
89 In "lib/MyApp/Controller/Books.pm" add the following method:
90 sub edit : Local {
92 my ( $self, $c, $book_id ) = @_;
93 $c->stash( template => 'books/edit.tt2',
95 form => $self->form );
96 # Validate and insert/update database
98 return unless $self->form->process( item_id => $book_id,
99 params => $c->req->parameters,
100 schema => $c->model('DB')->schema );
101 # Form validated, return to the books list
103 $c->flash->{status_msg} = 'Book saved';
104 $c->res->redirect($c->uri_for('list'));
105 }
106 This will handle both creating new books, and updating old books. If
108 $book_id is undefined, then HTML::FormHandler will create a new book
109 from your form. If you pass in a DBIx::Class row object instead of a
110 primary key, you don't need to specify the schema.
111 Render the form
113 Save a copy of "root/src/books/edit.tt2" and create a new file that
114 contains only:
115 [% form.render %]
117 Alternative hand-built Template for the form (optional)
119 Although the automatic rendering works well, sometimes it's necessary
120 to hand build HTML. This section contains an example of a Template
121 Toolkit template that may be used to display a FormHandler form.
122 In some cases, you might want to use the rendering for just the field
124 and build custom divs or tables or whatever around it:
125 <div class="mycustomclass">
127 [% form.render_field('book') %]
128 </div>
129 If you don't want to play with HTML at this point, you can skip ahead
131 to the next section.
132 You could also use TT macros to do pretty sophisticated template
134 generation. But for now, we'll stick to a straightforward TT template:
135 Delete the single statement in "root/src/books/edit.tt2", and enter or
137 copy the following:
138 [% META title = 'Book Form' %]
140 [% FOR field IN form.error_fields %]
142 [% FOR error IN field.errors %]
143 <p><span class="error" id="error">
144 [% field.label _ ': ' _ error %] </span></p>
145 [% END %]
146 [% END %]
147 <form name="[% form.name %]"
149 action="[% c.uri_for('edit', form.item_id) %]"
150 method="post">
151 <p>
152 [% f = form.field('title') %]
153 <label class="label" for="[% f.name %]">[% f.label %]:</label>
154 <input type="text" name="[% f.name %]" id="[% f.name %]" value="[% f.fif %]">
155 </p>
156 <p>
157 [% f = form.field('rating') %]
158 <label class="label" for="[% f.name %]">[% f.label %]:</label>
159 <input type="text" name="[% f.name %]" id="[% f.name %]" %] value="[% f.fif %]">
160 </p>
161 <p>
162 [% f = form.field('authors') %]
163 <label class="label" for="[% f.name %]">[% f.label %]:</label>
164 <select name="[% f.name %]" multiple="multiple" size="[% f.size %]">
165 [% FOR option IN f.options %]
166 <option value="[% option.value %]"
167 [% FOREACH selval IN f.fif %]
168 [% IF selval == option.value %]selected="selected"[% END %]
169 [% END %]>
170 [% option.label | html %]</option>
171 [% END %]
172 </select>
173 </p>
174 <input class="button" name="submit" type="submit" value="Submit" />
175 </form>
176 <p><a href="[% c.uri_for('list') %]">Return to book list</a></p>
178 Add links to access create and update actions
180 Add a link to root/src/books/list.tt2 to allow you to edit an existing
181 book, by changing the last <td> cell in the book list:
182 <td>
184 <a href="[% c.uri_for('delete', book.id) %]">Delete</a>|
185 <a href="[% c.uri_for('edit', book.id) %]">Edit</a>
186 </td>
187 Change the link to create a book at the bottom of the file:
189 <p>
191 <a href="[% c.uri_for('edit') %]">Create book</a>
192 </p>
193 Test the HTML::FormHandler Create Form
195 Start up the server for MyApp:
196 $ script/myapp_server.pl
198 (You'll need to login with test01/mypass if you're using the packaged
200 tutorial.) Click the new "Create book" link at the bottom to display
201 the form. Fill in the fields and click submit. You should be returned
202 to the Book List page with a "Book saved" message.
203 Magic! A new book has been created and saved to the database with very
205 little code in your controller.
206 Click on the 'edit' links, and edit the existing books. Changes should
208 be saved and displayed properly. Try to add an alphabetic character to
209 the rating field. You should get an error message.
210 Add additional attributes to your form's fields
212 We'll add a couple of 'label' attributes to the fields:
213 has_field 'title' => ( type => 'Text', label => 'Title of a Book' );
215 has_field 'rating' => ( type => 'Integer', label => 'Rating (1-5)' );
216 has_field 'authors' => ( type => 'Multiple', label_column => 'last_name' );
217 If you want a new attribute in your fields, it's very easy to add it to
219 your custom Field classes.
220 package MyApp::Form::Field::Extra;
222 use Moose;
223 extends 'HTML::FormHandler::Field';
224 has 'my_attribute' => ( isa => Str, is => 'ro' );
226 1;
228 Now if your Field classes inherit from this, you can have a
230 'my_attribute' attribute for all your fields. Or use a Moose role
231 instead of inheritance.
232 You can also add attributes to the base FormHandler field class using
234 Moose. This technique is described in
235 HTML::FormHandler::Manual::Cookbook.
236
238 Now we'll add more validation to ensure that users are entering correct
239 data.
240 Update the fields in the form file:
242 has_field 'title' => ( type => 'Text', label => 'Title of a Book',
244 required => 1, size => 40, minlength => 5 );
245 has_field 'rating' => ( type => 'Integer', label => 'Rating (1-5)',
246 required => 1, messages => { required => 'You must rate the book' },
247 range_start => 1, range_end => 5 );
248 has_field 'authors' => ( type => 'Multiple', label_column => 'last_name',
249 required => 1 );
250 We've made all the fields required. We added 'size' and 'minlength'
252 attributes to the 'title' field. These are attributes of the 'Text'
253 Field, which will use them to validate. We've added 'range_start' and
254 'range_end' attributes to the 'rating' field. Numbers entered in the
255 form will be checked to make sure they fall within the defined range.
256 (Another option would have been to use the 'IntRange' field type, which
257 makes it easy to create a select list of numbers.)
258 Add customized validation
260 You can create a Field class for validation that will be performed on
261 more than one field, but it is easy to perform custom validation on a
262 per-field basis.
263 This form doesn't really require any customized validation, so we'll
265 add a silly field constraint. Add the following to the form:
266 sub validate_title {
268 my ( $self, $field ) = @_;
269 $field->add_error("The word \'Rainbows\' is not allowed in titles")
270 if ( $field->value =~ /Rainbows/ );
271 }
272 You can also apply Moose constraints and transforms. Validation can
274 also be performed in a form 'validate_<field_name' method, in a
275 'validate_model' routine, and in a custom field class. You can
276 validate that the field is unique, or use a dependency list to make
277 more fields required if one is updated.
278 Check out the validation
280 Restart the development server, login, and try adding books with
281 various errors: title length less than 5 or more than 40, rating above
282 5, leaving out a particular field. Create a book with 'Rainbows' in
283 the title.
284 You should get error messages for every error.
286
288 FormHandler Contributors - see HTML::FormHandler
289
291 This software is copyright (c) 2017 by Gerda Shank.
292 This is free software; you can redistribute it and/or modify it under
294 the same terms as the Perl 5 programming language system itself.
295perl v5.38.0 2023-07H-T2M0L::FormHandler::Manual::Tutorial(3)