X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial.pod;h=af5e1fa40567ae67e82e3232f499abf917e5e1a6;hp=fe928234cc63ab96ab2374651deee674f7f0b5ed;hb=c9b77c06a0de97f1d6e9a66091e693a637578357;hpb=387e4c5093d5230f1bf4b6510d62f87b9ca353cf

diff --git a/lib/Catalyst/Manual/Tutorial.pod b/lib/Catalyst/Manual/Tutorial.pod
index fe92823..af5e1fa 100644
--- a/lib/Catalyst/Manual/Tutorial.pod
+++ b/lib/Catalyst/Manual/Tutorial.pod
@@ -1,354 +1,574 @@
 =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:
-
-    $ catalyst MyApp
-    
-    created "MyApp"
-    created "MyApp/script"
-    created "MyApp/lib"
-    created "MyApp/root"
-    created "MyApp/root/static"
-    created "MyApp/root/static/images"
-    created "MyApp/t"
-    created "MyApp/t/Model"
-    created "MyApp/t/View"
-    created "MyApp/t/Controller"
-    created "MyApp/lib/MyApp"
-    created "MyApp/lib/MyApp/Model"
-    created "MyApp/lib/MyApp/View"
-    created "MyApp/lib/MyApp/Controller"
-    created "MyApp/lib/MyApp.pm"
-    created "MyApp/Build.PL"
-    created "MyApp/Makefile.PL"
-    created "MyApp/README"
-    created "MyApp/Changes"
-    created "MyApp/t/01app.t"
-    created "MyApp/t/02pod.t"
-    created "MyApp/t/03podcoverage.t"
-    created "MyApp/root/static/images/catalyst_logo.png"
-    created "MyApp/root/static/images/btn_120x50_built.png"
-    created "MyApp/root/static/images/btn_120x50_built_shadow.png"
-    created "MyApp/root/static/images/btn_120x50_powered.png"
-    created "MyApp/root/static/images/btn_120x50_powered_shadow.png"
-    created "MyApp/root/static/images/btn_88x31_built.png"
-    created "MyApp/root/static/images/btn_88x31_built_shadow.png"
-    created "MyApp/root/static/images/btn_88x31_powered.png"
-    created "MyApp/root/static/images/btn_88x31_powered_shadow.png"
-    created "MyApp/root/favicon.ico"
-    created "MyApp/script/myapp_cgi.pl"
-    created "MyApp/script/myapp_fastcgi.pl"
-    created "MyApp/script/myapp_server.pl"
-    created "MyApp/script/myapp_test.pl"
-    created "MyApp/script/myapp_create.pl"
-
-This creates the directory structure shown, populated with skeleton 
-files.
-
-=head2 Testing out the sample application
-
-You can test out your new application by running the server script that
-Catalyst provides:
-
-    $ cd MyApp
-    $ script/myapp_server.pl 
-
-    [...] [catalyst] [debug] Debug messages enabled
-    [...] [catalyst] [debug] Loaded plugins:
-    .------------------------------------------------------------------------------.
-    | Catalyst::Plugin::Static::Simple                                             |
-    '------------------------------------------------------------------------------'
-    [...] [catalyst] [debug] Loaded dispatcher "Catalyst::Dispatcher"
-    [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
-    [...] [catalyst] [debug] Found home "/home/users/me/MyApp"
-    [...] [catalyst] [debug] Loaded Private actions:
-    .--------------------------------------+---------------------------------------.
-    | Private                              | Class                                 |
-    +--------------------------------------+---------------------------------------+
-    | /default                             | MyApp                                 |
-    '--------------------------------------+---------------------------------------'
-    
-    [...] [catalyst] [info] MyApp powered by Catalyst 5.5
-    You can connect to your server at http://localhost:3000
-
-(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.)
-
-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):
-
-    $ telnet localhost 3000
-    Trying 127.0.0.1...
-    Connected to localhost.
-    Escape character is '^]'.
-    GET / HTTP/1.0
-    
-    HTTP/1.0 200 OK
-    Date: Mon, 07 Nov 2005 14:57:39 GMT
-    Content-Length: 5525
-    Content-Type: text/html; charset=utf-8
-    Status: 200
-    X-Catalyst: 5.5
-
-    [...]
-    Connection closed by foreign host.
-    $
-
-You can see the full welcome message by visting
-http://localhost:3000/ with your browser.
-
-More trace messages will appear in the original terminal window:
-
-    [...] [catalyst] [debug] **********************************
-    [...] [catalyst] [debug] * Request 1 (0.063/s) [2148]
-    [...] [catalyst] [debug] **********************************
-    [...] [catalyst] [debug] Arguments are ""
-    [...] [catalyst] [debug] "GET" request for "" from localhost
-    [...] [catalyst] [info] Request took 0.046883s (21.330/s)
-    .------------------------------------------------------------------+-----------.
-    | Action                                                           | Time      |
-    +------------------------------------------------------------------+-----------+
-    | /default                                                         | 0.000000s |
-    '------------------------------------------------------------------+-----------'
-
-The server will continue running until you interrupt it.
-
-The application can also be tested from the command line using the generated
-helper script, C<script/myapp_test.pl>.
-
-=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:
-
-    <Location /MyApp>
-        SetHandler  perl-script
-        PerlHandler MyApp
-    </Location>
-
-To run as a CGI script you need a wrapper script like:
-
-    #!/usr/bin/perl -w
-    
-    use strict;
-    use lib '/path/to/MyApp/lib';
-    use MyApp;
-    
-    MyApp->run;
-
-=head2 Examining the generated code
-
-The generated application code is quite simple and looks something 
-like this (comments removed):
-
-    package MyApp;
-    
-    use strict;
-    use warnings;
-    
-    use Catalyst qw/-Debug Static::Simple/;
-    
-    our $VERSION = '0.01';
-    
-    __PACKAGE__->config( name => 'MyApp' );
-    __PACKAGE__->setup;
-    
-    sub default : Private {
-        my ( $self, $c ) = @_;
-    
-        $c->response->body( $c->welcome_message );
-    }
-    
-    1;
-
-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).
-
-The call to C<config> sets up configuration data for the application.  
-The C<name> parameter is the only required configuration parameter.
-You may also specificy a C<root> parameter, which is the path to the
-directory where documents, images, and templates can be found.
-
-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 welcome page.
-
-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>.
-
-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.
-
-Component modules have names prefixed with the application module name,
-followed by C<Model>, C<View> or C<Controller> (or the optional short
-forms: C<M>, C<V> or C<C>) followed by the component
-name, for example:
-
-    MyApp::Controller::ShoppingCart  # long (default) version
-    MyApp::C::ShoppingCart           # short version 
-
-    MyApp::Model::User               # long (default) version
-    MyApp::M::User                   # short version
-
-=head2 Extending the generated code
-
-You can start extending the application by adding new actions:
-
-    sub test1 : Global {
-        my ( $self, $c ) = @_;
-        $c->res->body('In a new test action #1');
-    }
-    sub default : Private {
-        my ( $self, $c ) = @_;
-        $c->res->body('Congratulations, MyApp is on Catalyst!');
-    }
-
-    # called like '/article/2005/06'
-    sub archive_month : Regex('^article/(\d{4})/(\d{2})$') {
-        my ( $self, $c ) = @_;
-
-        my $datetime = DateTime->new(
-            year  => $c->request->snippets->[0],
-            month => $c->request->snippets->[1]
-        );
-    }
-
-TODO: explain briefly about plugins, actions, and components
-
-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.
-
-=head2 Hooking in to Template Toolkit
-
-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).
-
-You can create a stub Template Toolkit view component by installing
-L<Catalyst::View::TT> and using the create script that Catalyst set
-up as part of the skeleton application:
-
-    $ script/myapp_create.pl view TT TT
-    
-     exists "MyApp/lib/MyApp/View"
-     exists "MyApp/t/View"
-    created "MyApp/lib/MyApp/View/TT.pm"
-    created "MyApp/t/View/TT.t"
-
-this generates a view component named C<MyApp::View::TT>, which you 
-might use by forwarding from your C<end> action:
-
-    # In MyApp or MyApp::Controller::SomeController
-
-    sub end : Private {
-        my($self, $c) = @_;
-        $c->forward('MyApp::V::TT');
-    }
-
-The generated TT view component simply subclasses the 
-C<Catalyst::View::TT> class.  It looks like this (with the POD 
-stripped out): 
-
-    package My::App::V::TT;
-
-    use strict;
-    use base 'Catalyst::View::TT';
-
-    1;
-
-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:
-
-    sub new {
-        my $self = shift;
-        $self->config->{PRE_PROCESS} = 'config/main';
-        $self->config->{WRAPPER}     = 'site/wrapper';
-        return $self->SUPER::new(@_);
-    }
+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.
+
+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
+
+
+=over 4
+
+=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 *
+
+Using RenderView for the Default View
+
+=item *
+
+Globally Customize Every View
+
+=item *
+
+Create a TT Template Page
+
+=back
 
-=head1 AUTHOR
 
-Andrew Ford, C<A.Ford@ford-mason.co.uk>
-Marcus Ramberg, C<mramberg@cpan.org>
+=item *
 
-As noted above, this document is at an alpha stage.  My plan for this 
-document is as follows:
+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 1
+=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
 
-Expand this document fairly rapidly to cover topics relevant to
-a newcomer to Catalyst, in an order that can be read sequentially
+=item *
 
-=item 2
+Configure Authentication
 
-Incorporate feedback 
+=item *
 
-=item 3
+Add Login and Logout Controllers
 
-Revise the text 
+=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
 
-Placeholders are indicated by the words: TODO or CHECK 
+=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 (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.
+
+=item *
+
+Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
+and Jess Robinson (including their work on the original Catalyst
+tutorial).
+
+=item *
+
+Everyone on #catalyst and #catalyst-dev.
+
+=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,  
+Bryan Roach, Ashley Berlin, and David Kamholz.  
+
+=back
+
+
+
+=head1 AUTHOR
 
-Please send comments, corrections and suggestions for improvements to
-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 Catalyst 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/>).