X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial.pod;h=91d11acc7743c79e78506caa74119f871818cdfb;hb=64ccd8a8bfbc16276c044c94702b1440c2897695;hp=dea503ea95f363832b29d399400de289f0290dfb;hpb=b460ad78a952bcaaa8f468d6e578c17002d0645b;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Manual/Tutorial.pod b/lib/Catalyst/Manual/Tutorial.pod
index dea503e..91d11ac 100644
--- a/lib/Catalyst/Manual/Tutorial.pod
+++ b/lib/Catalyst/Manual/Tutorial.pod
@@ -1,317 +1,521 @@
 =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
+design to provide a rapid introduction to its basics and most commonly
+used features while focusing on real-world best practices.
+
+The tutorial is broken down into the following sections:
+
+=over 4
+
+=item *
+
+L<Introduction|Catalyst::Manual::Tutorial_Intro>
+
+=item * 
+
+L<Catalyst Basics|Catalyst::Manual::Tutorial_CatalystBasics>
+
+=item * 
+
+L<CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
+
+=item * 
+
+L<Authentication|Catalyst::Manual::Tutorial_Authentication>
+
+=item * 
+
+L<Authorization|Catalyst::Manual::Tutorial_Authorization>
+
+=item * 
+
+L<Debugging|Catalyst::Manual::Tutorial_Debugging>
+
+=item * 
+
+L<Testing|Catalyst::Manual::Tutorial_Testing>
+
+=item * 
+
+L<CRUD|Catalyst::Manual::Tutorial_AdvancedCRUD>
+
+=item * 
+
+L<Appendicies|Catalyst::Manual::Tutorial_Appendicies>
+
+=back
+
+
+Full source code is available for each section via the main Catalyst
+Subversion repository at
+L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.  See the
+end of each section for the specifics on retrieving code for that
+section.
+
+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 *
+
+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 Method to Display The Form
+
+=item *
 
-NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE.  SEE THE NOTES
-AT THE BOTTOM OF THE DOCUMENT.
+Add a Template for the Form
 
+=item *
 
+Add Method to Process Form Values and Update Database
 
-=head2 Installation
+=item *
 
-The first step is to install Catalyst, and the simplest way to do this is to
-install the Catalyst bundle from CPAN:
+Test Out The Form
 
-    $ perl -MCPAN -e 'install Bundle::Catalyst'
+=back
 
-This will retrieve Catalyst and a number of useful extensions and install them
-for you.
+=item *
 
+A SIMPLE DELETE FEATURE
 
-=head2 Setting up your application
+=over 4
 
-Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
-application for you:
+=item *
 
-    $ 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/cgi.pl"
-    created "My-App/script/nph-cgi.pl"
-    created "My-App/script/fcgi.pl"
-    created "My-App/script/server.pl"
-    created "My-App/script/test.pl"
-    created "My-App/script/create.pl"
+Include a Delete Link in the List
 
-This creates the directory structure shown, populated with skeleton files.
+=item *
 
+Add a Delete Action to the Controller
 
+=item *
 
-=head2 Testing out the sample application
+Try the Delete Feature
 
-You can test out your new application by running the server script that
-catalyst provides:
+=back
 
-    $ cd My-App
-    $ script/server.pl 
-    [...] [catalyst] [debug] Debug messages enabled
-    [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI"
-    [...] [catalyst] [debug] Initialized components ""
-    [...] [catalyst] [info] My::App powered by Catalyst 4.26
-    [...] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)"
-    You can connect to your server at http://localhost:3000
+=back
 
-(Note that each line logged by Catalyst includes 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):
+=head2 Part 4: Authentication
 
-    $ 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
+=over 4
 
-    Congratulations, My::App is on Catalyst!
-    Connection closed by foreign host.
-    $
+=item *
 
-More trace messages will appear in the original terminal window:
+BASIC AUTHENTICATION
 
-    [...] [catalyst] [debug] ********************************
-    [...] [catalyst] [debug] * Request 1 (0.027/s) [9818]
-    [...] [catalyst] [debug] ********************************
-    [...] [catalyst] [debug] "GET" request for ""
-    [...] [catalyst] [debug] Using default action
-    [...] [catalyst] [info] Processing "!default" took 0.000033s
-    [...] [catalyst] [info] Request took 0.051399s (19.456/s)
+=over 4
 
-The server will continue running until you interrupt it.
+=item *
 
-The application can also be tested from the command line using the generated
-helper script, C<script/test.pl>.
+Add Users and Roles to the Database
 
+=item *
 
-=head2 Getting your application invoked
+Add User and Role Information to DBIC Schema
 
-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.
+=item *
 
-To run from mod_perl you need to add something like this to your Apache
-configuration file:
+Create New ``Result Source Objects''
 
-    <Location /my-app>
-        SetHandler  perl-script
-        PerlHandler My::App
-    </Location>
+=item *
 
-To run as a CGI script you need a wrapper script like:
+Sanity-Check Reload of Development Server
 
-    #!/usr/bin/perl -w
+=item *
 
-    use strict;
-    use lib '/path/to/My/App/lib';
-    use My::App;
+Include Authentication and Session Plugins
 
-    My::App->run;
+=item *
 
-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->.
+Configure Authentication
 
-CHECK: is this statement still valid for Cat5?
+=item *
 
+Add Login and Logout Controllers
 
-=head2 Examining the generated code
+=item *
 
-The generated application code is quite simple and looks something like this:
+Add a Login Form TT Template Page
 
-    package My::App;
+=item *
 
-    use strict;
-    use Catalyst qw/-Debug/;
+Add Valid User Check
 
-    our $VERSION = '0.01';
+=item *
 
-    My::App->config(
-	name => 'My::App',
-	root => '/home/andrew/My-App/root',
-    );
+Displaying Content Only to Authenticated Users
 
-    My::App->action(
-	'!default' => sub {
-	    my ( $self, $c ) = @_;
-	    $c->res->output('Congratulations, My::App is on Catalyst!');
-	},
-    );
+=item *
 
-    1;
+Try Out Authentication
 
+=back
 
-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<action> available to the application module).
+=item *
 
-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.
+USING PASSWORD HASHES
 
-Catalyst associates I<actions> with URLs and on receiving a request dispatches
-to the action that matches to request URL.  The call to C<action> 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!".
+=over 4
 
-TODO: mention private actions and attributes
+=item *
 
+Get a SHA-1 Hash for the Password
 
-The first call to the C<action> method 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 alternative short
-forms: C<M>, C<V> or C<C>) followed by the component name, for example:
+=item *
 
-    My::App::Controller::ShoppingCart
+Switch to SHA-1 Password Hashes in the Database
 
+=item *
 
+Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
 
+=item *
 
-=head2 Extending the generated code
+Try Out the Hashed Passwords
 
-NOTE: this section is outdated by Cat5.
+=back
 
-You can start extending the application by adding new actions:
+=back
 
-    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!');
-	},
-    );
 
+=head2 Part 5: Authorization
 
-TODO: explain briefly about plugins, actions and components
+=over 4
 
-regex actions passed subexpression matches in $c->req->snippets (array ref).
+=item *
 
+BASIC AUTHORIZATION
 
-=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 Wardly, 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:
+Update Plugins to Include Support  for Authorization
 
-    $ script/create.pl view TT TT
+=item *
 
-this generates a view component named C<My::App::View::TT>, which you might
-use by forwarding from your C<end> action:
+Add Config Information for Authorization
 
-    # In My::App or My::App::Controller::SomeController
+=item *
 
-    sub end : Private {
-        my($self, $c) = @_;
-        $c->forward('My::App::View::TT');
-    }
+Add Role-Specific Logic to the ``Book List'' Template
 
-The generated TT view component simply subclasses the C<Catalyst::View::TT>
-class.  It looks like this (with the POD stripped out):
+=item *
 
-    package My::App::V::TT;
+Limit Books::add to admin Users
 
-    use strict;
-    use base 'Catalyst::View::TT';
+=item *
 
-    1;
+Try Out Authentication And Authorization
 
-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:
+=back
 
-    sub new {
-	my $self = shift;
-	$self->config->{PRE_PROCESS} = 'config/main';
-	$self->config->{WRAPPER}     = 'site/wrapper';
-	return $self->SUPER::new(@_);
-    }
+=item *
 
+ENABLE ACL-BASED AUTHORIZATION
 
+=over 4
 
-=head1 AUTHOR
+=item *
 
-Andrew Ford, C<A.Ford@ford-mason.co.uk>
+Add the Catalyst::Plugin::Authorization::ACL Plugin
 
-As noted above, this document is at an alpha stage.  My plan for this document
-is as follows:
+=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 1
+=item *
+
+LOG STATEMENTS
 
-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
+RUNNING CATALYST UNDER THE PERL DEBUGGER
+
+=back
 
-incorporate feedback 
 
-=item 3
+=head2 Part 7: Testing
 
-revise the text 
+=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
 
-Placeholders are indicated by the words: TODO or CHECK 
 
-Please send comments, corrections and suggestions for improvements to
-A.Ford@ford-mason.co.uk
+=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 *
 
-=head1 COPYRIGHT
+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
+
+=back
 
-This program is free software, you can redistribute it and/or modify it under
-the same terms as Perl itself.