From: Kennedy Clark Date: Sun, 15 Nov 2009 14:01:41 +0000 (+0000) Subject: Add FormHandler branch (with thanks to gshank!) X-Git-Tag: v5.8005~84 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=0abc72edf5636d7f700793f5b700180428102feb Add FormHandler branch (with thanks to gshank!) --- diff --git a/lib/Catalyst/Manual/Tutorial/01_Intro.pod b/lib/Catalyst/Manual/Tutorial/01_Intro.pod index f8be880..3139583 100644 --- a/lib/Catalyst/Manual/Tutorial/01_Intro.pod +++ b/lib/Catalyst/Manual/Tutorial/01_Intro.pod @@ -162,8 +162,8 @@ by DBIx::Class.) =item * -The use of L for automated form processing -and validation. +The use of L or L +for automated form processing and validation. =back diff --git a/lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD.pod b/lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD.pod index f1424f5..9e295fc 100644 --- a/lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD.pod +++ b/lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD.pod @@ -79,6 +79,10 @@ L =item * +L + +=item * + L =back diff --git a/lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD/09_FormHandler.pod b/lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD/09_FormHandler.pod new file mode 100644 index 0000000..cfd23cf --- /dev/null +++ b/lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD/09_FormHandler.pod @@ -0,0 +1,297 @@ +=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. + + +=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', 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