From: Kennedy Clark Date: Sun, 1 Jun 2008 03:02:45 +0000 (+0000) Subject: Initial update for AdvancedCRUD/FormFu.pod X-Git-Tag: v5.8005~290 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=cca5cd9814a4abf3f78f49065103f8db2b70a089 Initial update for AdvancedCRUD/FormFu.pod Add warning about StackTrace to MoreCatalystBasics.pod --- diff --git a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod index 38eab9b..ecee070 100644 --- a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod +++ b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod @@ -58,3 +58,248 @@ L =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. + +See +L +for additional form management options other than +L. + + +=head1 Install C + +If you are following along in Ubuntu, it turns out that C +is not yet available as a package at the time this was written. To +install it with a combination of C packages and traditional +CPAN modules, first use C to install most of the modules +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 + +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 + + +=head1 C FORM CREATION + +This section looks at how L can be used to +add additional functionality to the manually created form from Part 4. + + +=head2 Inherit From C + +First, change your C to inherit from +L +by changing the C line from the default of: + + use base 'Catalyst::Controller'; + +to use the FormFu base controller class: + + use base 'Catalyst::Controller::HTML::FormFu'; + + +=head2 Add Action to Display and Save the Form + +Open C in your editor and add the +following method: + + =head2 fu_form_create + + Build an HTML::FormFu form for book creation and updates + + =cut + + sub fu_form_create :Local :FormConfig { + my ($self, $c) = @_; + + # 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" + # 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); + # Set a status message for the user + $c->flash->{status_msg} = 'Book created'; + # Return to the books list + $c->response->redirect($c->uri_for('list')); + $c->detach; + } + # Set the template + $c->stash->{template} = 'books/fu_form_create.tt2'; + } + + +=head2 Create a Form Config File + +Although C supports any configuration file handled by +L, most people tend to use YAML. First +create a directory to hold your form configuration files: + + mkdir -p root/forms/books + +Then create the file C and enter the +following text: + + --- + indicator: submit + elements: + - type: Text + name: title + label: Title + attributes: + title: Enter a book title here + - type: Text + name: rating + label: Rating + attributes: + title: Enter a rating between 1 and 5 here + - type: Submit + name: submit + value: Submit + + +=head2 Update the CSS + +Edit C and add the following lines to the bottom of +the file: + + label { + display: block; + } + .submit { + display: block; + } + .error_messages { + color: [% site.col.error %]; + } + +These changes will display form elements vertically and also show error +messages in red. Note that we are pulling the color scheme settings +from the C file that was created by the TTSite +helper. This allows us to change the color used by various error styles +in the CSS from a single location. + + +=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::FormFu Form %] + [% form %] + +

Return to book list

+ + +=head2 Add Links for Create and Update via C + +Open C in your editor and add the following to +the bottom of the existing file: + +

+ HTML::FormFu: + Create +

+ + +=head2 Test The 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. Once at the Book List page, click the HTML::FormFu +"Create" link to display for form produced by C. Fill +out the form with the following values: Title = "Internetworking with +TCP/IP Vol. II", Rating = "4", and Author = "Comer". Click Submit, and +you will be returned to the Book List page with a "Book created" status +message displayed. + +Also note that this implementation allows you to can create books with +bogus information. Although we have constrained the authors with the +drop-down list, there are no restrictions on items such as the length of +the title (for example, you can create a one-letter title) and value for +the rating (you can use any number you want, and even non-numeric values +with SQLite). The next section will address this concern. + +B Depending on the database you are using and how you established +the columns in your tables, the database could obviously provide various +levels of "type enforcement" on your data. The key point being made in +the previous paragraph is that the I itself is not +performing any validation. + + +=head1 C VALIDATION AND FILTERING + +Although the use of L in the previous section +did provide an automated mechanism to build the form, the real power of +this module stems from functionality that can automatically validate and +filter the user input. Validation uses constraints to be sure that +users input appropriate data (for example, that the email field of a +form contains a valid email address). Filtering can be used to remove +extraneous whitespace from fields or to escape meta-characters in user +input. + +=head2 Add Constraints + + +Open C in your editor and update it +to match: + + --- + indicator: submit + elements: + - type: Text + name: title + label: Title + attributes: + title: Enter a book title here + constraints: + - Required + - type: Length + min: 2 + max: 30 + message: Length must be between 2 and 30 characters + - type: Text + name: rating + label: Rating + attributes: + title: Enter a rating between 1 and 5 here + constraints: + - Required + - Integer + - type: Submit + name: submit + value: Submit + constraints: + - SingleValue + +... + +=head1 AUTHOR + +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. + +Copyright 2006, Kennedy Clark, under Creative Commons License +(L). + \ No newline at end of file diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod index cc2fbd7..18be3fd 100644 --- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod +++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod @@ -208,6 +208,10 @@ Note: L output appears in your browser, not in the console window from which you're running your application, which is where logging output usually goes. +B You will want to disable +L before you put your +application into production, but it can be helpful during development. + =back Note that when specifying plugins on the C line, you can