X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FAdvancedCRUD%2FFormFu.pod;h=80c872ca6290f8e903a3dad57f9a3dcbe2ebc5c1;hp=644f10785e62a3ceba3dc56f1e87859d02f95251;hb=aee2748332aed431f3c342d3dc2956c0ceb2b1ea;hpb=0909d46f048c5d6407bdc0b99bcfb7835f3c2284 diff --git a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod index 644f107..80c872c 100644 --- a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod +++ b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod @@ -1,9 +1,9 @@ =head1 NAME -Catalyst::Manual::Tutorial::AdvancedCRUD::FormFu - Catalyst Tutorial - Part 9: Advanced CRUD - FormFu -NOTE: This part of the tutorial is in progress and will be ready soon. +Catalyst::Manual::Tutorial::AdvancedCRUD::FormFu - Catalyst Tutorial - Part 9: Advanced CRUD - FormFu + =head1 OVERVIEW @@ -60,7 +60,8 @@ L 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. +as well as save and restore data to/from the database. This was written +using HTML::FormFu version 0.03007. See L @@ -79,13 +80,33 @@ required by C: sudo apt-get install libtest-nowarnings-perl libdatetime-format-builder-perl \ libdatetime-format-strptime-perl libdatetime-locale-perl \ libhtml-tokeparser-simple-perl liblist-moreutils-perl \ - libregexp-copy-perl libregexp-common-perl libyaml-syck-perl libparams-util-perl + libregexp-copy-perl libregexp-common-perl libyaml-syck-perl libparams-util-perl \ + libcrypt-des-perl libcaptcha-recaptcha-perl libcrypt-cbc-perl \ + libreadonly-xs-perl libmoose-perl libregexp-assemble-perl + + ... + + sudo apt-get clean Then use the following command to install directly from CPAN the modules that aren't available as Ubuntu/Debian packages via C: - sudo cpan File::ShareDir Task::Weaken Config::Any HTML::FormFu \ - Catalyst::Controller::HTML::FormFu + sudo cpan File::ShareDir Task::Weaken Config::Any Test::Harness Test::Aggregate \ + boolean Test::MockTime DateTime::Format::Natural HTML::FormFu \ + Catalyst::Component::InstancePerContext Catalyst::Controller::HTML::FormFu \ + HTML::FormFu::Model::DBIC + + ... + + Is it OK to try to connect to the Internet? [yes] yes + + ... + + +B If you are following along with the Ubuntu LiveCD, you might +want to make sure you still have adequate free disk space in the root +partition with the C command. You can free up some space with +C. =head1 C FORM CREATION @@ -100,11 +121,11 @@ First, change your C to inherit from L by changing the C line from the default of: - use base 'Catalyst::Controller'; + use parent 'Catalyst::Controller'; to use the FormFu base controller class: - use base 'Catalyst::Controller::HTML::FormFu'; + use parent 'Catalyst::Controller::HTML::FormFu'; =head2 Add Action to Display and Save the Form @@ -124,14 +145,14 @@ following method: # Get the form that the :FormConfig attribute saved in the stash my $form = $c->stash->{form}; - # Check if the form as been submitted (vs. displaying the initial - # form) and if the data based validation. "submitted_and_valid" + # Check if the form has been submitted (vs. displaying the initial + # form) and if the data passed validation. "submitted_and_valid" # is shorthand for "$form->submitted && !$form->has_errors" if ($form->submitted_and_valid) { # Create a new book my $book = $c->model('DB::Books')->new_result({}); # Save the form data for the book - $form->save_to_model($book); + $form->model->update($book); # Set a status message for the user $c->flash->{status_msg} = 'Book created'; # Return to the books list @@ -202,10 +223,14 @@ following text: name: submit value: Submit +B Copying and pasting YAML from perl documentation is sometimes +tricky. See the L section of +this document for a more foolproof config format. + =head2 Update the CSS -Edit C and add the following lines to the bottom of +Edit C and add the following lines to the bottom of the file: input { @@ -235,7 +260,7 @@ Open C in your editor and enter the following: [%# Render the HTML::FormFu Form %] [% form %] -

Return to book list

+

Return to book list

=head2 Add Links for Create and Update via C @@ -245,7 +270,7 @@ the bottom of the existing file:

HTML::FormFu: - Create + Create

This adds a new link to the bottom of the book list page that we can @@ -311,16 +336,8 @@ to match: # This is an optional 'mouse over' title pop-up attributes: title: Enter a book title here - # Use Filter to clean up the input data - filter: - # Remove whitespace at both ends - - TrimEdges - # Escape HTML characters for safety - - HTMLEscape # Add constraints for the field constraints: - # The user cannot leave this field blank - - SingleValue # Force the length to be between 5 and 40 chars - type: Length min: 5 @@ -335,16 +352,22 @@ to match: attributes: title: Enter a rating between 1 and 5 here # Use Filter to clean up the input data - filter: - # Remove whitespace at both ends - - TrimEdges + # Could use 'NonNumeric' below, but since Filters apply *before* + # constraints, it would conflict with the 'Integer' constraint below. + # So let's skip this and just use the constraint. + #filter: # Remove everything except digits - - NonNumeric + #- NonNumeric # Add constraints to the field constraints: - - SingleValue # Make sure it's a number - - Integer + - type: Integer + message: "Required. Digits only, please." + # Check the min & max values + - type: Range + min: 1 + max: 5 + message: "Must be between 1 and 5." # Add a select list for the author selection. Note that we will # dynamically fill in all the authors from the controller but we @@ -362,12 +385,6 @@ to match: # One could argue we don't need to do filters or constraints for # a select list, but it's smart to do validation and sanity # checks on this data in case a user "hacks" the input - # Use Filter to clean up the input data - filter: - # Remove whitespace at both ends - - TrimEdges - # Escape HTML characters for safety - - HTMLEscape # Add constraints to the field constraints: # Make sure it's a number @@ -378,10 +395,21 @@ to match: name: submit value: Submit - # Globally ensure that each field only specified one value + # Global filters and constraints. constraints: - # The user cannot leave any fields blank - - Required + # The user cannot leave any fields blank + - Required + # If not all fields are required, move the Required constraint to the + # fields that are + filter: + # Remove whitespace at both ends + - TrimEdges + # Escape HTML characters for safety + - HTMLEscape + +B Copying and pasting YAML from perl documentation is sometimes +tricky. See the L section of +this document for a more foolproof config format. The main changes are: @@ -452,12 +480,12 @@ bottom: # Get the form that the :FormConfig attribute saved in the stash my $form = $c->stash->{form}; - # Check if the form as been submitted (vs. displaying the initial - # form) and if the data based validation. "submitted_and_valid" + # Check if the form has been submitted (vs. displaying the initial + # form) and if the data passed validation. "submitted_and_valid" # is shorthand for "$form->submitted && !$form->has_errors" if ($form->submitted_and_valid) { # Save the form data for the book - $form->save_to_model($book); + $form->model->update($book); # Set a status message for the user $c->flash->{status_msg} = 'Book edited'; # Return to the books list @@ -476,7 +504,7 @@ bottom: # Add the authors to it $select->options(\@authors); # Populate the form with existing values from DB - $form->defaults_from_model($book); + $form->model->default_values($book); } # Set the template @@ -505,14 +533,14 @@ we set the error message and return to the book list. =item * If the form has been submitted and passes validation, we skip creating a -new book and just use C<$form-Esave_to_model> to update the existing +new book and just use C<$form-Emodel-Eupdate> to update the existing book. =item * If the form is being displayed for the first time (or has failed validation and it being redisplayed), we use - C<$form-Edefault_from_model> to populate the form with data from the + C<$form-Emodel-Edefault_values> to populate the form with data from the database. =back @@ -522,12 +550,18 @@ existing "Delete" link that allows us to edit/update each existing book. The last EtdE cell in the book list table should look like the following: + ... [% # Add a link to delete a book %] - Delete + Delete [% # Add a link to edit a book %] - Edit + Edit + ... + +B Only add two lines (the "Add a link to edit a book" comment +and the href for C). Make sure you add it below the +existing C link. =head2 Try Out the Edit/Update Feature @@ -545,6 +579,91 @@ 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 More Things to Try + +You are now armed with enough knowledge to be dangerous. You can keep +tweaking the example application; some things you might want to do: + +=over 4 + +=item * + +Add an appropriate ACL to the new Edit function. + +=item * + +Cleanup the List page so that the Login link only displays when the user +isn't logged in and the Logout link only displays when a user is logged +in. + +=item * + +Add a more sensible policy for when and how users and admins can do +things in the CRUD cycle. + +=item * + +Support the CRUD cycle for authors. + +=back + +Or you can proceed to write your own application, which is probably the +real reason you worked through this Tutorial in the first place. + +=head2 Config::General Config for this tutorial + +If you are having difficulty with YAML config above, please save the +below into the file C and delete the +C file. The below is in +L format which follows the syntax of +Apache config files. + + constraints Required + + + min 5 + max 40 + type Length + message Length must be between 5 and 40 characters + + filter TrimEdges + filter HTMLEscape + name title + type Text + label Title + + title Enter a book title here + + + + constraints Integer + filter TrimEdges + filter NonNumeric + name rating + type Text + label Rating + + title Enter a rating between 1 and 5 here + + + + constraints Integer + filter TrimEdges + filter HTMLEscape + name authors + type Select + label Author + multiple 1 + size 3 + + + value Submit + name submit + type Submit + + indicator submit + + =head1 AUTHOR @@ -552,8 +671,7 @@ Kennedy Clark, C Please report any errors, issues or suggestions to the author. The most recent version of the Catalyst Tutorial can be found at -L. +L. -Copyright 20066-2008, Kennedy Clark, under Creative Commons License -(L). - +Copyright 2006-2008, Kennedy Clark, under Creative Commons License +(L).