X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=db585290a07bb7d7adfc1e8e8a942a6f3bae4134;hp=568f15663cb7c573b4b54ab7df933174240d0895;hb=f63c03e47ae0278e50d513b90ecbbdfd67d1a021;hpb=3ffaf022fdbd8d058e76df96b6b0f117bd4c0c85

diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod
index 568f156..db58529 100644
--- a/lib/Catalyst/Manual/Cookbook.pod
+++ b/lib/Catalyst/Manual/Cookbook.pod
@@ -11,17 +11,24 @@ Yummy code like your mum used to bake!
 =head2 Force debug screen
 
 You can force Catalyst to display the debug screen at the end of the request by
-placing a die() call in the _end action.
+placing a C<die()> call in the C<end> action.
 
      sub end : Private {
          my ( $self, $c ) = @_;
-         die "testing";
+         die "forced debug";
      }
 
-If you're tired of removing and adding this all the time, you
-can easily add a condition. for example:
+If you're tired of removing and adding this all the time, you can add a
+condition in the C<end> action. For example:
+
+    sub end : Private {  
+        my ( $self, $c ) = @_;  
+        die "forced debug" if $c->req->params->{dump_info};  
+    }  
+
+Then just add to your query string C<"&dump_info=1">, or the like, to
+force debug output.
 
-  die "Testing" if $c->param->{dump_info};
 
 =head2 Disable statistics
 
@@ -33,45 +40,21 @@ statistics in your debug messages.
 =head2 Scaffolding
 
 Scaffolding is very simple with Catalyst.
-Just use Catalyst::Model::CDBI::CRUD as baseclass.
-
-    # lib/MyApp/Model/CDBI.pm
-    package MyApp::Model::CDBI;
-
-    use strict;
-    use base 'Catalyst::Model::CDBI::CRUD';
 
-    __PACKAGE__->config(
-        dsn           => 'dbi:SQLite:/tmp/myapp.db',
-        relationships => 1
-    );
+The recommended way is to use Catalyst::Helper::Controller::Scaffold.
 
-    1;
+Just install this module, and to scaffold a Class::DBI Model class, do the following:
 
-    # lib/MyApp.pm
-    package MyApp;
+./script/myapp_create controller <name> Scaffold <CDBI::Class>Scaffolding
 
-    use Catalyst 'FormValidator';
-
-    __PACKAGE__->config(
-        name => 'My Application',
-        root => '/home/joeuser/myapp/root'
-    );
 
-    sub my_table : Global {
-        my ( $self, $c ) = @_;
-        $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] );
-        $c->forward('MyApp::Model::CDBI::Table');
-    }
 
-    1;
 
-Modify the $c->form() parameters to match your needs, and don't forget to copy
-the templates. ;)
+=head2 File uploads
 
-=head2 Single file upload with Catalyst
+=head3 Single file upload with Catalyst
 
-To implement uploads in Catalyst you need to have a HTML form similiar to
+To implement uploads in Catalyst, you need to have a HTML form similar to
 this:
 
     <form action="/upload" method="post" enctype="multipart/form-data">
@@ -80,8 +63,8 @@ this:
       <input type="submit" value="Send">
     </form>
 
-It's very important not to forget enctype="multipart/form-data" in form, 
-if it's not there, uploads just don't work.
+It's very important not to forget C<enctype="multipart/form-data"> in
+the form.
 
 Catalyst Controller module 'upload' action:
 
@@ -91,25 +74,24 @@ Catalyst Controller module 'upload' action:
         if ( $c->request->parameters->{form_submit} eq 'yes' ) {
 
             if ( my $upload = $c->request->upload('my_file') ) {
-            
+
                 my $filename = $upload->filename;
                 my $target   = "/tmp/upload/$filename";
-                
+
                 unless ( $upload->link_to($target) || $upload->copy_to($target) ) {
                     die( "Failed to copy '$filename' to '$target': $!" );
                 }
             }
         }
-        
+
         $c->stash->{template} = 'file_upload.html';
     }
 
-=head2 Multiple file upload with Catalyst
+=head3 Multiple file upload with Catalyst
 
-Code for uploading multiple files from one form needs little changes compared
-to single file upload.
+Code for uploading multiple files from one form needs a few changes:
 
-Form goes like this:
+The form should have this basic structure:
 
     <form action="/upload" method="post" enctype="multipart/form-data">
       <input type="hidden" name="form_submit" value="yes">
@@ -119,7 +101,7 @@ Form goes like this:
       <input type="submit" value="Send">
     </form>
 
-Controller:
+And in the controller:
 
     sub upload : Local {
         my ($self, $c) = @_;
@@ -128,9 +110,10 @@ Controller:
 
             for my $field ( $c->req->upload ) {
 
+                my $upload   = $c->req->upload($field);
                 my $filename = $upload->filename;
                 my $target   = "/tmp/upload/$filename";
-                
+
                 unless ( $upload->link_to($target) || $upload->copy_to($target) ) {
                     die( "Failed to copy '$filename' to '$target': $!" );
                 }
@@ -140,153 +123,204 @@ Controller:
         $c->stash->{template} = 'file_upload.html';
     }
 
-for my $field ($c->req->upload) loops automatically over all file input
-fields and gets input names. After that is basic file saving code, just like in
-single file upload.
+C<for my $field ($c-E<gt>req->upload)> loops automatically over all file
+input fields and gets input names. After that is basic file saving code,
+just like in single file upload.
 
-Notice: die'ing might not be what you want to do, when error occurs, but
-it works as an example. Better idea would be to store error $! in
-$c->stash->{error} and show custom error template displaying this message.
+Notice: C<die>ing might not be what you want to do, when an error
+occurs, but it works as an example. A better idea would be to store
+error C<$!> in $c->stash->{error} and show a custom error template
+displaying this message.
 
 For more information about uploads and usable methods look at
-C<Catalyst::Request::Upload> and C<Catalyst::Request>.
+L<Catalyst::Request::Upload> and L<Catalyst::Request>.
+
+=head2 Authentication with Catalyst::Plugin::Authentication
+
+In this example, we'll use the
+L<Catalyst::Plugin::Authentication::Store::DBIC> store and the
+L<Catalyst::Plugin::Authentication::Credential::Password> credentials.
+
+In the lib/MyApp.pm package, we'll need to change the C<use Catalyst;>
+line to include the following modules:
+
+    use Catalyst qw/
+        ConfigLoader 
+        Authentication
+        Authentication::Store::DBIC
+        Authentication::Credential::Password
+        Session
+        Session::Store::FastMmap
+        Session::State::Cookie
+        HTML::Widget
+        Static::Simple
+        /;
+
+The Session, Session::Store::* and Session::State::* modules listed above
+ensure that we stay logged-in across multiple page-views.
+
+In our MyApp.yml configuration file, we'll need to add:
+
+    authentication:
+      dbic:
+        user_class: MyApp::Model::DBIC::User
+        user_field: username
+        password_field: password
+        password_type: hashed
+        password_hash_type: SHA-1
+
+'user_class' is a DBIx::Class package for your users table.
+'user_field' tells which field (column) is used for username lookup.
+'password_field' is the password field in your table.
+The above settings for 'password_type' and 'password_hash_type' ensure that
+the password won't be stored in the database in clear text.
+
+In SQLite, the users table might be something like:
+
+    CREATE TABLE user (
+        id       INTEGER PRIMARY KEY,
+        username VARCHAR(100),
+        password VARCHAR(100)
+    );
 
-=head2 Authentication with Catalyst::Plugin::Authentication::CDBI
+Now we need to create a DBIC::SchemaLoader component for this database
+(changing "myapp.db" to wherever your SQLite database is).
 
-There are (at least) two ways to implement authentication with this plugin:
-1) only checking username and password
-2) checking username, password and the roles the user has
+    script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:myapp.db'
 
-For both variants you'll need the following code in your MyApp package:
+Now we can start creating our page controllers and templates.
+For our homepage, we create the file "root/index.tt" containing:
 
-    use Catalyst qw/Session::FastMmap Static Authentication::CDBI/;
+    <html>
+    <body>
+    [% IF c.user %]
+        <p>hello [% c.user.username %]</p>
+        <p><a href="[% c.uri_for( '/logout' ) %]">logout</a></p>
+    [% ELSE %]
+        <p><a href="[% c.uri_for( '/login' ) %]">login</a></p>
+    [% END %]
+    </body>
+    </html>
 
-    MyApp->config( authentication => { user_class => 'MyApp::M::MyApp::Users',
-                                       user_field => 'email',
-                                       password_field => 'password' });
+If the user is logged in, they will be shown their name, and a logout link.
+Otherwise, they will be shown a login link.
 
-'user_class' is a Class::DBI class for your users table.
-'user_field' tells which field is used for username lookup (might be 
-email, first name, surname etc).
-'password_field' is, well, password field in your table and by default 
-password is stored in plain text. Authentication::CDBI looks for 'user' 
-and 'password' fields in table, if they're not defined in the config.
+To display the homepage, we can uncomment the C<default> and C<end>
+subroutines in lib/MyApp/Controller/Root.pm and populate them as so:
 
-In PostgreSQL users table might be something like:
+    sub default : Private {
+        my ( $self, $c ) = @_;
+    
+        $c->stash->{template} = 'index.tt';
+    }
 
-CREATE TABLE users (
-  user_id   serial,
-  name      varchar(100),
-  surname   varchar(100),
-  password  varchar(100),
-  email     varchar(100),
-  primary key(user_id)
-);
+    sub end : Private {
+        my ( $self, $c ) = @_;
+    
+        $c->forward( $c->view('TT') )
+            unless $c->response->body || $c->response->redirect;
+    }
 
-We'll discuss the first variant for now:
-1. user:password login / auth without roles
+The login template is very simple, as L<HTML::Widget> will handle the
+HTML form creation for use. This is saved as "root/login.tt".
 
-To log in a user you might use a action like this:
+    <html>
+    <head>
+    <link href="[% c.uri_for('/static/simple.css') %]" rel="stylesheet" type="text/css">
+    </head>
+    <body>
+    [% result %]
+    </body>
+    </html>
 
-    sub 'login' : Local {
-        my ($self, $c) = @_;
-        if ($c->req->params->{username}) {
-            $c->session_login($c->req->params->{username}, 
-                              $c->req->params->{password} );
-            if ($c->req->{user}) {
-                $c->forward('?restricted_area');
-            }
-        }
-    }
+For the HTML form to look correct, we also copy the C<simple.css> file
+from the L<HTML::Widget> distribution into our "root/static" folder.
+This file is automatically server by the L<Catalyst::Plugin::Static::Simple>
+module which we loaded in our lib/MyApp.pm package.
 
-$c->req->params->{username} and $c->req->params->{password} are html 
-form parameters from a login form. If login succeeds, then 
-$c->req->{user} contains the username of the authenticated user.
+To handle login requests, we first create a controller, like so:
 
-If you want to remember the users login status inbetween further 
-requests, then just use the $c->session_login method, Catalyst will 
-create a session id, session cookie and automatically append session 
-id to all urls. So all you have to do, is just check $c->req->{user} 
-where needed.
+    script/myapp_create.pl controller Login
 
-To log out user, just call $c->session_logout.
+In the lib/MyApp/Controller/Login.pm package, we can then uncomment the
+C<default> subroutine, and populate it, as below.
 
-Now lets take a look at the second variant:
-2. user:password login / auth with roles
+First the widget is created, it needs the 'action' set, and 'username' and
+'password' fields and a submit button added.
 
-To use roles you need to add to MyApp->config in the 'authentication' 
-section following parameters:
+Then, if we've received a username and password in the request, we attempt
+to login. If successful, we redirect to the homepage; if not the login form
+will be displayed again.
 
-    role_class      => 'MyApp::M::MyApp::Roles',
-    user_role_class => 'MyApp::M::MyApp::UserRoles',
-    user_role_user_field => 'user_id',
-    user_role_role_field => 'role_id',
+    sub default : Private {
+        my ( $self, $c ) = @_;
+    
+        $c->widget->method('POST')->action( $c->uri_for('/login') );
+        $c->widget->element( 'Textfield', 'username' )->label( 'Username' );
+        $c->widget->element( 'Password', 'password' )->label( 'Password' );
+        $c->widget->element( 'Submit' )->value( 'Login' );
+        
+        my $result = $c->widget->process( $c->req );
+        
+        if ( my $user = $result->param('username')
+            and my $pass = $result->param('password') )
+        {    
+            if ( $c->login( $user, $pass ) ) {
+                $c->response->redirect( $c->uri_for( "/" ) );
+                return;
+            }
+        }
+        
+        $c->stash->{template} = 'login.tt';
+        $c->stash->{result}   = $result;
+    }
 
-Corresponding tables in PostgreSQL could look like this:
+To handle logout's, we create a new controller:
 
-CREATE TABLE roles (
-  role_id  serial,
-  name     varchar(100),
-  primary key(role_id)
-);
+    script/myapp_create.pl controller Logout
 
-CREATE TABLE user_roles (
-  user_role_id  serial,
-  user_id       int,
-  role_id       int,
-  primary key(user_role_id),
-  foreign key(user_id) references users(user_id),
-  foreign key(role_id) references roles(role_id)
-);
+Then in the lib/MyApp/Controller/Logout.pm package, we change the
+C<default> subroutine, to logout and then redirect back to the
+homepage.
 
-The 'roles' table is a list of role names and the 'user_role' table is 
-used for the user -> role lookup.
+    sub default : Private {
+        my ( $self, $c ) = @_;
+    
+        $c->logout;
+        
+        $c->response->redirect( $c->uri_for( "/" ) );
+    }
 
-Now if a logged in user wants to see a location which is allowed only 
-for people with 'admin' role then in you controller you can check it 
-with:
+Remember that to test this, we would first need to add a user to the
+database, ensuring that the password field is saved as the SHA1 hash
+of our desired password.
 
-    sub add : Local {
-        my ($self, $c) = @_;
-        if ($c->roles(qw/admin/)) {
-            $c->req->output("Your account has the role 'admin.'");
-        } else {
-            $c->req->output("You're not allowed to be here");
-        }
-    }
 
-One thing you might need is to forward non-authenticated users to login 
-form, if they try to access restricted areas. If you want to do this 
-controller-wide (if you have one controller for admin section) then it's 
-best to add user check to '!begin' action:
+=head2 Pass-through login (and other actions)
+
+An easy way of having assorted actions that occur during the processing
+of a request that are orthogonal to its actual purpose - logins, silent
+commands etc. Provide actions for these, but when they're required for
+something else fill e.g. a form variable __login and have a sub begin
+like so:
 
     sub begin : Private {
-        my ($self, $c) = @_;
-        unless ($c->req->{user}) {
-            $c->req->action(undef);  ## notice this!!
-            $c->forward('?login');
+      my ($self, $c) = @_;
+      foreach my $action (qw/login docommand foo bar whatever/) {
+        if ($c->req->params->{"__${action}"}) {
+          $c->forward($action);
         }
+      }
     }
 
-Pay attention to $c->req->action(undef). This is needed, because of the 
-way $c->forward works - forward to login gets called, but after that 
-Catalyst executes anyway the action defined in the uri (eg. if you 
-tried to watch /add, then first 'begin' forwards to 'login', but after
-that anyway 'add' is executed). So $c->req->action(undef) undefines any 
-actions that were to be called and forwards user where we want him/her 
-to be.
-
-And this is all you need to do, isn't Catalyst wonderful?
-
-
 =head2 How to use Catalyst without mod_perl
 
 Catalyst applications give optimum performance when run under mod_perl.
 However sometimes mod_perl is not an option, and running under CGI is 
-just too slow.  There are two alternatives to mod_perl that give 
-reasonable performance: FastCGI and PersistentPerl.
+just too slow.  There's also an alternative to mod_perl that gives
+reasonable performance named FastCGI.
 
-B<Using FastCGI>
+=head3 Using FastCGI
 
 To quote from L<http://www.fastcgi.com/>: "FastCGI is a language 
 independent, scalable, extension to CGI that provides high performance 
@@ -310,7 +344,7 @@ it is done - and it also works as a normal, single-shot CGI script.
 Any initialization code should be included outside the request-accept 
 loop.
 
-There is one little complication, which is that C<MyApp->run> outputs a
+There is one little complication, which is that C<MyApp-E<gt>run> outputs a
 complete HTTP response including the status line (e.g.: 
 "C<HTTP/1.1 200>").
 FastCGI just wants a set of headers, so the sample code captures the 
@@ -318,7 +352,7 @@ output and  drops the first line if it is an HTTP status line (note:
 this may change).
 
 The Apache C<mod_fastcgi> module is provided by a number of Linux 
-distros and is straightforward to compile for most Unix-like systems.  
+distro's and is straightforward to compile for most Unix-like systems.  
 The module provides a FastCGI Process Manager, which manages FastCGI 
 scripts.  You configure your script as a FastCGI script with the 
 following Apache configuration directives:
@@ -336,55 +370,447 @@ or:
 
 C<mod_fastcgi> provides a number of options for controlling the FastCGI
 scripts spawned; it also allows scripts to be run to handle the
-authentication, authorization and access check phases.
+authentication, authorization, and access check phases.
 
 For more information see the FastCGI documentation, the C<FCGI> module 
 and L<http://www.fastcgi.com/>.
 
+=head2 Serving static content
 
-B<PersistentPerl>
+Serving static content in Catalyst can be somewhat tricky; this recipe
+shows one possible solution. Using this recipe will serve all static
+content through Catalyst when developing with the built-in HTTP::Daemon
+server, and will make it easy to use Apache to serve the content when
+your app goes into production.
 
-PersistentPerl (previously known as C<CGI::SpeedyCGI>) is a persistent 
-Perl interpreter.  After the script is initially run, instead of 
-exiting, the perl interpreter is kept running. During subsequent runs, 
-this interpreter is used to handle new executions instead of starting 
-a new perl interpreter each time. A very fast frontend program contacts
-the persistent Perl process, which is usually already running, to do 
-the work and return the results.
-PersistentPerl can be used to speed up perl CGI scripts.  It also 
-provides an Apache module so that scripts can be run without the 
-overhead of doing a fork/exec for each request.
+Static content is best served from a single directory within your root
+directory. Having many different directories such as C<root/css> and
+C<root/images> requires more code to manage, because you must separately
+identify each static directory--if you decide to add a C<root/js>
+directory, you'll need to change your code to account for it. In
+contrast, keeping all static directories as subdirectories of a main
+C<root/static> directory makes things much easier to manager. Here's an
+example of a typical root directory structure:
 
-The code for PersistentPerl is simpler than for FastCGI; rather than 
-waiting in an accept loop the script runs to completion, however 
-variables are not reinitialized on subsequent runs but maintain their 
-values from the previous run.
+    root/
+    root/content.tt
+    root/controller/stuff.tt
+    root/header.tt
+    root/static/
+    root/static/css/main.css
+    root/static/images/logo.jpg
+    root/static/js/code.js
 
 
-    #!/usr/bin/perperl
-    use strict;
-    use vars qw($output $initialized);
-    use PersistentPerl;
-    use MyApp;
+All static content lives under C<root/static> with everything else being
+Template Toolkit files. Now you can identify the static content by
+matching C<static> from within Catalyst.
+
+=head3 Serving with HTTP::Daemon (myapp_server.pl)
+
+To serve these files under the standalone server, we first must load the
+Static plugin. Install L<Catalyst::Plugin::Static> if it's not already
+installed.
+
+In your main application class (MyApp.pm), load the plugin:
+
+    use Catalyst qw/-Debug FormValidator Static OtherPlugin/;
+
+You will also need to make sure your end method does I<not> forward
+static content to the view, perhaps like this:
+
+    sub end : Private {
+        my ( $self, $c ) = @_;
+
+        $c->forward( 'MyApp::V::TT' ) 
+          unless ( $c->res->body || !$c->stash->{template} );
+    }
+
+This code will only forward to the view if a template has been
+previously defined by a controller and if there is not already data in
+C<$c-E<gt>res-E<gt>body>.
+
+Next, create a controller to handle requests for the /static path. Use
+the Helper to save time. This command will create a stub controller as
+C<lib/MyApp/C/Static.pm>.
+
+    $ script/myapp_create.pl controller Static
+
+Edit the file and add the following methods:
+
+    # serve all files under /static as static files
+    sub default : Path('/static') {
+        my ( $self, $c ) = @_;
+
+        # Optional, allow the browser to cache the content
+        $c->res->headers->header( 'Cache-Control' => 'max-age=86400' );
+
+        $c->serve_static; # from Catalyst::Plugin::Static
+    }
+
+    # also handle requests for /favicon.ico
+    sub favicon : Path('/favicon.ico') {
+        my ( $self, $c ) = @_;
+
+        $c->serve_static;
+    }
+
+You can also define a different icon for the browser to use instead of
+favicon.ico by using this in your HTML header:
+
+    <link rel="icon" href="/static/myapp.ico" type="image/x-icon" />
+
+=head3 Common problems
+
+The Static plugin makes use of the C<shared-mime-info> package to
+automatically determine MIME types. This package is notoriously
+difficult to install, especially on win32 and OS X. For OS X the easiest
+path might be to install Fink, then use C<apt-get install
+shared-mime-info>. Restart the server, and everything should be fine.
+
+Make sure you are using the latest version (>= 0.16) for best
+results. If you are having errors serving CSS files, or if they get
+served as text/plain instead of text/css, you may have an outdated
+shared-mime-info version. You may also wish to simply use the following
+code in your Static controller:
+
+    if ($c->req->path =~ /css$/i) {
+        $c->serve_static( "text/css" );
+    } else {
+        $c->serve_static;
+    }
+
+=head3 Serving with Apache
+
+When using Apache, you can completely bypass Catalyst and the Static
+controller by intercepting requests for the C<root/static> path at the
+server level. All that is required is to define a DocumentRoot and add a
+separate Location block for your static content. Here is a complete
+config for this application under mod_perl 1.x:
+
+    <Perl>
+        use lib qw(/var/www/MyApp/lib);
+    </Perl>
+    PerlModule MyApp
+
+    <VirtualHost *>
+        ServerName myapp.example.com
+        DocumentRoot /var/www/MyApp/root
+        <Location />
+            SetHandler perl-script
+            PerlHandler MyApp
+        </Location>
+        <LocationMatch "/(static|favicon.ico)">
+            SetHandler default-handler
+        </LocationMatch>
+    </VirtualHost>
+
+And here's a simpler example that'll get you started:
+
+    Alias /static/ "/my/static/files/"
+    <Location "/static">
+        SetHandler none
+    </Location>
+
+=head2 Forwarding with arguments
+
+Sometimes you want to pass along arguments when forwarding to another
+action. As of version 5.30, arguments can be passed in the call to
+C<forward>; in earlier versions, you can manually set the arguments in
+the Catalyst Request object:
+
+  # version 5.30 and later:
+  $c->forward('/wherever', [qw/arg1 arg2 arg3/]);
+
+  # pre-5.30
+  $c->req->args([qw/arg1 arg2 arg3/]);
+  $c->forward('/wherever');
+
+(See the L<Catalyst::Manual::Intro> Flow_Control section for more 
+information on passing arguments via C<forward>.)
+
+=head2 Configure your application
+
+You configure your application with the C<config> method in your
+application class. This can be hard-coded, or brought in from a
+separate configuration file.
+
+=head3 Using YAML
+
+YAML is a method for creating flexible and readable configuration
+files. It's a great way to keep your Catalyst application configuration
+in one easy-to-understand location.
+
+In your application class (e.g. C<lib/MyApp.pm>):
+
+  use YAML;
+  # application setup
+  __PACKAGE__->config( YAML::LoadFile(__PACKAGE__->config->{'home'} . '/myapp.yml') );
+  __PACKAGE__->setup;
+
+Now create C<myapp.yml> in your application home:
+
+  --- #YAML:1.0
+  # DO NOT USE TABS FOR INDENTATION OR label/value SEPARATION!!!
+  name:     MyApp
+
+  # session; perldoc Catalyst::Plugin::Session::FastMmap
+  session:
+    expires:        '3600'
+    rewrite:        '0'
+    storage:        '/tmp/myapp.session'
+
+  # emails; perldoc Catalyst::Plugin::Email
+  # this passes options as an array :(
+  email:
+    - SMTP
+    - localhost
+
+This is equivalent to:
+
+  # configure base package
+  __PACKAGE__->config( name => MyApp );
+  # configure authentication
+  __PACKAGE__->config->{authentication} = {
+    user_class => 'MyApp::M::MyDB::Customer',
+    ...
+  };
+  # configure sessions
+  __PACKAGE__->config->{session} = {
+    expires => 3600,
+    ...
+  };
+  # configure email sending
+  __PACKAGE__->config->{email} = [qw/SMTP localhost/];
+
+See also L<YAML>.
+
+=head2 Using existing DBIC (etc.) classes with Catalyst
 
-    if (!$initialized++) {
-        # initialization code - set up database, etc
-        if ($PersistentPerl::i_am_per_perl) {
-            # PP-specific initialization code
+Many people have existing Model classes that they would like to use with
+Catalyst (or, conversely, they want to write Catalyst models that can be
+used outside of Catalyst, e.g.  in a cron job). It's trivial to write a
+simple component in Catalyst that slurps in an outside Model:
+
+    package MyApp::Model::DB;
+    use base qw/Catalyst::Model::DBIC::Schema/;
+    __PACKAGE__->config(
+        schema_class => 'Some::DBIC::Schema',
+        connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}];
+    );
+    1;
+
+and that's it! Now C<Some::DBIC::Schema> is part of your
+Cat app as C<MyApp::Model::DB>.
+
+=head2 Delivering a Custom Error Page
+
+By default, Catalyst will display its own error page whenever it
+encounters an error in your application. When running under C<-Debug>
+mode, the error page is a useful screen including the error message and
+L<Data::Dump> output of the relevant parts of the C<$c> context object. 
+When not in C<-Debug>, users see a simple "Please come back later" screen.
+
+To use a custom error page, use a special C<end> method to short-circuit
+the error processing. The following is an example; you might want to
+adjust it further depending on the needs of your application (for
+example, any calls to C<fillform> will probably need to go into this
+C<end> method; see L<Catalyst::Plugin::FillInForm>).
+
+    sub end : Private {
+        my ( $self, $c ) = @_;
+
+        if ( scalar @{ $c->error } ) {
+            $c->stash->{errors}   = $c->error;
+            $c->stash->{template} = 'errors.tt';
+            $c->forward('MyApp::View::TT');
+            $c->error(0);
         }
+
+        return 1 if $c->response->status =~ /^3\d\d$/;
+        return 1 if $c->response->body;
+
+        unless ( $c->response->content_type ) {
+            $c->response->content_type('text/html; charset=utf-8');
+        }
+
+        $c->forward('MyApp::View::TT');
+    }
+
+You can manually set errors in your code to trigger this page by calling
+
+    $c->error( 'You broke me!' );
+
+=head2 Require user logins
+
+It's often useful to restrict access to your application to a set of
+registered users, forcing everyone else to the login page until they're
+signed in.
+
+To implement this in your application make sure you have a customer
+table with username and password fields and a corresponding Model class
+in your Catalyst application, then make the following changes:
+
+=head3 lib/MyApp.pm
+
+  use Catalyst qw/
+      Authentication
+      Authentication::Store::DBIC
+      Authentication::Credential::Password
+  /;
+
+  __PACKAGE__->config->{authentication}->{dbic} = {
+    'user_class'        => 'My::Model::DBIC::User',
+    'user_field'        => 'username',
+    'password_field'    => 'password'
+    'password_type'     => 'hashed',
+    'password_hash_type'=> 'SHA-1'
+  };
+
+  sub auto : Private {
+    my ($self, $c) = @_;
+    my $login_path = 'user/login';
+
+    # allow people to actually reach the login page!
+    if ($c->request->path eq $login_path) {
+      return 1;
+    }
+
+    # if a user doesn't exist, force login
+    if ( !$c->user_exists ) {
+      # force the login screen to be shown
+      $c->response->redirect($c->request->base . $login_path);
+    }
+
+    # otherwise, we have a user - continue with the processing chain
+    return 1;
+  }
+
+=head3 lib/MyApp/C/User.pm
+
+  sub login : Path('/user/login') {
+    my ($self, $c) = @_;
+
+    # default template
+    $c->stash->{'template'} = "user/login.tt";
+    # default form message
+    $c->stash->{'message'} = 'Please enter your username and password';
+
+    if ( $c->request->param('username') ) {
+      # try to log the user in
+      # login() is provided by ::Authentication::Credential::Password
+      if( $c->login(
+        $c->request->param('username'),
+        $c->request->param('password'),
+        );
+
+        # if login() returns 1, user is now logged in
+        $c->response->redirect('/some/page');
+      }
+
+      # otherwise we failed to login, try again!
+      $c->stash->{'message'} = 
+         'Unable to authenticate the login details supplied';
     }
+  }
+
+  sub logout : Path('/user/logout') {
+    my ($self, $c) = @_;
+    # log the user out
+    $c->logout;
+
+    # do the 'default' action
+    $c->response->redirect($c->request->base);
+  }
+
 
-    MyApp->run;
+=head3 root/base/user/login.tt
 
-For more information see the C<PersistentPerl> documentation.
+ [% INCLUDE header.tt %]
+ <form action="/user/login" method="POST" name="login_form">
+    [% message %]<br />
+    <label for="username">username:</label><br />
+    <input type="text" id="username" name="username" /><br />
 
+    <label for="password">password:</label><br />
+    <input type="password" id="password" name="password" /><br />
+
+    <input type="submit" value="log in" name="form_submit" />
+  </form>
+  [% INCLUDE footer.tt %]
+
+=head2 Role-based Authorization
+
+For more advanced access control, you may want to consider using role-based
+authorization. This means you can assign different roles to each user, e.g.
+"user", "admin", etc.
+
+The C<login> and C<logout> methods and view template are exactly the same as
+in the previous example.
+
+The L<Catalyst::Plugin::Authorization::Roles> plugin is required when
+implementing roles:
+
+ use Catalyst qw/
+    Authentication
+    Authentication::Credential::Password
+    Authentication::Store::Htpasswd
+    Authorization::Roles
+  /;
+
+Roles are implemented automatically when using
+L<Catalyst::Authentication::Store::Htpasswd>:
+
+  # no additional role configuration required
+  __PACKAGE__->config->{authentication}{htpasswd} = "passwdfile";
+
+Or can be set up manually when using L<Catalyst::Authentication::Store::DBIC>:
+
+  # Authorization using a many-to-many role relationship
+  __PACKAGE__->config->{authorization}{dbic} = {
+    'role_class'           => 'My::Model::DBIC::Role',
+    'role_field'           => 'name',
+    'user_role_user_field' => 'user',
+
+    # DBIx::Class only (omit if using Class::DBI)
+    'role_rel'             => 'user_role',
+
+    # Class::DBI only, (omit if using DBIx::Class)
+    'user_role_class'      => 'My::Model::CDBI::UserRole'
+    'user_role_role_field' => 'role',
+  };
+
+To restrict access to any action, you can use the C<check_user_roles> method:
+
+  sub restricted : Local {
+     my ( $self, $c ) = @_;
+
+     $c->detach("unauthorized")
+       unless $c->check_user_roles( "admin" );
+
+     # do something restricted here
+  }
+
+You can also use the C<assert_user_roles> method. This just gives an error if
+the current user does not have one of the required roles:
+
+  sub also_restricted : Global {
+    my ( $self, $c ) = @_;
+    $c->assert_user_roles( qw/ user admin / );
+  }
 
 =head1 AUTHOR
 
 Sebastian Riedel, C<sri@oook.de>
-Danijel Milicevic C<me@danijel.de>
-Viljo Marrandi C<vilts@yahoo.com>
-Marcus Ramberg C<mramberg@cpan.org>
+Danijel Milicevic, C<me@danijel.de>
+Viljo Marrandi, C<vilts@yahoo.com>  
+Marcus Ramberg, C<mramberg@cpan.org>
+Jesse Sheidlower, C<jester@panix.com>
+Andy Grundman, C<andy@hybridized.org> 
+Chisel Wright, C<pause@herlpacker.co.uk>
+Will Hawes, C<info@whawes.co.uk>
+Gavin Henry, C<ghenry@cpan.org> (Spell checking)
+
 
 =head1 COPYRIGHT