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=5e6326940b22c9ddd42a80317b7525cbba15e8cb;hp=f6db547dc95f0ebfb7e5ed2d2398c7588d231fb5;hb=af20a15d7f4089fabd2e4e9bb161f2d2de50f333;hpb=a300559cabca3e1a60cc90e5a68eefe8ab4bc3ac diff --git a/lib/Catalyst/Manual/Tutorial.pod b/lib/Catalyst/Manual/Tutorial.pod index f6db547..5e63269 100644 --- a/lib/Catalyst/Manual/Tutorial.pod +++ b/lib/Catalyst/Manual/Tutorial.pod @@ -9,58 +9,73 @@ quickly building high-functionality web applications. This tutorial is designed to provide a rapid introduction to its basics and its most commonly used features while focusing on real-world best practices. +We suggest that you read this introduction on the web. Make sure you are +reading the latest version of the tutorial by visiting +L. Alternatively +you can use CPAN modules like L, L, +L (Catalyst based), or L to read a local +copy of the tutorial. + 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 +L -=item * +=item 2 -L +L -=item * +=item 3 -L +L -=item * +=item 4 -L +L -=item * +=item 5 -L +L -=item * +=item 6 -L +L -=item * +=item 7 + +L -L +=item 8 -=item * +L -L +=item 9 -=item * +L -L +=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 +98,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 +111,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 -=item * +=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. -Create the DBIC ``Result Source'' Files +=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 +160,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 +690,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 +702,23 @@ 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, Ingo Wichmann, and Shlomi Fish. +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, Adam Witney and xenoterracide. Thanks to Devin Austin for +coming up with an initial version of a non-TTSite wrapper page. +Also, a huge thank you to Kiffin Gish for all the hard work on the +"database depluralization" effort and Rafael Kitover for the work on +updating the tutorial to include foreign key support for SQLite. +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 +728,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).