=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.
-
-NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE. SEE
-THE NOTES AT THE BOTTOM OF THE DOCUMENT.
-
-=head2 Installation
-
-The first step is to install Catalyst, and the simplest way to do this
-is to install the Catalyst bundle from CPAN:
-
- $ perl -MCPAN -e 'install Bundle::Catalyst'
-
-This will retrieve Catalyst and a number of useful extensions and
-install them for you.
-
-
-=head2 Setting up your application
-
-Catalyst includes a helper script, C<catalyst.pl>, that will set up a
-skeleton application for you:
-
- 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/Build.PL"
- created "My-App/Makefile.PL"
- created "My-App/README"
- created "My-App/Changes"
- created "My-App/t/01app.t"
- created "My-App/t/02pod.t"
- created "My-App/t/03podcoverage.t"
- created "My-App/script/my_app_cgi.pl"
- created "My-App/script/my_app_fastcgi.pl"
- created "My-App/script/my_app_server.pl"
- created "My-App/script/my_app_test.pl"
- created "My-App/script/my_app_create.pl"
+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.
-This creates the directory structure shown, populated with skeleton
-files.
+The tutorial is divided into the following sections:
+=over 4
+
+=item *
+
+L<Introduction|Catalyst::Manual::Tutorial::Intro>
+
+=item *
+
+L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
+
+=item *
+
+L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
+
+=item *
+
+L<Authentication|Catalyst::Manual::Tutorial::Authentication>
+
+=item *
+
+L<Authorization|Catalyst::Manual::Tutorial::Authorization>
+
+=item *
+
+L<Testing|Catalyst::Manual::Tutorial::Testing>
+
+=item *
+
+L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
+
+=item *
+
+L<Appendices|Catalyst::Manual::Tutorial::Appendices>
+
+=back
+
+A tarball of the final application is available at
+C<to_be_compled_in_final_version>.
+
+=head1 Detailed Table Of Contents
+
+=head2 Part 1: Introduction
+
+=over 4
+
+=item *
+
+VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
+
+=item *
+
+CATALYST INSTALLATION
+
+=item *
+
+DATABASES
+
+=item *
+
+WHERE TO GET WORKING CODE
+
+=back
+
+
+=head2 Part 2: Catalyst Application Development Basics
+
+=over 4
+
+=item *
+
+CREATE A CATALYST PROJECT
+
+=item *
+
+CREATE A SQLITE DATABASE
+
+=item *
+
+EDIT THE LIST OF CATALYST PLUGINS
+
+=item *
+
+DATABASE ACCESS WITH DBIx::Class
+
+=item *
+
+Create a DBIC Schema File
+
+=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 *
+
+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 *
-=head2 Testing out the sample application
+Try Out the Hashed Passwords
-You can test out your new application by running the server script that
-Catalyst provides:
+=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
- $ cd My-App
- $ script/my_app_server.pl
+=item *
- [...] [catalyst] [debug] Debug messages enabled
- [...] [catalyst] [debug] Loaded dispatcher "Catalyst::Dispatcher"
- [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
- [...] [catalyst] [debug] Found home "/usr/home/jester/foo/My-App/script/.."
- [...] [catalyst] [debug] Loaded private actions
- .=--------------------------------+------------------------------------=.
- | Private | Class |
- |=--------------------------------+------------------------------------=|
- | /default | My::App |
- '=--------------------------------+------------------------------------='
+Add the Catalyst::Plugin::Authorization::ACL Plugin
- [....] [catalyst] [info] My::App powered by Catalyst 5.20
- You can connect to your server at http://localhost:3000/
+=item *
-(Note that each line logged by Catalyst begins with a timestamp, which has
-been replaced here with "C<...>" so that the text fits onto the lines.)
+Add ACL Rules to the Application Class
-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):
+=item *
- $ telnet localhost 3000
- Trying 127.0.0.1...
- Connected to localhost.
- Escape character is '^]'.
- GET / HTTP/1.0
-
- HTTP/1.0 200
- Server: Catalyst/5.20
- Status: 200
- Date: Fri May 13 14:15:46 EDT 2005
- X-catalyst: 5.20
- Content-length: 40
- Content-Type: text/html; charset=ISO-8859-1
+Add a Method to Handle Access Violations
- Congratulations, My::App is on Catalyst!
- Connection closed by foreign host.
- $
+=back
-More trace messages will appear in the original terminal window:
+=back
- [...] [catalyst] [debug] ********************************
- [...] [catalyst] [debug] * Request 1 (0.027/s) [9818]
- [...] [catalyst] [debug] ********************************
- [...] [catalyst] [debug] "GET" request for "" from localhost
- [...] [catalyst] [info] Request took 0.051399s (19.456/s)
- .=--------------------------------------------------+----------=.
- | Action | Time |
- |=--------------------------------------------------+----------=|
- | /default | 0.000026s |
- '=--------------------------------------------------+----------='
-
-The server will continue running until you interrupt it.
+=head2 Part 6: Debugging
-The application can also be tested from the command line using the generated
-helper script, C<script/my_app_test.pl>.
+=over 4
+=item *
-=head2 Getting your application invoked
-
-Catalyst applications are usually run from mod_perl, but can also be
-run as CGI or FastCGI 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 changes to your application
-code take effect under CGI without having to restart the web server.
-
-To run from mod_perl you need to add something like this to your Apache
-configuration file:
+LOG STATEMENTS
- <Location /my-app>
- SetHandler perl-script
- PerlHandler My::App
- </Location>
+=item *
-To run as a CGI script you need a wrapper script like:
+RUNNING CATALYST UNDER THE PERL DEBUGGER
- #!/usr/bin/perl -w
+=back
- use strict;
- use lib '/path/to/My/App/lib';
- use My::App;
+=head2 Part 7: Testing
- My::App->run;
+=over 4
+=item *
+RUNNING THE "CANNED" CATALYST TESTS
-=head2 Examining the generated code
+=item *
-The generated application code is quite simple and looks something
-like this:
+RUNNING A SINGLE TEST
- package My::App;
+=item *
- use strict;
- use Catalyst qw/-Debug/;
+ADDING YOUR OWN TEST SCRIPT
- our $VERSION = '0.01';
+=item *
- My::App->config(
- name => 'My::App',
- root => '/home/andrew/My-App/root',
- );
+SUPPORTING BOTH PRODUCTION AND TEST DATABASES
- __PACKAGE__->setup();
+=back
- sub default : Private {
- my ( $self, $c ) = @_;
- $c->res->output('Congratulations, My::App is on Catalyst!');
- }
+=head2 Part 8: Advanced CRUD
- 1;
+=over 4
+=item *
-When the C<Catalyst> module is imported by the application code,
-Catalyst performs the first stage of its initialization. This includes
-loading the appropriate Engine module for the environment in which the
-application is running, loading any plugins and ensuring that the
-calling module (the application module) inherits from C<Catalyst>
-(which makes the Catalyst methods C<config> and C<setup> available to
-the application module).
+HTML::WIDGET FORM CREATION
-The call to C<config> sets up configuration data for the application.
-The C<name> and C<root> items are the minimum required, and specify
-the name of the application and the path to the root directory where
-documents, images, and templates can be found.
+=over 4
+
+=item *
+
+Add the HTML::Widget Plugin
-Catalyst associates I<actions> with URLs and on receiving a request
-dispatches to the action that matches to request URL. The call to
-C<setup> in the code above registers a default action. With just
-this action registered the application will respond to all requests
-with the same message "Congratulations, My::App is on Catalyst!".
+=item *
-As you see, the default action is defined as a Private action.
-Most private actions are not directly available from a web url. This
-also includes the built-in actions, 'default','begin','end', and
-'auto', although they will be called as part of some chains.
-The rest can only be reached by using C<forward>.
+Add a Form Creation Helper Method
-The call to the C<setup> method also triggers the second stage of
-Catalyst's initialization process. In this phase Catalyst searches
-for any component modules, locating and registering any actions it
-finds in those modules.
+=item *
-Component modules have names prefixed with the application module name,
-followed by C<M>, C<V> or C<C> (or the optional long
-forms: C<Model>, C<View> or C<Controller>) followed by the component
-name, for example:
+Add Actions to Display and Save the Form
- My::App::C::ShoppingCart # short (default) version
- My::App::Controller::ShoppingCart # long version
+=item *
- My::App::M::User # short (default) version
- My::App::Model::User # long version
+Update the CSS
-=head2 Extending the generated code
+=item *
+Create a Template Page To Display The Form
-You can start extending the application by adding new actions:
+=item *
- sub test1 : Global {
- my ( $self, $c ) = @_;
- $c->res->output('In a new test action #1');
- }
- sub default : Private {
- my ( $self, $c ) = @_;
- $c->res->output('Congratulations, My::App is on Catalyst!');
- }
+Add Links for Create and Update via HTML::Widget
- # called like '/article/2005/06'
- sub archive_month : Regex('^article/(\d{4})/(\d{2})$') {
- my ( $self, $c ) = @_;
+=item *
- my $datetime = DateTime->new(
- year => $c->request->snippets->[0],
- month => $c->request->snippets->[1]
- );
- }
+Test The <HTML::Widget> Create Form
-TODO: explain briefly about plugins, actions, and components
+=back
-If the action is a Regex type, you can use capturing parentheses to
-extract values within the matching URL (2005, 06 in the above
-example). Those values are available in the $c->req->snippets
-anonymous array. See L<Catalyst::Manual::Intro#Actions> for details.
+=item *
+HTML::WIDGET VALIDATION AND FILTERING
-=head2 Hooking in to Template Toolkit
+=over 4
-One of the first things you will probably want to add to your
-application is a templating system for generating your output.
-Catalyst works well with Template Toolkit. If you are unfamiliar with
-Template Toolkit then I suggest you look at L<http://tt2.org>, install
-C<Template>, read the documentation and play around with it, and have
-a look at the I<Badger Book> (I<Template Toolkit> by Darren
-Chamberlain, Dave Cross, and Andy Wardley, O'Reilly & Associates, 2004).
+=item *
-You can create a stub Template Toolkit view component using the create
-script that Catalyst set up as part of the skeleton application:
+Add Constraints and Filters to the Widget Creation Method
- $ script/create.pl view TT TT
+=item *
-this generates a view component named C<My::App::V::TT>, which you
-might use by forwarding from your C<end> action:
+Rebuild the Form Submission Method to Include Validation
- # In My::App or My::App::Controller::SomeController
+=item *
- sub end : Private {
- my($self, $c) = @_;
- $c->forward('My::App::V::TT');
- }
+Try Out the Form
-The generated TT view component simply subclasses the
-C<Catalyst::View::TT> class. It looks like this (with the POD
-stripped out):
+=back
- package My::App::V::TT;
+=item *
- use strict;
- use base 'Catalyst::View::TT';
+Enable DBIx::Class::HTMLWidget Support
- 1;
+=over 4
-C<Catalyst::View::TT> initializes a Template Toolkit object with an
-options hash initialized with built-in default settings followed by
-the contents of the hash C<<%{__PACKAGE__->config()}>>. You can
-configure TT more to your needs by adding a C<new> method to the
-generated TT component:
+=item *
- sub new {
- my $self = shift;
- $self->config->{PRE_PROCESS} = 'config/main';
- $self->config->{WRAPPER} = 'site/wrapper';
- return $self->SUPER::new(@_);
- }
+Add DBIx::Class::HTMLWidget to DBIC Model
+=item *
+Use populate_from_widget in hw_create_do
-=head1 AUTHOR
+=back
-Andrew Ford, C<A.Ford@ford-mason.co.uk>
-Marcus Ramberg, C<mramberg@cpan.org>
+=back
-As noted above, this document is at an alpha stage. My plan for this
-document is as follows:
+=head2 Part 9: Appendices
=over 4
-=item 1
+=item *
-Expand this document fairly rapidly to cover topics relevant to
-a newcomer to Catalyst, in an order that can be read sequentially
+APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
-=item 2
+=over 4
-Incorporate feedback
+=item *
-=item 3
+"Un-indenting" with Vi/Vim
-Revise the text
+=item *
+
+"Un-indenting" with Emacs
=back
-Placeholders are indicated by the words: TODO or CHECK
+=item *
+
+APPENDIX 2: USING MYSQL AND POSTGRESQL
-Please send comments, corrections and suggestions for improvements to
-A.Ford@ford-mason.co.uk
+=over 4
+=item *
-=head1 COPYRIGHT
+MySQL
+
+=item *
+
+PostgreSQL
+
+=back
+
+=back
-This program is free software, you can redistribute it and/or modify
-it under the same terms as Perl itself.