3 Catalyst::Manual::Tutorial - Catalyst Tutorial: Overview
7 The Catalyst framework is a flexible and comprehensive environment for
8 quickly building high-functionality web applications. This tutorial is
9 designed to provide a rapid introduction to its basics and its most
10 commonly used features while focusing on real-world best practices.
12 We suggest that you read this introduction on the web. Make sure you are
13 reading the latest version of the tutorial by visiting
14 L<http://search.cpan.org/perldoc?Catalyst::Manual::Tutorial>. Alternatively
15 you can use CPAN modules like L<Pod::Webserver>, L<Pod::POM::Web>,
16 L<Pod::Browser> (Catalyst based), or L<CPAN::Mini::Webserver> to read a local
19 The tutorial is divided into the following sections:
21 B<NOTE: CLICK THESE LINKS TO JUMP TO CHAPTERS> (the index links above
22 only navigate inside this page).
28 L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
32 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
36 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
40 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
44 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
48 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
52 L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
56 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
60 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
64 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
68 Final code tarballs for each chapter of the tutorial are available at
69 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/>.
72 =head1 Detailed Table of Contents
75 =head2 L<Chapter 1: Intro|Catalyst::Manual::Tutorial::01_Intro>
77 Note: Click on the heading in the previous line to jump to the actual
78 chapter. Below is a "table of contents" for this chapter.
84 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
96 WHERE TO GET WORKING CODE
101 =head2 L<Chapter 2: Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
103 Note: Click on the heading in the previous line to jump to the actual
104 chapter. Below is a "table of contents" for this chapter.
110 CREATE A CATALYST PROJECT
124 Hello, World! Using a View and a Template
130 CREATE A SIMPLE CONTROLLER AND AN ACTION
135 =head2 L<Chapter 3: More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
137 Note: Click on the heading in the previous line to jump to the actual
138 chapter. Below is a "table of contents" for this chapter.
144 CREATE A NEW APPLICATION
148 EDIT THE LIST OF CATALYST PLUGINS
152 CREATE A CATALYST CONTROLLER
163 Create a Catalyst View
167 Create a TT Template Page
171 Test Run The Application
177 CREATE A SQLITE DATABASE
181 DATABASE ACCESS WITH DBIx::Class
187 Create a Dynamic DBIC Model
193 ENABLE THE MODEL IN THE CONTROLLER
199 Test Run The Application
205 CREATE A WRAPPER FOR THE VIEW
211 Configure TT.pm For The Wrapper
215 Create the Wrapper Template File and Stylesheet
219 Test Run The Application
225 A STATIC DATABASE MODEL WITH DBIx::Class
231 Create Static DBIC Schema Files
235 Updating the Generated DBIC Schema Files
249 RUNNING THE APPLICATION FROM THE COMMAND LINE
259 Using RenderView for the Default View
263 Using The Default Template Name
267 Return To A Manually-Specified Template
274 =head2 L<Chapter 4: Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
276 Note: Click on the heading in the previous line to jump to the actual
277 chapter. Below is a "table of contents" for this chapter.
289 Include a Create Action in the Books Controller
293 Include a Template for the url_create Action:
297 Try the url_create Feature
303 CONVERT TO A CHAINED ACTION
309 Try the Chained Action
313 Refactor to Use a "Base" Method to Start the Chains
319 MANUALLY BUILDING A CREATE FORM
325 Add a Method to Display the Form
329 Add a Template for the Form
333 Add Method to Process Form Values and Update Database
343 A SIMPLE DELETE FEATURE
349 Include a Delete Link in the List
353 Add a Common Method to Retrieve a Book for the Chain
357 Add a Delete Action to the Controller
361 Try the Delete Feature
365 Fixing a Dangerous URL
369 Try the Delete and Redirect Logic
373 Using uri_for to Pass Query Parameters
377 Try the Delete and Redirect With Query Param Logic
383 EXPLORING THE POWER OF DBIC
389 Add Datetime Columns to Our Existing Books Table
393 Update DBIC to Automatically Handle the Datetime Columns
397 Create a ResultSet Class
405 Adding Methods to Result Classes
412 =head2 L<Chapter 5: Authentication|Catalyst::Manual::Tutorial::05_Authentication>
414 Note: Click on the heading in the previous line to jump to the actual
415 chapter. Below is a "table of contents" for this chapter.
427 Add Users and Roles to the Database
431 Add User and Role Information to DBIC Schema
435 Sanity-Check Reload of Development Server
439 Include Authentication and Session Plugins
443 Configure Authentication
447 Add Login and Logout Controllers
451 Add a Login Form TT Template Page
459 Displaying Content Only to Authenticated Users
463 Try Out Authentication
469 USING PASSWORD HASHES
475 Get a SHA-1 Hash for the Password
479 Switch to SHA-1 Password Hashes in the Database
483 Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
487 Try Out the Hashed Passwords
493 USING THE SESSION FOR FLASH
503 Switch To Flash-To-Stash
510 =head2 L<Chapter 6: Authorization|Catalyst::Manual::Tutorial::06_Authorization>
512 Note: Click on the heading in the previous line to jump to the actual
513 chapter. Below is a "table of contents" for this chapter.
525 Update Plugins to Include Support for Authorization
529 Add Config Information for Authorization
533 Add Role-Specific Logic to the ``Book List'' Template
537 Limit Books::add to admin Users
541 Try Out Authentication And Authorization
547 ENABLE MODEL-BASED AUTHORIZATION
552 =head2 L<Chapter 7: Debugging|Catalyst::Manual::Tutorial::07_Debugging>
554 Note: Click on the heading in the previous line to jump to the actual
555 chapter. Below is a "table of contents" for this chapter.
565 RUNNING CATALYST UNDER THE PERL DEBUGGER
569 DEBUGGING MODULES FROM CPAN
578 =head2 L<Chapter 8: Testing|Catalyst::Manual::Tutorial::08_Testing>
580 Note: Click on the heading in the previous line to jump to the actual
581 chapter. Below is a "table of contents" for this chapter.
587 RUNNING THE "CANNED" CATALYST TESTS
591 RUNNING A SINGLE TEST
595 ADDING YOUR OWN TEST SCRIPT
599 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
604 =head2 L<Chapter 9: Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
606 Note: Click on the heading in the previous line to jump to the actual
607 chapter. Below is a "table of contents" for this chapter.
613 ADVANCED CRUD OPTIONS
618 =head2 L<Chapter 10: Appendices|Catalyst::Manual::Tutorial::10_Appendices>
620 Note: Click on the heading in the previous line to jump to the actual
621 chapter. Below is a "table of contents" for this chapter.
627 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
633 "Un-indenting" with Vi/Vim
637 "Un-indenting" with Emacs
643 APPENDIX 2: USING MYSQL AND POSTGRESQL
659 APPENDIX 3: IMPROVED HASHING SCRIPT
666 This tutorial would not have been possible without the input of many
667 different people in the Catalyst community. In particular, the
668 primary author would like to thank:
674 Sebastian Riedel for founding the Catalyst project.
678 The members of the Catalyst Core Team for their tireless efforts to
679 advance the Catalyst project. Although all of the Core Team members
680 have played a key role in this tutorial, it would have never been
681 possible without the critical contributions of: Matt Trout, for his
682 unfathomable knowledge of all things Perl and Catalyst (and his
683 willingness to answer lots of my questions); Jesse Sheidlower, for his
684 incredible skill with the written word and dedication to improving the
685 Catalyst documentation; and Yuval Kogman, for his work on the Catalyst
686 "Auth & Authz" plugins (the original focus of the tutorial) and other
687 key Catalyst modules.
691 Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
692 and Jess Robinson (including their work on the original Catalyst
697 Kieren Diment for his oversite of Catalyst-related documentation.
701 Everyone on #catalyst and #catalyst-dev.
705 Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the
706 PostgreSQL content in the Appendix.
710 People who have emailed me with corrections and suggestions on the
711 tutorial. As of the most recent release, this include: Florian
712 Ragwitz, Mauro Andreolini, Jim Howard, Giovanni Gigante, William
713 Moreno, Bryan Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning
714 Sprang, Jeremy Jones, David Kurtz, Ingo Wichmann, Shlomi Fish, Murray
715 Walker and Adam Witney. Thanks to Devin Austin for coming up with an
716 initial version of a non-TTSite wrapper page. Also, a huge thank you
717 to Kiffin Gish for all the hard work on the "database depluralization"
718 effort! I'm sure I am missing some names here... apologies for that
719 (please let me know if you name should be here).
725 Kennedy Clark, C<hkclark@gmail.com>
727 Please report any errors, issues or suggestions to the author. The
728 most recent version of the Catalyst Tutorial can be found at
729 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
731 Copyright 2006-2008, Kennedy Clark, under Creative Commons License
732 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).