X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial.pod;h=b9a21c3fc2e9a43bb5c43c64e0425a537ec45b9d;hp=7a4693997872ca83064e012a979b1c5a9c5fea6e;hb=4ab6212da7a5e07df9837b0e57fb2b0c37aa9759;hpb=d712b8268991d1d97723bda87975411c4f74263d diff --git a/lib/Catalyst/Manual/Tutorial.pod b/lib/Catalyst/Manual/Tutorial.pod index 7a46939..b9a21c3 100644 --- a/lib/Catalyst/Manual/Tutorial.pod +++ b/lib/Catalyst/Manual/Tutorial.pod @@ -11,56 +11,64 @@ commonly used features while focusing on real-world best practices. The tutorial is divided into the following sections: -B CLICK THESE LINKS TO JUMP TO CHAPTERS (the index links above +B (the index links above only navigate inside this page). =over 4 -=item * +=item 1 L -=item * +=item 2 L -=item * +=item 3 + +L + +=item 4 L -=item * +=item 5 L -=item * +=item 6 L -=item * +=item 7 L -=item * +=item 8 L -=item * +=item 9 L -=item * +=item 10 L =back -A tarball of the final application is available at -L. +Final code tarballs for each chapter of the tutorial are available at +L. =head1 Detailed Table of Contents -=head2 L + +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. =over 4 @@ -83,7 +91,10 @@ WHERE TO GET WORKING CODE =back -=head2 L +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. =over 4 @@ -93,33 +104,41 @@ CREATE A CATALYST PROJECT =item * -CREATE A SQLITE DATABASE +HELLO WORLD + +=over 4 =item * -EDIT THE LIST OF CATALYST PLUGINS +The Simplest Way =item * -DATABASE ACCESS WITH DBIx::Class - +Hello, World! Using a View and a Template -=over 4 +=back =item * -Create a DBIC Schema File +CREATE A SIMPLE CONTROLLER AND AN ACTION + +=back -=item * -Create the DBIC ``Result Source'' Files +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. + +=over 4 =item * -Use Catalyst::Model::DBIC::Schema to Load the Model Class +CREATE A NEW APPLICATION -=back +=item * +EDIT THE LIST OF CATALYST PLUGINS =item * @@ -134,358 +153,465 @@ CATALYST VIEWS =item * -Create a Catalyst View Using TTSite - -=item * - -Using RenderView for the Default View +Create a Catalyst View =item * -Globally Customize Every View +Create a TT Template Page =item * -Create a TT Template Page +Test Run The Application =back +=item * + +CREATE A SQLITE DATABASE =item * -RUN THE APPLICATION +DATABASE ACCESS WITH DBIx::Class + +=over 4 =item * -USING THE DEFAULT TEMPLATE NAME +Create a Dynamic DBIC Model =back -=head2 L +=item * + +ENABLE THE MODEL IN THE CONTROLLER =over 4 =item * -FORMLESS SUBMISSION +Test Run The Application + +=back + +=item * + +CREATE A WRAPPER FOR THE VIEW =over 4 =item * -Include a Create Action in the Books Controller +Configure TT.pm For The Wrapper =item * -Include a Template for the url_create Action: +Create the Wrapper Template File and Stylesheet =item * -Try the url_create Feature +Test Run The Application =back =item * -MANUALLY BUILDING A CREATE FORM +A STATIC DATABASE MODEL WITH DBIx::Class =over 4 =item * -Add a Method to Display the Form +Create Static DBIC Schema Files =item * -Add a Template for the Form +Updating the Generated DBIC Schema Files =item * -Add Method to Process Form Values and Update Database +Run The Application + +=back =item * -Test Out the Form +UPDATING THE VIEW -=back +=item * + +RUNNING THE APPLICATION FROM THE COMMAND LINE =item * -A SIMPLE DELETE FEATURE +OPTIONAL INFORMATION =over 4 =item * -Include a Delete Link in the List +Using RenderView for the Default View =item * -Add a Delete Action to the Controller +Using The Default Template Name =item * -Try the Delete Feature +Return To A Manually-Specified Template =back =back -=head2 L + +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. =over 4 =item * -BASIC AUTHENTICATION +FORMLESS SUBMISSION =over 4 =item * -Add Users and Roles to the Database +Include a Create Action in the Books Controller =item * -Add User and Role Information to DBIC Schema +Include a Template for the url_create Action: =item * -Create New ``Result Source Objects'' +Try the url_create Feature + +=back =item * -Sanity-Check Reload of Development Server +CONVERT TO A CHAINED ACTION + +=over 4 =item * -Include Authentication and Session Plugins +Try the Chained Action =item * -Configure Authentication +Refactor to Use a "Base" Method to Start the Chains + +=back =item * -Add Login and Logout Controllers +MANUALLY BUILDING A CREATE FORM + +=over 4 =item * -Add a Login Form TT Template Page +Add a Method to Display the Form =item * -Add Valid User Check +Add a Template for the Form =item * -Displaying Content Only to Authenticated Users +Add Method to Process Form Values and Update Database =item * -Try Out Authentication +Test Out the Form =back =item * -USING PASSWORD HASHES +A SIMPLE DELETE FEATURE =over 4 =item * -Get a SHA-1 Hash for the Password +Include a Delete Link in the List =item * -Switch to SHA-1 Password Hashes in the Database +Add a Common Method to Retrieve a Book for the Chain =item * -Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC +Add a Delete Action to the Controller =item * -Try Out the Hashed Passwords +Try the Delete Feature -=back +=item * -=back +Fixing a Dangerous URL -=head2 L +=item * -=over 4 +Try the Delete and Redirect Logic =item * -BASIC AUTHORIZATION +Using uri_for to Pass Query Parameters + +=item * + +Try the Delete and Redirect With Query Param Logic + +=back + +=item * + +EXPLORING THE POWER OF DBIC =over 4 =item * -Update Plugins to Include Support for Authorization +Add Datetime Columns to Our Existing Books Table =item * -Add Config Information for Authorization +Update DBIC to Automatically Handle the Datetime Columns =item * -Add Role-Specific Logic to the ``Book List'' Template +Create a ResultSet Class =item * -Limit Books::add to admin Users +Chaining ResultSets =item * -Try Out Authentication And Authorization +Adding Methods to Result Classes + +=back =back + +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. + +=over 4 + =item * -ENABLE ACL-BASED AUTHORIZATION +BASIC AUTHENTICATION =over 4 =item * -Add the Catalyst::Plugin::Authorization::ACL Plugin +Add Users and Roles to the Database =item * -Add ACL Rules to the Application Class +Add User and Role Information to DBIC Schema =item * -Add a Method to Handle Access Violations +Sanity-Check Reload of Development Server -=back +=item * -=back +Include Authentication and Session Plugins -=head2 L +=item * -=over 4 +Configure Authentication =item * -LOG STATEMENTS +Add Login and Logout Controllers =item * -RUNNING CATALYST UNDER THE PERL DEBUGGER +Add a Login Form TT Template Page =item * -DEBUGGING MODULES FROM CPAN +Add Valid User Check + +=item * + +Displaying Content Only to Authenticated Users + +=item * + +Try Out Authentication =back -=head2 L +=item * + +USING PASSWORD HASHES =over 4 =item * -RUNNING THE "CANNED" CATALYST TESTS +Get a SHA-1 Hash for the Password =item * -RUNNING A SINGLE TEST +Switch to SHA-1 Password Hashes in the Database =item * -ADDING YOUR OWN TEST SCRIPT +Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC =item * -SUPPORTING BOTH PRODUCTION AND TEST DATABASES +Try Out the Hashed Passwords =back -=head2 L +=item * + +USING THE SESSION FOR FLASH =over 4 =item * -HTML::WIDGET FORM CREATION +Try Out Flash + +=item * + +Switch To Flash-To-Stash + +=back + +=back + + +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. =over 4 =item * -Add the HTML::Widget Plugin +BASIC AUTHORIZATION + +=over 4 =item * -Add a Form Creation Helper Method +Update Plugins to Include Support for Authorization =item * -Add Actions to Display and Save the Form +Add Config Information for Authorization =item * -Update the CSS +Add Role-Specific Logic to the ``Book List'' Template =item * -Create a Template Page To Display The Form +Limit Books::add to admin Users =item * -Add Links for Create and Update via HTML::Widget +Try Out Authentication And Authorization + +=back =item * -Test The Create Form +ENABLE MODEL-BASED AUTHORIZATION =back -=item * -HTML::WIDGET VALIDATION AND FILTERING +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. =over 4 =item * -Add Constraints and Filters to the Widget Creation Method +LOG STATEMENTS =item * -Rebuild the Form Submission Method to Include Validation +RUNNING CATALYST UNDER THE PERL DEBUGGER =item * -Try Out the Form +DEBUGGING MODULES FROM CPAN + +=item * + +TT DEBUGGING =back -=item * -Enable DBIx::Class::HTMLWidget Support +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. =over 4 =item * -Add DBIx::Class::HTMLWidget to DBIC Model +RUNNING THE "CANNED" CATALYST TESTS + +=item * + +RUNNING A SINGLE TEST + +=item * + +ADDING YOUR OWN TEST SCRIPT =item * -Use populate_from_widget in hw_create_do +SUPPORTING BOTH PRODUCTION AND TEST DATABASES =back + +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. + +=over 4 + +=item * + +ADVANCED CRUD OPTIONS + =back -=head2 L + +=head2 L + +Note: Click on the heading in the previous line to jump to the actual +chapter. Below is a "table of contents" for this chapter. =over 4 @@ -557,7 +683,11 @@ key Catalyst modules. Other Catalyst documentation folks like Kieren Diment, Gavin Henry, and Jess Robinson (including their work on the original Catalyst -tutorial). +tutorial). + +=item * + +Kieren Diment for his oversite of Catalyst-related documentation. =item * @@ -565,11 +695,20 @@ Everyone on #catalyst and #catalyst-dev. =item * +Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the +PostgreSQL content in the Appendix. + +=item * + People who have emailed me with corrections and suggestions on the -tutorial. As of the most recent release, this include: Florian Ragwitz, -Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno, -Bryan Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning Sprang, -Jeremy Jones, David Kurtz, and Ingo Wichmann. +tutorial. As of the most recent release, this include: Florian +Ragwitz, Mauro Andreolini, Jim Howard, Giovanni Gigante, William +Moreno, Bryan Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning +Sprang, Jeremy Jones, David Kurtz, Ingo Wichmann, Shlomi Fish, Murray +Walker. Also, thanks to Devin Austin for coming up with an initial +version of a non-TTSite wrapper page. I'm sure I am missing some +names here... apologies for that (please let me know if you name +should be here). =back @@ -579,7 +718,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 2006, Kennedy Clark, under Creative Commons License +Copyright 2006-2008, Kennedy Clark, under Creative Commons License (L).