Catalyst::Manual::Tutorial - Catalyst Tutorial: Overview
The Catalyst framework is a flexible and comprehensive environment for 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 Catalyst::Manual::Tutorial. Alternatively you can use CPAN modules like Pod::Webserver, Pod::POM::Web, Pod::Browser (Catalyst based), or CPAN::Mini::Webserver to read a local copy of the tutorial.
The tutorial is divided into the following sections:
NOTE: CLICK THESE LINKS TO JUMP TO CHAPTERS (the index links above only navigate inside this page).
Final code tarballs for each chapter of the tutorial are available at http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/.
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
CATALYST INSTALLATION
DATABASES
WHERE TO GET WORKING CODE
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 A CATALYST PROJECT
HELLO WORLD
The Simplest Way
Hello, World! Using a View and a Template
CREATE A SIMPLE CONTROLLER AND AN ACTION
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 A NEW APPLICATION
EDIT THE LIST OF CATALYST PLUGINS
CREATE A CATALYST CONTROLLER
CATALYST VIEWS
Create a Catalyst View
Create a TT Template Page
Test Run The Application
CREATE A SQLITE DATABASE
DATABASE ACCESS WITH DBIx::Class
Create a Dynamic DBIC Model
ENABLE THE MODEL IN THE CONTROLLER
Test Run The Application
CREATE A WRAPPER FOR THE VIEW
Configure TT.pm For The Wrapper
Create the Wrapper Template File and Stylesheet
Test Run The Application
A STATIC DATABASE MODEL WITH DBIx::Class
Create Static DBIC Schema Files
Updating the Generated DBIC Schema Files
Run The Application
UPDATING THE VIEW
RUNNING THE APPLICATION FROM THE COMMAND LINE
OPTIONAL INFORMATION
Using RenderView for the Default View
Using The Default Template Name
Return To A Manually-Specified Template
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
FORMLESS SUBMISSION
Include a Create Action in the Books Controller
Include a Template for the url_create Action:
Try the url_create Feature
CONVERT TO A CHAINED ACTION
Try the Chained Action
Refactor to Use a "Base" Method to Start the Chains
MANUALLY BUILDING A CREATE FORM
Add a Method to Display the Form
Add a Template for the Form
Add Method to Process Form Values and Update Database
Test Out the Form
A SIMPLE DELETE FEATURE
Include a Delete Link in the List
Add a Common Method to Retrieve a Book for the Chain
Add a Delete Action to the Controller
Try the Delete Feature
Fixing a Dangerous URL
Try the Delete and Redirect Logic
Using uri_for to Pass Query Parameters
Try the Delete and Redirect With Query Param Logic
EXPLORING THE POWER OF DBIC
Add Datetime Columns to Our Existing Books Table
Update DBIC to Automatically Handle the Datetime Columns
Create a ResultSet Class
Chaining ResultSets
Adding Methods to Result Classes
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
BASIC AUTHENTICATION
Add Users and Roles to the Database
Add User and Role Information to DBIC Schema
Sanity-Check Reload of Development Server
Include Authentication and Session Plugins
Configure Authentication
Add Login and Logout Controllers
Add a Login Form TT Template Page
Add Valid User Check
Displaying Content Only to Authenticated Users
Try Out Authentication
USING PASSWORD HASHES
Get a SHA-1 Hash for the Password
Switch to SHA-1 Password Hashes in the Database
Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
Try Out the Hashed Passwords
USING THE SESSION FOR FLASH
Try Out Flash
Switch To Flash-To-Stash
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
BASIC AUTHORIZATION
Update Plugins to Include Support for Authorization
Add Config Information for Authorization
Add Role-Specific Logic to the ``Book List'' Template
Limit Books::add to admin Users
Try Out Authentication And Authorization
ENABLE MODEL-BASED AUTHORIZATION
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
LOG STATEMENTS
RUNNING CATALYST UNDER THE PERL DEBUGGER
DEBUGGING MODULES FROM CPAN
TT DEBUGGING
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
RUNNING THE "CANNED" CATALYST TESTS
RUNNING A SINGLE TEST
ADDING YOUR OWN TEST SCRIPT
SUPPORTING BOTH PRODUCTION AND TEST DATABASES
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
ADVANCED CRUD OPTIONS
Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter.
APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
"Un-indenting" with Vi/Vim
"Un-indenting" with Emacs
APPENDIX 2: USING MYSQL AND POSTGRESQL
MySQL
PostgreSQL
APPENDIX 3: IMPROVED HASHING SCRIPT
This tutorial would not have been possible without the input of many different people in the Catalyst community. In particular, the primary author would like to thank:
Sebastian Riedel for founding the Catalyst project.
The members of the Catalyst Core Team for their tireless efforts to advance the Catalyst project. Although all of the Core Team members have played a key role in this tutorial, it would have never been possible without the critical contributions of: Matt Trout, for his unfathomable knowledge of all things Perl and Catalyst (and his willingness to answer lots of my questions); Jesse Sheidlower, for his incredible skill with the written word and dedication to improving the Catalyst documentation; and Yuval Kogman, for his work on the Catalyst "Auth & Authz" plugins (the original focus of the tutorial) and other key Catalyst modules.
Other Catalyst documentation folks like Kieren Diment, Gavin Henry, and Jess Robinson (including their work on the original Catalyst tutorial).
Kieren Diment for his oversight of Catalyst-related documentation.
Everyone on #catalyst and #catalyst-dev.
Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the PostgreSQL content in the Appendix.
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, Shlomi Fish, Murray Walker, Adam Witney and xenoterracide (Caleb Cushing). 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).
Kennedy Clark, hkclark@gmail.com
Feel free to contact the author for any errors or suggestions, but the best way to report issues is via the CPAN RT Bug system at https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual.
Copyright 2006-2010, Kennedy Clark, under the Creative Commons Attribution Share-Alike License Version 3.0 (https://creativecommons.org/licenses/by-sa/3.0/us/).