3 Catalyst::Manual::Tutorial::AdvancedCRUD - Catalyst Tutorial - Part 8: Advanced CRUD
8 This is B<Part 8 of 9> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
16 L<Introduction|Catalyst::Manual::Tutorial::Intro>
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
24 L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
28 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
32 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
36 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
40 L<Testing|Catalyst::Manual::Tutorial::Testing>
48 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
54 This part of the tutorial explores more advanced functionality for
55 Create, Read, Update, and Delete (CRUD) than we saw in Part 3. In
56 particular, it looks at a number of techniques that can be useful for
57 the Update portion of CRUD, such as automated form generation,
58 validation of user-entered data, and automated transfer of data between
59 forms and model objects.
61 In keeping with the Catalyst (and Perl) spirit of flexibility, there are
62 many different ways to approach advanced CRUD operations in a Catalyst
63 environment. One alternative is to use
64 L<Catalyst::Helper::Controller::Scaffold|Catalyst::Helper::Controller::Scaffold>
65 to instantly construct a set of Controller methods and templates for
66 basic CRUD operations. Although a popular subject in Quicktime
67 movies that serve as promotional material for various frameworks,
68 real-world applications generally require more control. Other
69 options include L<Data::FormValidator|Data::FormValidator> and
70 L<HTML::FillInForm|HTML::FillInForm>.
72 Here, we will make use of the L<HTML::Widget|HTML::Widget> to not only
73 ease form creation, but to also provide validation of the submitted
74 data. The approached used by this part of the tutorial is to slowly
75 incorporate additional L<HTML::Widget|HTML::Widget> functionality in a
76 step-wise fashion (we start with fairly simple form creation and then
77 move on to more complex and "magical" features such as validation and
78 auto-population/auto-saving).
80 B<Note:> Part 8 of the tutorial is optional. Users who do not wish to
81 use L<HTML::Widget|HTML::Widget> may skip this part.
83 You can checkout the source code for this example from the catalyst subversion repository as per the instructions in L<Catalyst::Manual::Tutorial::Intro>
85 =head1 C<HTML::WIDGET> FORM CREATION
87 This section looks at how L<HTML::Widget|HTML::Widget> can be used to
88 add additional functionality to the manually created form from Part 3.
90 =head2 Add the C<HTML::Widget> Plugin
92 Open C<lib/MyApp.pm> in your editor and add the following to the list of
93 plugins (be sure to leave the existing plugins enabled):
97 =head2 Add a Form Creation Helper Method
99 Open C<lib/MyApp/Controller/Books.pm> in your editor and add the
102 =head2 make_book_widget
104 Build an HTML::Widget form for book creation and updates
108 sub make_book_widget {
111 # Create an HTML::Widget to build the form
112 my $w = $c->widget('book_form')->method('post');
115 my @authorObjs = $c->model("MyAppDB::Author")->all();
116 my @authors = map {$_->id => $_->last_name }
117 sort {$a->last_name cmp $b->last_name} @authorObjs;
119 # Create the form feilds
120 $w->element('Textfield', 'title' )->label('Title')->size(60);
121 $w->element('Textfield', 'rating' )->label('Rating')->size(1);
122 $w->element('Select', 'authors')->label('Authors')
124 $w->element('Submit', 'submit' )->value('submit');
130 This method provides a central location that builds an
131 HTML::Widget-based form with the appropriate fields. The "Get authors"
132 code uses DBIC to retrieve a list of model objects and then uses C<map>
133 to create a hash where the hash keys are the database primary keys from
134 the authors table and the associated values are the last names of the
137 =head2 Add Actions to Display and Save the Form
139 Open C<lib/MyApp/Controller/Books.pm> in your editor and add the
144 Build an HTML::Widget form for book creation and updates
148 sub hw_create : Local {
151 # Create the widget and set the action for the form
152 my $w = $self->make_book_widget($c);
153 $w->action($c->uri_for('hw_create_do'));
155 # Write form to stash variable for use in template
156 $c->stash->{widget_result} = $w->result;
159 $c->stash->{template} = 'books/hw_form.tt2';
165 Build an HTML::Widget form for book creation and updates
169 sub hw_create_do : Local {
172 # Retrieve the data from the form
173 my $title = $c->request->params->{title};
174 my $rating = $c->request->params->{rating};
175 my $authors = $c->request->params->{authors};
177 # Call create() on the book model object. Pass the table
178 # columns/field values we want to set as hash values
179 my $book = $c->model('MyAppDB::Book')->create({
184 # Add a record to the join table for this book, mapping to
186 $book->add_to_book_authors({author_id => $authors});
188 # Set a status message for the user
189 $c->stash->{status_msg} = 'Book created';
191 # Use 'hw_create' to redisplay the form. As discussed in
192 # Part 3, 'detach' is like 'forward', but it does not return
193 $c->detach('hw_create');
196 Note how we use C<make_book_widget> to build the core parts of the form
197 in one location, but we set the action (the URL the form is sent to when
198 the user clicks the 'Submit' button) separately in C<hw_create>. Doing
199 so allows us to have the same form submit the data to different actions
200 (e.g., C<hw_create_do> for a create operation but C<hw_update_do> to
201 update an existing book object).
203 B<NOTE:> If you receive an error about Catalyst not being able to find
204 the template C<hw_create_do.tt2>, please verify that you followed the
205 instructions in the final section of
206 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics> where
207 you returned to a manually-specified template. You can either use
208 C<forward>/C<detach> B<OR> default template names, but the two cannot
212 =head2 Update the CSS
214 Edit C<root/src/ttsite.css> and add the following lines to the bottom of
235 color: [% site.col.error %];
238 These changes will display form elements vertically and also show error
239 messages in red. Note that we are pulling the color scheme settings
240 from the C<root/lib/config/col> file that was created by the TTSite
241 helper. This allows us to change the color used by various error styles
242 in the CSS from a single location.
244 =head2 Create a Template Page To Display The Form
246 Open C<root/src/books/hw_form.tt2> in your editor and enter the following:
248 [% META title = 'Create/Update Book' %]
250 [% widget_result.as_xml %]
252 <p><a href="[% Catalyst.uri_for('list') %]">Return to book list</a></p>
254 =head2 Add Links for Create and Update via C<HTML::Widget>
256 Open C<root/src/books/list.tt2> in your editor and add the following to
257 the bottom of the existing file:
261 <a href="[% Catalyst.uri_for('hw_create') %]">Create</a>
265 =head2 Test The <HTML::Widget> Create Form
267 Press C<Ctrl-C> to kill the previous server instance (if it's still
268 running) and restart it:
270 $ script/myapp_server.pl
272 Login as C<test01>. Once at the Book List page, click the HTML::Widget
273 "Create" link to display for form produced by C<make_book_widget>. Fill
274 out the form with the following values: Title = "Internetworking with
275 TCP/IP Vol. II", Rating = "4", and Author = "Comer". Click Submit, and
276 you will be returned to the Create/Update Book page with a "Book
277 created" status message displayed. Click "Return to book list" to view
278 the newly created book on the main list.
280 Also note that this implementation allows you to can create books with
281 bogus information. Although we have constrained the authors with the
282 drop-down list, there are no restrictions on items such as the length of
283 the title (for example, you can create a one-letter title) and value for
284 the rating (you can use any number you want, and even non-numeric values
285 with SQLite). The next section will address this concern.
287 B<Note:> Depending on the database you are using and how you established
288 the columns in your tables, the database could obviously provide various
289 levels of "type enforcement" on your data. The key point being made in
290 the previous paragraph is that the I<web application> itself is not
291 performing any validation.
293 =head1 C<HTML::WIDGET> VALIDATION AND FILTERING
295 Although the use of L<HTML::Widget|HTML::Widget> in the previous section
296 did provide an automated mechanism to build the form, the real power of
297 this module stems from functionality that can automatically validate and
298 filter the user input. Validation uses constraints to be sure that
299 users input appropriate data (for example, that the email field of a
300 form contains a valid email address). Filtering can be used to remove
301 extraneous whitespace from fields or to escape meta-characters in user
304 =head2 Add Constraints and Filters to the Widget Creation Method
306 Open C<lib/MyApp/Controller/Books.pm> in your editor and update the
307 C<make_book_widget> method to match the following (new sections have
308 been marked with a C<*** NEW:> comment):
310 sub make_book_widget {
313 # Create an HTML::Widget to build the form
314 my $w = $c->widget('book_form')->method('post');
317 my @authorObjs = $c->model("MyAppDB::Author")->all();
318 my @authors = map {$_->id => $_->last_name }
319 sort {$a->last_name cmp $b->last_name} @authorObjs;
321 # Create the form feilds
322 $w->element('Textfield', 'title' )->label('Title')->size(60);
323 $w->element('Textfield', 'rating' )->label('Rating')->size(1);
324 # ***NEW: Convert to multi-select list
325 $w->element('Select', 'authors')->label('Authors')
326 ->options(@authors)->multiple(1)->size(3);
327 $w->element('Submit', 'submit' )->value('submit');
329 # ***NEW: Set constraints
330 $w->constraint(All => qw/title rating authors/)
331 ->message('Required. ');
332 $w->constraint(Integer => qw/rating/)
333 ->message('Must be an integer. ');
334 $w->constraint(Range => qw/rating/)->min(1)->max(5)
335 ->message('Must be a number between 1 and 5. ');
336 $w->constraint(Length => qw/title/)->min(5)->max(50)
337 ->message('Must be between 5 and 50 characters. ');
339 # ***NEW: Set filters
340 for my $column (qw/title rating authors/) {
341 $w->filter( HTMLEscape => $column );
342 $w->filter( TrimEdges => $column );
349 The main changes are:
355 The C<Select> element for C<authors> is changed from a single-select
356 drop-down to a multi-select list by adding calls to C<multiple> (set to
357 C<true>) and C<size> (set to the number of rows to display).
361 Four sets of constraints are added to provide validation of the user input.
365 Two filters are run on every field to remove and escape unwanted input.
369 =head2 Rebuild the Form Submission Method to Include Validation
371 Edit C<lib/MyApp/Controller/Books.pm> and change C<hw_create_do> to
372 match the following code (enough of the code is different that you
373 probably want to cut and paste this over code the existing method):
375 sub hw_create_do : Local {
378 # Retrieve the data from the form
379 my $title = $c->request->params->{title};
380 my $rating = $c->request->params->{rating};
381 my $authors = $c->request->params->{authors};
383 # Create the widget and set the action for the form
384 my $w = $self->make_book_widget($c);
385 $w->action($c->uri_for('hw_create_do'));
387 # Validate the form parameters
388 my $result = $w->process($c->req);
390 # Write form (including validation error messages) to
391 # stash variable for use in template
392 $c->stash->{widget_result} = $result;
394 # Were their validation errors?
395 if ($result->has_errors) {
396 # Warn the user at the top of the form that there were errors.
397 # Note that there will also be per-field feedback on
398 # validation errors because of '$w->process($c->req)' above.
399 $c->stash->{error_msg} = 'Validation errors!';
401 # Everything validated OK, so do the create
402 # Call create() on the book model object. Pass the table
403 # columns/field values we want to set as hash values
404 my $book = $c->model('MyAppDB::Book')->create({
409 # Add a record to the join table for this book, mapping to
410 # appropriate author. Note that $authors will be 1 author as
411 # a scalar or ref to list of authors depending on how many the
412 # user selected; the 'ref $authors ?...' handles both cases
413 foreach my $author (ref $authors ? @$authors : $authors) {
414 $book->add_to_book_authors({author_id => $author});
416 # Set a status message for the user
417 $c->stash->{status_msg} = 'Book created';
421 $c->stash->{template} = 'books/hw_form.tt2';
424 The key changes to C<hw_create_do> are:
430 C<hw_create_do> no longer does a C<detach> to C<hw_create> to redisplay
431 the form. Now that C<hw_create_do> has to process the form in order to
432 perform the validation, we go ahead and build a complete set of form
433 presentation logic into C<hw_create_do> (for example, C<hw_create_do>
434 now has a C<$c-E<gt>stash-E<gt>{template}> line). Note that if we
435 process the form in C<hw_create_do> I<and> forward/detach back to
436 <hw_create>, we would end up with C<make_book_widget> being called
437 twice, resulting in a duplicate set of elements being added to the form.
438 (There are other ways to address the "duplicate form rendering" issue --
439 just be aware that it exists.)
443 C<$w-E<gt>process($c-E<gt>req)> is called to run the validation logic.
444 Not only does this set the C<has_errors> flag if validation errors are
445 encountered, it returns a string containing any field-specific warning
450 An C<if> statement checks if any validation errors were encountered. If
451 so, C<$c-E<gt>stash-E<gt>{error_msg}> is set and the input form is
452 redisplayed. If no errors were found, the object is created in a manner
453 similar to the prior version of the C<hw_create_do> method.
457 =head2 Try Out the Form
459 Press C<Ctrl-C> to kill the previous server instance (if it's still
460 running) and restart it:
462 $ script/myapp_server.pl
464 Now try adding a book with various errors: title less than 5 characters,
465 non-numeric rating, a rating of 0 or 6, etc. Also try selecting one,
466 two, and zero authors. When you click Submit, the HTML::Widget
467 C<constraint> items will validate the logic and insert feedback as
471 =head1 Enable C<DBIx::Class::HTMLWidget> Support
473 In this section we will take advantage of some of the "auto-population"
474 features of C<DBIx::Class::HTMLWidget>. Enabling
475 C<DBIx::Class::HTMLWidget> provides two additional methods to your DBIC
484 Takes data from the database and transfers it to your form widget.
488 populate_from_widget()
490 Takes data from a form widget and uses it to update the corresponding
491 records in the database.
495 In other words, the two methods are a mirror image of each other: one
496 reads from the database while the other writes to the database.
498 =head2 Add C<DBIx::Class::HTMLWidget> to DBIC Model
500 In order to use L<DBIx::Class::HTMLWidget|DBIx::Class::HTMLWidget>, we
501 need to add C<HTMLWidget> to the C<load_components> line of DBIC result
502 source files that need to use the C<fill_widget> and
503 C<populate_from_widget> methods. In this case, open
504 C<lib/MyAppDB/Book.pm> and update the C<load_components> line to match:
506 __PACKAGE__->load_components(qw/PK::Auto Core HTMLWidget/);
508 =head2 Use C<populate_from_widget> in C<hw_create_do>
510 Edit C<lib/MyApp/Controller/Books.pm> and update C<hw_create_do> to
511 match the following code:
515 Build an HTML::Widget form for book creation and updates
519 sub hw_create_do : Local {
522 # Create the widget and set the action for the form
523 my $w = $self->make_book_widget($c);
524 $w->action($c->uri_for('hw_create_do'));
526 # Validate the form parameters
527 my $result = $w->process($c->req);
529 # Write form (including validation error messages) to
530 # stash variable for use in template
531 $c->stash->{widget_result} = $result;
533 # Were their validation errors?
534 if ($result->has_errors) {
535 # Warn the user at the top of the form that there were errors.
536 # Note that there will also be per-field feedback on
537 # validation errors because of '$w->process($c->req)' above.
538 $c->stash->{error_msg} = 'Validation errors!';
540 my $book = $c->model('MyAppDB::Book')->new({});
541 $book->populate_from_widget($result);
543 # Add a record to the join table for this book, mapping to
544 # appropriate author. Note that $authors will be 1 author as
545 # a scalar or ref to list of authors depending on how many the
546 # user selected; the 'ref $authors ?...' handles both cases
547 my $authors = $c->request->params->{authors};
548 foreach my $author (ref $authors ? @$authors : $authors) {
549 $book->add_to_book_authors({author_id => $author});
552 # Set a status message for the user
553 $c->flash->{status_msg} = 'Book created';
555 # Redisplay an empty form for another
556 $c->stash->{widget_result} = $w->result;
560 $c->stash->{template} = 'books/hw_form.tt2';
563 In this version of C<hw_create_do> we removed the logic that manually
564 pulled the form variables and used them to call
565 C<$c-E<gt>model('MyAppDB::Book')-E<gt>create> and replaced it with a
566 single call to C<$book-E<gt>populate_from_widget>. Note that we still
567 have to call C<$book-E<gt>add_to_book_authors> once per author because
568 C<populate_from_widget> does not currently handle the relationships
569 between tables. Also, we reset the form to an empty fields by adding
570 another call to C<$w-E<gt>result> and storing the output in the stash
571 (if we don't override the output from C<$w-E<gt>process($c-E<gt>req)>,
572 the form values already entered will be retained on redisplay --
573 although this could be desirable for some applications, we avoid it
574 here to help avoid the creation of duplicate records).
577 =head2 Try Out the Form
579 Press C<Ctrl-C> to kill the previous server instance (if it's still
580 running) and restart it:
582 $ script/myapp_server.pl
584 Try adding a book that validates. Return to the book list and the book
585 you added should be visible.
589 =head1 Rendering C<HTMLWidget> Forms in a Table
591 Some developers my wish to use the "old-fashioned" table style of
592 rendering a form in lieu of the default C<HTML::Widget> rendering that
593 assumes you will use CSS for formatting. This section demonstrates
594 some techniques that can override the default rendering with a
598 =head2 Add a New "Element Container"
600 Open C<lib/FormElementContainer.pm> in your editor and enter:
602 package FormElementContainer;
604 use base 'HTML::Widget::Container';
607 my ($self, $element) = @_;
609 return () unless $element;
610 if (ref $element eq 'ARRAY') {
611 return map { $self->_build_element($_) } @{$element};
613 my $e = $element->clone;
614 $e = new HTML::Element('span', class => 'fields_with_errors')->push_content($e)
615 if $self->error && $e->tag eq 'input';
617 return $e ? ($e) : ();
622 This simply dumps the HTML code for a given form element, followed by a
623 C<span> that can contain validation error message.
626 =head2 Enable the New Element Container When Building the Form
628 Open C<lib/MyApp/Controller/Books.pm> in your editor. First add a
629 C<use> for your element container class:
631 use FormElementContainer;
633 B<Note:> If you forget to C<use> your container class in your
634 controller, then your form will not be displayed and no error messages
635 will be generated. Don't forget this important step!
637 Then tell C<HTML::Widget> to use that class during rendering by updating
638 C<make_book_widget> to match the following:
640 sub make_book_widget {
643 # Create an HTML::Widget to build the form
644 my $w = $c->widget('book_form')->method('post');
646 # ***New: Use custom class to render each element in the form
647 $w->element_container_class('FormElementContainer');
650 my @authorObjs = $c->model("MyAppDB::Author")->all();
651 my @authors = map {$_->id => $_->last_name }
652 sort {$a->last_name cmp $b->last_name} @authorObjs;
654 # Create the form feilds
655 $w->element('Textfield', 'title' )->label('Title')->size(60);
656 $w->element('Textfield', 'rating' )->label('Rating')->size(1);
657 # Convert to multi-select list
658 $w->element('Select', 'authors')->label('Authors')
659 ->options(@authors)->multiple(1)->size(3);
660 $w->element('Submit', 'submit' )->value('submit');
663 $w->constraint(All => qw/title rating authors/)
664 ->message('Required. ');
665 $w->constraint(Integer => qw/rating/)
666 ->message('Must be an integer. ');
667 $w->constraint(Range => qw/rating/)->min(1)->max(5)
668 ->message('Must be a number between 1 and 5. ');
669 $w->constraint(Length => qw/title/)->min(5)->max(50)
670 ->message('Must be between 5 and 50 characters. ');
673 for my $column (qw/title rating authors/) {
674 $w->filter( HTMLEscape => $column );
675 $w->filter( TrimEdges => $column );
682 The two new lines are marked with C<***New:>.
685 =head2 Update the TT Template
687 Open C<root/src/books/hw_form.tt2> and edit it to match:
689 [% META title = 'Create/Update Book' %]
691 [%# Comment out the auto-rendered form %]
692 [%# widget_result.as_xml %]
695 [%# Iterate over the form elements and display each -%]
696 <form name="book_form" action="[% widget_result.action %]" method="post">
698 [% FOREACH element = widget_result.elements %]
700 <td class="form-label">
701 [% element.label.as_text %]
703 <td class="form-element">
704 [% element.element_xml %]
705 <span class="form-error">
706 [% element.error_xml %]
715 <p><a href="[% Catalyst.uri_for('list') %]">Return to book list</a></p>
718 [%# A little JavaScript to move the cursor to the first field %]
719 <script LANGUAGE="JavaScript">
720 document.book_form.book_form_title.focus();
723 This represents three changes:
729 The existing C<widget_result.as_xml> has been commented out.
733 It loops through each form element, displaying the field name in the
734 first table cell along with the form element and validation errors in
739 JavaScript to position the user's cursor in the first field of the form.
744 =head2 Try Out the Form
746 Press C<Ctrl-C> to kill the previous server instance (if it's still
747 running) and restart it:
749 $ script/myapp_server.pl
751 Try adding a book that validates. Return to the book list and the book
752 you added should be visible.
757 Kennedy Clark, C<hkclark@gmail.com>
759 Please report any errors, issues or suggestions to the author. The
760 most recent version of the Catalyst Tutorial can be found at
761 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
763 Copyright 2006, Kennedy Clark, under Creative Commons License
764 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).