=head1 NAME Catalyst::Manual::Tutorial::09_AdvancedCRUD::09_FormHandler - Catalyst Tutorial - Chapter 9: Advanced CRUD - FormHandler =head1 OVERVIEW This is B for the Catalyst tutorial. L =over 4 =item 1 L =item 2 L =item 3 L =item 4 L =item 5 L =item 6 L =item 7 L =item 8 L =item 9 B<09_Advanced CRUD::09_FormHandler> =item 10 L =back =head1 DESCRIPTION This portion of the tutorial explores L and how it can be used to manage forms, perform validation of form input, as well as save and restore data to/from the database. This was written using HTML::FormHandler version 0.28001. See L for additional form management options other than L. =head1 Install HTML::FormHandler Use the following command to install L directly from CPAN: sudo cpan HTML::FormHandler::Model::DBIC It will install L as a prereq. Also add: requires 'HTML::FormHandler::Model::DBIC'; to your C. =head1 HTML::FormHandler FORM CREATION This section looks at how L can be used to add additional functionality to the manually created form from Chapter 4. =head2 Using FormHandler in your controllers FormHandler doen't have a Catalyst base controller, because interfacing to a form is only a couple of lines of code. =head2 Create a Book Form Create the directory C. Create C: package MyApp::Form::Book; use HTML::FormHandler::Moose; extends 'HTML::FormHandler::Model::DBIC'; use namespace::autoclean; has '+item_class' => ( default =>'Books' ); has_field 'title'; has_field 'rating' => ( type => 'Integer' ); has_field 'authors' => ( type => 'Multiple', label_column => 'last_name' ); has_field 'submit' => ( type => 'Submit', value => 'Submit' ); __PACKAGE__->meta->make_immutable; 1; =head2 Add Action to Display and Save the Form At the top of the C add: use MyApp::Form::Book; Add the following methods: =head2 create Use HTML::FormHandler to create a new book =cut sub create : Chained('base') PathPart('create') Args(0) { my ($self, $c ) = @_; my $book = $c->model('DB::Book')->new_result({}); return $self->form($c, $book); } =head2 form Process the FormHandler book form =cut sub form { my ( $self, $c, $book ) = @_; my $form = MyApp::Form::Book->new; # Set the template $c->stash( template => 'books/form.tt2', form => $form ); $form->process( item => $book, params => $c->req->params ); return unless $form->validated; $c->flash( message => 'Book created' ); # Redirect the user back to the list page $c->response->redirect($c->uri_for($self->action_for('list'))); } These two methods could be combined at this point, but we'll use the 'form' method later when we implement 'edit'. =head2 Create a Template Page To Display The Form Open C in your editor and enter the following: [% META title = 'Create/Update Book' %] [%# Render the HTML::FormHandler Form %] [% form.render %]

Return to book list

=head2 Add Link for Create Open C in your editor and add the following to the bottom of the existing file: ...

HTML::FormHandler: Create

This adds a new link to the bottom of the book list page that we can use to easily launch our HTML::FormHandler-based form. =head2 Test The HTML::FormHandler Create Form Press C to kill the previous server instance (if it's still running) and restart it: $ script/myapp_server.pl Login as C (password: mypass). Once at the Book List page, click the new HTML::Formhandler "Create" link at the bottom to display the form. Fill in the following values: Title = "Internetworking with TCP/IP Vol. II" Rating = "4" Author = "Comer" Click the Submit button, and you will be returned to the Book List page with a "Book created" status message displayed. Note that because the 'Author' column is a Select list, only the authors in the database can be entered. The 'ratings' field will only accept integers. =head2 Add Constraints Open C in your editor. Restrict the title size and make it required: has_field 'title' => ( minlength => 5, maxlength => 40, required => 1 ); Add range constraints to the 'rating' field: has_field 'rating' => ( type => 'Integer', range_start => 1, range_end => 5 ); The 'authors' relationship is a 'many-to-many' pseudo-relation, so this field can be set to Multiple to allow the selection of multiple authors and make it required: has_field 'authors' => ( type => 'Multiple', label_column => 'last_name', required => 1 ); Note: FormHandler automatically strips whitespace at the beginning or end of fields. If you want some other kind of stripping (or none) you can specify it explicitly. (see L) =head2 Try Out the Updated Form Press C to kill the previous server instance (if it's still running) and restart it: $ script/myapp_server.pl Make sure you are still logged in as C and try adding a book with various errors: title less than 5 characters, non-numeric rating, a rating of 0 or 6, etc. Also try selecting one, two, and zero authors. =head2 Create the 'edit' method Edit C and add the following method: =head2 edit Edit an existing book with FormHandler =cut sub edit : Chained('object') PathPart('edit') Args(0) { my ( $self, $c ) = @_; return $self->form($c, $c->stash->{object}); } Update the C, adding an 'edit' link below the "Delete" link to use the FormHandler edit method: [% # Add a link to delete a book %] Delete [% # Add a link to edit a book %] Edit =head2 Try Out the Edit/Update Feature Press C to kill the previous server instance (if it's still running) and restart it: $ script/myapp_server.pl Make sure you are still logged in as C and go to the L URL in your browser. Click the "Edit" link next to "Internetworking with TCP/IP Vol. II", change the rating to a 3, the "II" at end of the title to the number "2", add Stevens as a co-author (control-click), and click Submit. You will then be returned to the book list with a "Book edited" message at the top in green. Experiment with other edits to various books. =head2 See additional documentation on FormHandler L L #formhandler on irc.perl.org mailing list: http://groups.google.com/group/formhandler code: http://github.com/gshank/html-formhandler/tree/master =head1 AUTHOR Gerda Shank, C Copyright 2009, Gerda Shank, Perl Artistic License