.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::Manual::Tutorial 3pm"
.TH Catalyst::Manual::Tutorial 3pm "2020-07-25" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Manual::Tutorial \- Catalyst Tutorial: Overview
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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.
.PP
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 \s-1CPAN\s0 modules like Pod::Webserver, Pod::POM::Web,
Pod::Browser (Catalyst based), or CPAN::Mini::Webserver to read a local
copy of the tutorial.
.PP
The tutorial is divided into the following sections:
.PP
\&\fB\s-1NOTE: CLICK THESE LINKS TO JUMP TO CHAPTERS\s0\fR (the index links above
only navigate inside this page).
.IP "1." 4
Introduction
.IP "2." 4
Catalyst Basics
.IP "3." 4
More Catalyst Basics
.IP "4." 4
Basic \s-1CRUD\s0
.IP "5." 4
Authentication
.IP "6." 4
Authorization
.IP "7." 4
Debugging
.IP "8." 4
Testing
.IP "9." 4
Advanced \s-1CRUD\s0
.IP "10." 4
Appendices
.PP
Final code tarballs for each chapter of the tutorial are available at
<http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/>.
.SH "Detailed Table of Contents"
.IX Header "Detailed Table of Contents"
.SS "Chapter 1: Intro"
.IX Subsection "Chapter 1: Intro"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL\s0
.IP "\(bu" 4
\&\s-1CATALYST INSTALLATION\s0
.IP "\(bu" 4
\&\s-1DATABASES\s0
.IP "\(bu" 4
\&\s-1WHERE TO GET WORKING CODE\s0
.SS "Chapter 2: Catalyst Basics"
.IX Subsection "Chapter 2: Catalyst Basics"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1CREATE A CATALYST PROJECT\s0
.IP "\(bu" 4
\&\s-1HELLO WORLD\s0
.RS 4
.IP "\(bu" 4
The Simplest Way
.IP "\(bu" 4
Hello, World! Using a View and a Template
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1CREATE A SIMPLE CONTROLLER AND AN ACTION\s0
.SS "Chapter 3: More Catalyst Basics"
.IX Subsection "Chapter 3: More Catalyst Basics"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1CREATE A NEW APPLICATION\s0
.IP "\(bu" 4
\&\s-1EDIT THE LIST OF CATALYST PLUGINS\s0
.IP "\(bu" 4
\&\s-1CREATE A CATALYST CONTROLLER\s0
.IP "\(bu" 4
\&\s-1CATALYST VIEWS\s0
.RS 4
.IP "\(bu" 4
Create a Catalyst View
.IP "\(bu" 4
Create a \s-1TT\s0 Template Page
.IP "\(bu" 4
Test Run The Application
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1CREATE A SQLITE DATABASE\s0
.IP "\(bu" 4
\&\s-1DATABASE ACCESS WITH\s0 DBIx::Class
.RS 4
.IP "\(bu" 4
Create a Dynamic \s-1DBIC\s0 Model
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1ENABLE THE MODEL IN THE CONTROLLER\s0
.RS 4
.IP "\(bu" 4
Test Run The Application
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1CREATE A WRAPPER FOR THE VIEW\s0
.RS 4
.IP "\(bu" 4
Configure \s-1TT\s0.pm For The Wrapper
.IP "\(bu" 4
Create the Wrapper Template File and Stylesheet
.IP "\(bu" 4
Test Run The Application
.RE
.RS 4
.RE
.IP "\(bu" 4
A \s-1STATIC DATABASE MODEL WITH\s0 DBIx::Class
.RS 4
.IP "\(bu" 4
Create Static \s-1DBIC\s0 Schema Files
.IP "\(bu" 4
Updating the Generated \s-1DBIC\s0 Schema Files
.IP "\(bu" 4
Run The Application
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1UPDATING THE VIEW\s0
.IP "\(bu" 4
\&\s-1RUNNING THE APPLICATION FROM THE COMMAND LINE\s0
.IP "\(bu" 4
\&\s-1OPTIONAL INFORMATION\s0
.RS 4
.IP "\(bu" 4
Using RenderView for the Default View
.IP "\(bu" 4
Using The Default Template Name
.IP "\(bu" 4
Return To A Manually-Specified Template
.RE
.RS 4
.RE
.SS "Chapter 4: Basic \s-1CRUD\s0"
.IX Subsection "Chapter 4: Basic CRUD"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1FORMLESS SUBMISSION\s0
.RS 4
.IP "\(bu" 4
Include a Create Action in the Books Controller
.IP "\(bu" 4
Include a Template for the url_create Action:
.IP "\(bu" 4
Try the url_create Feature
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1CONVERT TO A CHAINED ACTION\s0
.RS 4
.IP "\(bu" 4
Try the Chained Action
.IP "\(bu" 4
Refactor to Use a \*(L"Base\*(R" Method to Start the Chains
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1MANUALLY BUILDING A CREATE FORM\s0
.RS 4
.IP "\(bu" 4
Add a Method to Display the Form
.IP "\(bu" 4
Add a Template for the Form
.IP "\(bu" 4
Add Method to Process Form Values and Update Database
.IP "\(bu" 4
Test Out the Form
.RE
.RS 4
.RE
.IP "\(bu" 4
A \s-1SIMPLE DELETE FEATURE\s0
.RS 4
.IP "\(bu" 4
Include a Delete Link in the List
.IP "\(bu" 4
Add a Common Method to Retrieve a Book for the Chain
.IP "\(bu" 4
Add a Delete Action to the Controller
.IP "\(bu" 4
Try the Delete Feature
.IP "\(bu" 4
Fixing a Dangerous \s-1URL\s0
.IP "\(bu" 4
Try the Delete and Redirect Logic
.IP "\(bu" 4
Using uri_for to Pass Query Parameters
.IP "\(bu" 4
Try the Delete and Redirect With Query Param Logic
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1EXPLORING THE POWER OF DBIC\s0
.RS 4
.IP "\(bu" 4
Add Datetime Columns to Our Existing Books Table
.IP "\(bu" 4
Update \s-1DBIC\s0 to Automatically Handle the Datetime Columns
.IP "\(bu" 4
Create a ResultSet Class
.IP "\(bu" 4
Chaining ResultSets
.IP "\(bu" 4
Adding Methods to Result Classes
.RE
.RS 4
.RE
.SS "Chapter 5: Authentication"
.IX Subsection "Chapter 5: Authentication"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1BASIC AUTHENTICATION\s0
.RS 4
.IP "\(bu" 4
Add Users and Roles to the Database
.IP "\(bu" 4
Add User and Role Information to \s-1DBIC\s0 Schema
.IP "\(bu" 4
Sanity-Check Reload of Development Server
.IP "\(bu" 4
Include Authentication and Session Plugins
.IP "\(bu" 4
Configure Authentication
.IP "\(bu" 4
Add Login and Logout Controllers
.IP "\(bu" 4
Add a Login Form \s-1TT\s0 Template Page
.IP "\(bu" 4
Add Valid User Check
.IP "\(bu" 4
Displaying Content Only to Authenticated Users
.IP "\(bu" 4
Try Out Authentication
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1USING PASSWORD HASHES\s0
.RS 4
.IP "\(bu" 4
Get a \s-1SHA\-1\s0 Hash for the Password
.IP "\(bu" 4
Switch to \s-1SHA\-1\s0 Password Hashes in the Database
.IP "\(bu" 4
Enable \s-1SHA\-1\s0 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
.IP "\(bu" 4
Try Out the Hashed Passwords
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1USING THE SESSION FOR FLASH\s0
.RS 4
.IP "\(bu" 4
Try Out Flash
.IP "\(bu" 4
Switch To Flash-To-Stash
.RE
.RS 4
.RE
.SS "Chapter 6: Authorization"
.IX Subsection "Chapter 6: Authorization"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1BASIC AUTHORIZATION\s0
.RS 4
.IP "\(bu" 4
Update Plugins to Include Support for Authorization
.IP "\(bu" 4
Add Config Information for Authorization
.IP "\(bu" 4
Add Role-Specific Logic to the ``Book List'' Template
.IP "\(bu" 4
Limit Books::add to admin Users
.IP "\(bu" 4
Try Out Authentication And Authorization
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1ENABLE\s0 MODEL-BASED \s-1AUTHORIZATION\s0
.SS "Chapter 7: Debugging"
.IX Subsection "Chapter 7: Debugging"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1LOG STATEMENTS\s0
.IP "\(bu" 4
\&\s-1RUNNING CATALYST UNDER THE PERL DEBUGGER\s0
.IP "\(bu" 4
\&\s-1DEBUGGING MODULES FROM CPAN\s0
.IP "\(bu" 4
\&\s-1TT DEBUGGING\s0
.SS "Chapter 8: Testing"
.IX Subsection "Chapter 8: Testing"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1RUNNING THE \*(L"CANNED\*(R" CATALYST TESTS\s0
.IP "\(bu" 4
\&\s-1RUNNING A SINGLE TEST\s0
.IP "\(bu" 4
\&\s-1ADDING YOUR OWN TEST SCRIPT\s0
.IP "\(bu" 4
\&\s-1SUPPORTING BOTH PRODUCTION AND TEST DATABASES\s0
.SS "Chapter 9: Advanced \s-1CRUD\s0"
.IX Subsection "Chapter 9: Advanced CRUD"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1ADVANCED CRUD OPTIONS\s0
.SS "Chapter 10: Appendices"
.IX Subsection "Chapter 10: Appendices"
Note: Click on the heading in the previous line to jump to the actual
chapter. Below is a \*(L"table of contents\*(R" for this chapter.
.IP "\(bu" 4
\&\s-1APPENDIX 1: CUT AND PASTE FOR\s0 POD-BASED \s-1EXAMPLES\s0
.RS 4
.IP "\(bu" 4
\&\*(L"Un-indenting\*(R" with Vi/Vim
.IP "\(bu" 4
\&\*(L"Un-indenting\*(R" with Emacs
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1APPENDIX 2: USING MYSQL AND POSTGRESQL\s0
.RS 4
.IP "\(bu" 4
MySQL
.IP "\(bu" 4
PostgreSQL
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\s-1APPENDIX 3: IMPROVED HASHING SCRIPT\s0
.SH "THANKS"
.IX Header "THANKS"
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:
.IP "\(bu" 4
Sebastian Riedel for founding the Catalyst project.
.IP "\(bu" 4
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
\&\*(L"Auth & Authz\*(R" plugins (the original focus of the tutorial) and other
key Catalyst modules.
.IP "\(bu" 4
Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
and Jess Robinson (including their work on the original Catalyst
tutorial).
.IP "\(bu" 4
Kieren Diment for his oversight of Catalyst-related documentation.
.IP "\(bu" 4
Everyone on #catalyst and #catalyst\-dev.
.IP "\(bu" 4
Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the
PostgreSQL content in the Appendix.
.IP "\(bu" 4
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 \*(L"database
depluralization\*(R" 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).
.SH "AUTHOR"
.IX Header "AUTHOR"
Kennedy Clark, \f(CW\*(C`hkclark@gmail.com\*(C'\fR
.PP
Feel free to contact the author for any errors or suggestions, but the
best way to report issues is via the \s-1CPAN RT\s0 Bug system at
<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst\-Manual>.
.PP
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/>).