=head1 NAME
-Catalyst::Manual::Tutorial - Getting started with Catalyst
+Catalyst::Manual::Tutorial - Catalyst Tutorial: Overview
=head1 DESCRIPTION
-This document aims to get you up and running with Catalyst.
+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.
-NOTE: THIS DOCUMENT IS STILL VERY MUCH AT AN ALPHA STAGE.
+The tutorial is divided into the following sections:
-Please send comments, corrections and suggestions for improvements to
-A.Ford@ford-mason.co.uk
+=over 4
+=item *
-=head2 Installation
+L<Introduction|Catalyst::Manual::Tutorial::Intro>
-The first step is to install Catalyst, and the simplest way to do this is to
-install the Catalyst bundle from CPAN:
+=item *
- $ perl -MCPAN -e 'install Bundle::Catalyst'
+L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
-This will retrieve Catalyst and a number of useful extensions and install them
-for you.
+=item *
+L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
-=head2 Setting up your application
+=item *
-Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
-application for you:
+L<Authentication|Catalyst::Manual::Tutorial::Authentication>
- $ catalyst.pl My::App
- created "My-App"
- created "My-App/script"
- created "My-App/lib"
- created "My-App/root"
- created "My-App/t"
- created "My-App/t/m"
- created "My-App/t/v"
- created "My-App/t/c"
- created "My-App/lib/My/App"
- created "My-App/lib/My/App/M"
- created "My-App/lib/My/App/V"
- created "My-App/lib/My/App/C"
- created "My-App/lib/My/App.pm"
- created "My-App/Makefile.PL"
- created "My-App/README"
- created "My-App/Changes"
- created "My-App/t/01app.t"
- created "My-App/t/02podcoverage.t"
- created "My-App/script/server.pl"
- created "My-App/script/test.pl"
- created "My-App/script/create.pl"
+=item *
-This creates the directory structure shown.
+L<Authorization|Catalyst::Manual::Tutorial::Authorization>
+=item *
+L<Testing|Catalyst::Manual::Tutorial::Testing>
-=head2 Testing out the sample application
+=item *
-You can test out your new application by running the server script that
-catalyst provides:
+L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
- $ cd My-App
- $ script/server.pl
- [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Debug messages enabled
- [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI"
- [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Initialized components ""
- [Sun Mar 20 12:31:18 2005] [catalyst] [info] My::App powered by Catalyst 4.26
- [Sun Mar 20 12:31:18 2005] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)"
- You can connect to your server at http://localhost:3000
+=item *
-The server is now waiting for you to make requests of it. Try using telnet to
-manually make a simple GET request of the server (when telnet responds with
-"Escape character is '^]'.", type "GET / HTTP/1.0" and hit return twice):
+L<Appendices|Catalyst::Manual::Tutorial::Appendices>
- $ telnet localhost 3000
- Trying 127.0.0.1...
- Connected to localhost.
- Escape character is '^]'.
- GET / HTTP/1.0
-
- HTTP/1.0 200
- Server: Catalyst/4.26
- Status: 200
- Date: Sun, 20 Mar 2005 12:31:55 GMT
- X-catalyst: 4.26
- Content-length: 40
- Content-Type: text/html; charset=ISO-8859-1
+=back
- Congratulations, My::App is on Catalyst!
- Connection closed by foreign host.
- $
+A tarball of the final application is available at
+C<to_be_compled_in_final_version>.
-More trace messages will appear in the original terminal window:
+=head1 Detailed Table Of Contents
- [Sun Mar 20 12:31:55 2005] [catalyst] [debug] ********************************
- [Sun Mar 20 12:31:55 2005] [catalyst] [debug] * Request 1 (0.027/s) [9818]
- [Sun Mar 20 12:31:55 2005] [catalyst] [debug] ********************************
- [Sun Mar 20 12:31:55 2005] [catalyst] [debug] "GET" request for ""
- [Sun Mar 20 12:31:55 2005] [catalyst] [debug] Using default action
- [Sun Mar 20 12:31:55 2005] [catalyst] [info] Processing "!default" took 0.000033s
- [Sun Mar 20 12:31:55 2005] [catalyst] [info] Request took 0.051399s (19.456/s)
+=head2 Part 1: Introduction
-The server will continue running until you interrupt it.
+=over 4
-The application can also be tested from the command line using the generated
-helper script, C<script/test.pl>.
+=item *
+VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
-=head2 Getting your application invoked
+=item *
-Catalyst applications are intended to be run from mod_perl, but can also be
-run as CGI scripts. Running under mod_perl gives better performance, but for
-development purposes you may want to run your application as a CGI script,
-especially as each changes to your application code take effect under CGI
-without having to restart the web server.
+CATALYST INSTALLATION
-To run from mod_perl you need to add something like this to your Apache
-configuration file:
+=item *
- <Location /myapp>
- SetHandler perl-script
- PerlHandler MyApp
- </Location>
+DATABASES
-To run as a CGI script you need a wrapper script like:
+=item *
- #!/usr/bin/perl -w
+WHERE TO GET WORKING CODE
- use strict;
- use lib '/path/to/MyApp/lib';
- use MyApp;
+=back
- MyApp->run;
-Catalyst outputs a complete HTTP response, which is not what is expected of a
-CGI script. You need to configure the script as a so-called "Non-parsed
-Headers" script for it to function properly. To do this in Apache just name
-the script starting with C<nph->.
+=head2 Part 2: Catalyst Application Development Basics
+=over 4
+=item *
+CREATE A CATALYST PROJECT
-=head2 Extending the generated code
+=item *
-The generated application code looks like this:
+CREATE A SQLITE DATABASE
- package My::App;
+=item *
- use strict;
- use Catalyst qw/-Debug/;
+EDIT THE LIST OF CATALYST PLUGINS
- our $VERSION = '0.01';
+=item *
- My::App->config(
- name => 'My::App',
- root => '/home/andrew/My-App/root',
- );
+DATABASE ACCESS WITH DBIx::Class
- My::App->action(
- '!default' => sub {
- my ( $self, $c ) = @_;
- $c->res->output('Congratulations, My::App is on Catalyst!');
- },
- );
- 1;
+=over 4
+=item *
-You can start extending the application by adding new actions:
+Create a DBIC Schema File
- My::App->action(
- 'test1' => sub {
- my ( $self, $c ) = @_;
- $c->res->output('In a new test action #1');
- },
- 'test1' => sub {
- my ( $self, $c ) = @_;
- $c->res->output('In a new test action #1');
- },
- '!default' => sub {
- my ( $self, $c ) = @_;
- $c->res->output('Congratulations, My::App is on Catalyst!');
- },
- );
+=item *
+Create the DBIC ``Result Source'' Files
+
+=item *
+
+Use Catalyst::Model::DBIC::Schema to Load the Model Class
+
+=back
+
+
+=item *
+
+CREATE A CATALYST CONTROLLER
+
+=item *
+
+CATALYST VIEWS
+
+
+=over 4
+
+=item *
+
+Create a Catalyst View Using TTSite
+
+=item *
+
+Using RenderView for the Default View
+
+=item *
+
+Globally Customize Every View
+
+=item *
+
+Create a TT Template Page
+
+=back
+
+
+=item *
+
+RUN THE APPLICATION
+
+=back
+
+=head2 Part 3: Basic CRUD
+
+=over 4
+
+=item *
+
+FORMLESS SUBMISSION
+
+=over 4
+
+=item *
+
+Include a Create Action in the Books Controller
+
+=item *
+
+Include a Template for the url_create Action:
+
+=item *
+
+Try the url_create Feature
+
+=back
+
+=item *
+
+MANUALLY BUILDING A CREATE FORM
+
+=over 4
+
+=item *
+
+Add a Method to Display the Form
+
+=item *
+
+Add a Template for the Form
+
+=item *
+
+Add Method to Process Form Values and Update Database
+
+=item *
+
+Test Out the Form
+
+=back
+
+=item *
+
+A SIMPLE DELETE FEATURE
+
+=over 4
+
+=item *
+
+Include a Delete Link in the List
+
+=item *
+
+Add a Delete Action to the Controller
+
+=item *
+
+Try the Delete Feature
+
+=back
+
+=back
+
+=head2 Part 4: Authentication
+
+=over 4
+
+=item *
+
+BASIC AUTHENTICATION
+
+=over 4
+
+=item *
+
+Add Users and Roles to the Database
+
+=item *
+
+Add User and Role Information to DBIC Schema
+
+=item *
+
+Create New ``Result Source Objects''
+
+=item *
+
+Sanity-Check Reload of Development Server
+
+=item *
+
+Include Authentication and Session Plugins
+
+=item *
+
+Configure Authentication
+
+=item *
+
+Add Login and Logout Controllers
+
+=item *
+
+Add a Login Form TT Template Page
+
+=item *
+
+Add Valid User Check
+
+=item *
+
+Displaying Content Only to Authenticated Users
+
+=item *
+
+Try Out Authentication
+
+=back
+
+=item *
+
+USING PASSWORD HASHES
+
+=over 4
+
+=item *
+
+Get a SHA-1 Hash for the Password
+
+=item *
+
+Switch to SHA-1 Password Hashes in the Database
+
+=item *
+
+Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
+
+=item *
+
+Try Out the Hashed Passwords
+
+=back
+
+=back
+
+=head2 Part 5: Authorization
+
+=over 4
+
+=item *
+
+BASIC AUTHORIZATION
+
+=over 4
+
+=item *
+
+Update Plugins to Include Support for Authorization
+
+=item *
+
+Add Config Information for Authorization
+
+=item *
+
+Add Role-Specific Logic to the ``Book List'' Template
+
+=item *
+
+Limit Books::add to admin Users
+
+=item *
+
+Try Out Authentication And Authorization
+
+=back
+
+=item *
+
+ENABLE ACL-BASED AUTHORIZATION
+
+=over 4
+
+=item *
+
+Add the Catalyst::Plugin::Authorization::ACL Plugin
+
+=item *
+
+Add ACL Rules to the Application Class
+
+=item *
+
+Add a Method to Handle Access Violations
+
+=back
+
+=back
+
+=head2 Part 6: Debugging
+
+=over 4
+
+=item *
+
+LOG STATEMENTS
+
+=item *
+
+RUNNING CATALYST UNDER THE PERL DEBUGGER
+
+=item *
+
+DEBUGGING MODULES FROM CPAN
+
+=back
+
+=head2 Part 7: Testing
+
+=over 4
+
+=item *
+
+RUNNING THE "CANNED" CATALYST TESTS
+
+=item *
+
+RUNNING A SINGLE TEST
+
+=item *
+
+ADDING YOUR OWN TEST SCRIPT
+
+=item *
+
+SUPPORTING BOTH PRODUCTION AND TEST DATABASES
+
+=back
+
+=head2 Part 8: Advanced CRUD
+
+=over 4
+
+=item *
+
+HTML::WIDGET FORM CREATION
+
+=over 4
+
+=item *
+
+Add the HTML::Widget Plugin
+
+=item *
+
+Add a Form Creation Helper Method
+
+=item *
+
+Add Actions to Display and Save the Form
+
+=item *
+
+Update the CSS
+
+=item *
+
+Create a Template Page To Display The Form
+
+=item *
+
+Add Links for Create and Update via HTML::Widget
+
+=item *
+
+Test The <HTML::Widget> Create Form
+
+=back
+
+=item *
+
+HTML::WIDGET VALIDATION AND FILTERING
+
+=over 4
+
+=item *
+
+Add Constraints and Filters to the Widget Creation Method
+
+=item *
+
+Rebuild the Form Submission Method to Include Validation
+
+=item *
+
+Try Out the Form
+
+=back
+
+=item *
+
+Enable DBIx::Class::HTMLWidget Support
+
+=over 4
+
+=item *
+
+Add DBIx::Class::HTMLWidget to DBIC Model
+
+=item *
+
+Use populate_from_widget in hw_create_do
+
+=back
+
+=back
+
+=head2 Part 9: Appendices
+
+=over 4
+
+=item *
+
+APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
+
+=over 4
+
+=item *
+
+"Un-indenting" with Vi/Vim
+
+=item *
+
+"Un-indenting" with Emacs
+
+=back
+
+=item *
+
+APPENDIX 2: USING MYSQL AND POSTGRESQL
+
+=over 4
+
+=item *
+
+MySQL
+
+=item *
+
+PostgreSQL
+
+=back
+
+=item *
+
+APPENDIX 3: IMPROVED HASHING SCRIPT
+
+=back
+
+
+=head1 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:
+
+=over 4
+
+=item *
+
+Sebastian Riedel for founding the Catalyst project.
+
+=item *
+
+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 (& his
+willingness to answer lots of my questions); Jesse Sheidlower, for his
+incrediable 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.
+
+=item *
+
+Everyone on #catalyst and #catalyst-dev.
+
+=item *
+
+Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
+and Jess Robinson (including their work on the original Catalyst
+tutorial).
+
+=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, and
+Bryan Roach.
+
+=back
=head1 AUTHOR
-Andrew Ford, C<A.Ford@ford-mason.co.uk>
+Kennedy Clark, C<hkclark@gmail.com>
-=head1 COPYRIGHT
+Please report any errors, issues or suggestions to the author. The
+most recent version of the Catlayst Tutorial can be found at
+L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
-This program is free software, you can redistribute it and/or modify it under
-the same terms as Perl itself.
+Copyright 2006, Kennedy Clark, under Creative Commons License
+(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
projects / catagits/Catalyst-Runtime.git / blobdiff