From: Matt S Trout Date: Thu, 8 Jun 2006 14:38:31 +0000 (+0000) Subject: Tut docs work X-Git-Tag: 5.7099_04~528 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3c098c712dbc92de8efb97acf71772b439956cd9;p=catagits%2FCatalyst-Runtime.git Tut docs work r9737@cain (orig r4286): jester | 2006-06-05 03:24:16 +0000 --- diff --git a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod index 22f562b..4543178 100644 --- a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod +++ b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod @@ -2,8 +2,6 @@ Catalyst::Manual::Tutorial::AdvancedCRUD - Catalyst Tutorial - Part 8: Advanced CRUD - - =head1 OVERVIEW This is B for the Catalyst tutorial. @@ -46,12 +44,10 @@ B =item 9 -L +L =back - - =head1 DESCRIPTION This part of the tutorial explores more advanced functionality for @@ -64,23 +60,22 @@ forms and model objects. In keeping with the Catalyst (and Perl) spirit of flexibility, there are many different ways approach advanced CRUD operations in a Catalyst environment. One alternative is to use -L -to instantly construct a set of Controller methods and templates for -basic CRUD operations. Although a popular subject in Quicktime movies -that serve as promotional material for various frameworks, more -real-world applications require more control. Other options include -L and -L. - -Here, we will make use of the L to not only -ease form creation, but to also provide validation of the submitted -data. The approached used by the part of the tutorial is to slowly -incorporate additional L functionality in a -step-wise fashion (we start with fairly simple form creation and then -move on to more complex and "magical" features such as validation and +L to instantly construct a set +of Controller methods and templates for basic CRUD operations. Although +a popular subject in Quicktime movies that serve as promotional material +for various frameworks, more real-world applications require more +control. Other options include L and +L. + +Here, we will make use of the L to not only ease form +creation, but to also provide validation of the submitted data. The +approached used by the part of the tutorial is to slowly incorporate +additional L functionality in a step-wise fashion (we +start with fairly simple form creation and then move on to more complex +and "magical" features such as validation and auto-population/auto-saving). -B Part 8 of the tutorial is optional. Users who do not which to +B Part 8 of the tutorial is optional. Users who do not wish to use L may skip this section. B: Note that all of the code for this part of the tutorial can be @@ -90,22 +85,18 @@ following command: svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@### IMPORTANT: Does not work yet. Will be completed for final version. - - =head1 C FORM CREATION -This section looks at how L can be used to +This section looks at how L can be used to add additional functionality to the manually created form from Part 3. - =head2 Add the C Plugin Open C in your editor and add the following to the list of -plugins (be sure to leave the existing plugins enabled: +plugins (be sure to leave the existing plugins enabled): HTML::Widget - =head2 Add a Form Creation Helper Method Open C in your editor and add the @@ -140,13 +131,11 @@ following method: } This method provides a central location (so it can be called by multiple -actions, such as create and edit) that builds an HTML::Wiget-based form -with the appropriate fields. The "Get Authors" code uses DBIC to -retrieve a list of model objects and then uses C to quickly create -a hash where the hash keys are the database primary keys from the -authors table and the associated values are the last names of the -authors. - +actions, such as C and C) that builds an HTML::Wiget-based +form with the appropriate fields. The "Get Authors" code uses DBIC to +retrieve a list of model objects and then uses C to create a hash +where the hash keys are the database primary keys from the authors table +and the associated values are the last names of the authors. =head2 Add Actions to Display and Save the Form @@ -214,7 +203,6 @@ so allows us to have the same form submit the data to different actions (e.g., C for a create operation but C to update an existing book object). - =head2 Update the CSS Edit C and add the following lines to the bottom of @@ -245,8 +233,7 @@ 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 CCS from a single location. - +in the CSS from a single location. =head2 Create a Template Page To Display The Form @@ -257,7 +244,6 @@ C

Return to book list

- =head2 Add Links for Create and Update via C Open C in your editor and add the following to @@ -269,7 +255,6 @@ the bottom of the existing file: Update

- =head2 Test The Create Form Press C to kill the previous server instance (if it's still @@ -290,7 +275,7 @@ 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 seeks to address this concern. +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 @@ -298,7 +283,6 @@ 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 @@ -310,7 +294,6 @@ 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 and Filters to the Widget Creation Method Open C in your editor and update the @@ -376,7 +359,6 @@ Two filters are run on every field to remove and escape unwanted input. =back - =head2 Rebuild the Form Submission Method to Include Validation Edit C and change C to @@ -463,7 +445,6 @@ similar to the prior version of the C method. =back - =head2 Try Out the Form Press C to kill the previous server instance (if it's still running) and restart it: @@ -476,7 +457,6 @@ two, and zero authors. When you click Submit, the HTML::Widget C items will validate the logic and insert feedback as appropriate. - =head1 Enable C Support In this section we will take advantage of some of the "auto-population" @@ -504,7 +484,6 @@ records in the database. In other words, the two methods are a mirror image of each other: one reads from the database while the other writes to the database. - =head2 Add C to DBIC Model In order to use L, we @@ -515,7 +494,6 @@ C and update the C line to match: __PACKAGE__->load_components(qw/PK::Auto Core HTMLWidget/); - =head2 Use C in C Edit C and update C to @@ -576,8 +554,6 @@ have to call C<$book-Eadd_to_book_authors> once per author because C does not currently handle the relationships between tables. - - =head1 AUTHOR Kennedy Clark, C @@ -586,7 +562,8 @@ Please report any errors, issues or suggestions to the author. Copyright 2006, Kennedy Clark. All rights reserved. -This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. +This library is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. Version: .94 diff --git a/lib/Catalyst/Manual/Tutorial/Appendices.pod b/lib/Catalyst/Manual/Tutorial/Appendices.pod index c408e82..a28e787 100644 --- a/lib/Catalyst/Manual/Tutorial/Appendices.pod +++ b/lib/Catalyst/Manual/Tutorial/Appendices.pod @@ -45,26 +45,21 @@ L =item 9 -B +B =back - - =head1 DESCRIPTION This part of the tutorial provides supporting information relevant to the Catalyst tutorial. - - =head1 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES You may notice that Pod indents example code with four spaces. This section provides some quick advice to "un-indent" this text in common editors. - =head2 "Un-indenting" with Vi/Vim When cutting and pasting multi-line text from Pod-based documents, the @@ -97,13 +92,10 @@ Removes four leading space from the current line through line 44 =back - =head2 "Un-indenting" with Emacs B - - =head1 APPENDIX 2: USING MYSQL AND POSTGRESQL The main database used in this tutorial is the very simple yet powerful @@ -121,7 +113,6 @@ section are not designed to take maximum advantage of the various features in each database for issues such as referential integrity and field types/constraints. - =head2 MySQL B diff --git a/lib/Catalyst/Manual/Tutorial/Testing.pod b/lib/Catalyst/Manual/Tutorial/Testing.pod index c8ea930..527d42e 100644 --- a/lib/Catalyst/Manual/Tutorial/Testing.pod +++ b/lib/Catalyst/Manual/Tutorial/Testing.pod @@ -2,8 +2,6 @@ Catalyst::Manual::Tutorial::Testing - Catalyst Tutorial - Part 7: Testing - - =head1 OVERVIEW This is B for the Catalyst tutorial. @@ -46,21 +44,18 @@ L =item 9 -L +L =back - - =head1 DESCRIPTION - You may have noticed that the Catalyst Helper scripts automatically -create C<.t> test scripts under the C directory. This part of the -tutorial briefly looks at how these tests can be used to not only ensure -that your application is working correctly at the present time, but also -provide automated regression testing as you upgrade various pieces of -your application over time. +create basic C<.t> test scripts under the C directory. This part of +the tutorial briefly looks at how these tests can be used to not only +ensure that your application is working correctly at the present time, +but also provide automated regression testing as you upgrade various +pieces of your application over time. B: Note that all of the code for this part of the tutorial can be pulled from the Catalyst Subversion repository in one step with the @@ -70,7 +65,6 @@ following command: IMPORTANT: Does not work yet. Will be completed for final version. - =head1 RUNNING THE "CANNED" CATALYST TESTS There are a variety of ways to run Catalyst and Perl tests (for example, @@ -106,7 +100,7 @@ Although you can edit the C to comment out the C<-Debug> plugin, it's generally easier to simply set the C environment variable. For example: - CATALYST_DEBUG=0 prove --lib lib t + $ CATALYST_DEBUG=0 prove --lib lib t During the C and C tests, you might notice the C warning message. To @@ -124,8 +118,6 @@ prints the name of each test case as it is being run: $ CATALYST_DEBUG=0 TEST_POD=1 prove --lib lib -v t - - =head1 RUNNING A SINGLE TEST You can also run a single script by appending its name to the C @@ -138,19 +130,17 @@ For example: $ CATALYST_DEBUG=0 perl -Ilib t/01app.t - =head1 ADDING YOUR OWN TEST SCRIPT Although the Catalyst helper scripts provide a basic level of checks "for free," testing can become significantly more helpful when you write your own script to exercise the various parts of your application. The -L module -is very popular for writing these sorts of test cases. This module -extends L (and therefore -L) to allow you to automate the action of +L module is very popular for writing +these sorts of test cases. This module extends L +(and therefore L) to allow you to automate the action of a user "clicking around" inside your application. It gives you all the benefits of testing on a live system without the messiness of having to -use an actual web server. +use an actual web server, and a real person to do the clicking. To create a sample test case, open the C file in your editor and enter the following: @@ -160,17 +150,19 @@ editor and enter the following: use strict; use warnings; - # Load testing framework and use 'no_plan' to dynamically pick up all tests. Better - # to replace "'no_plan'" with "tests => 30" so it knows exactly how many tests need - # to be run (and will tell you if not), but 'no_plan' is nice for quick & dirty tests + # Load testing framework and use 'no_plan' to dynamically pick up + # all tests. Better to replace "'no_plan'" with "tests => 30" so it + # knows exactly how many tests need to be run (and will tell you if + # not), but 'no_plan' is nice for quick & dirty tests + use Test::More 'no_plan'; # Need to specify the name of your app as arg on next line # Can also do: # use Test::WWW::Mechanize::Catalyst "MyApp"; + use ok "Test::WWW::Mechanize::Catalyst" => "MyApp"; - - + # Create two 'user agents' to simulate two different users ('test01' & 'test02') my $ua1 = Test::WWW::Mechanize::Catalyst->new; my $ua2 = Test::WWW::Mechanize::Catalyst->new; @@ -249,14 +241,12 @@ editor and enter the following: The C test cases uses copious comments to explain each step of the process. In addition to the techniques shown here, there are a -variety of other methods available in -L (for -example, regex-based matching). Consult the documentation for more +variety of other methods available in L +(for example, regex-based matching). Consult the documentation for more detail. B: For I vs. the "full application tests" approach used -by L, see -L. +by L, see L. B The test script does not test the C and C actions. That is left as an exercise for the reader @@ -274,25 +264,23 @@ or Experiment with the C, C and C<-v> settings. If you find that there are errors, use the techniques discussed in the "Catalyst Debugging" section (Part 6) to -isolate and fix the problem. +isolate and fix any problems. If you want to run the test case under the Perl interactive debugger, try a command such as: $ DBIX_CLASS_STORAGE_DBI_DEBUG=0 CATALYST_DEBUG=0 perl -d -Ilib t/live_app01.t -Note that although the tutorial uses a single custom test case for +Note that although this tutorial uses a single custom test case for simplicity, you may wish to break your tests into different files for better organization. - - =head1 SUPPORTING BOTH PRODUCTION AND TEST DATABASES You may wish to leverage the techniques discussed in this tutorial to maintain both a "production database" for your live application and a "testing database" for your test cases. One advantage to -L is that +L is that it runs your full application; however, this can complicate things when you want to support multiple databases. One solution is to allow the database specification to be overridden with an environment variable. @@ -321,8 +309,6 @@ launch your normal application without the C environment variable defined, it will default to the same C as before. - - =head1 AUTHOR Kennedy Clark, C