X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=bd7202930abdf75895f203af631cd3ab92ad027d;hb=de6fb80a66ecfeb21ab707daf70de17cc02415f8;hp=af8d13e78466efe829110fa00929d3695dadf727;hpb=f25a32836c7c60ea3c89aebec41f7edf82133ea6;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod
index af8d13e..bd72029 100644
--- a/lib/Catalyst/Manual/Cookbook.pod
+++ b/lib/Catalyst/Manual/Cookbook.pod
@@ -40,51 +40,21 @@ statistics in your debug messages.
 =head2 Scaffolding
 
 Scaffolding is very simple with Catalyst.
-Just use Catalyst::Model::CDBI::CRUD as your base class.
 
-    # lib/MyApp/Model/CDBI.pm
-    package MyApp::Model::CDBI;
+The recommended way is to use Catalyst::Helper::Controller::Scaffold.
 
-    use strict;
-    use base 'Catalyst::Model::CDBI::CRUD';
-
-    __PACKAGE__->config(
-        dsn           => 'dbi:SQLite:/tmp/myapp.db',
-        relationships => 1
-    );
-
-    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<$c-E<gt>form()> parameters to match your needs, and don't
-forget to copy the templates into the template root. Can't find the
-templates?  They were in the CRUD model distribution, so you can do
-B<look Catalyst::Model::CDBI::CRUD> from the CPAN shell to find them.
-
-Other Scaffolding modules are in development at the time of writing.
 
 =head2 File uploads
 
 =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">
@@ -104,16 +74,16 @@ 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';
     }
 
@@ -143,7 +113,7 @@ And in the controller:
                 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': $!" );
                 }
@@ -208,7 +178,7 @@ To log in a user you might use an action like this:
             $c->session_login($c->req->params->{username}, 
                               $c->req->params->{password} );
             if ($c->req->{user}) {
-                $c->forward('?restricted_area');
+                $c->forward('/restricted_area');
             }
         }
     }
@@ -266,32 +236,32 @@ with:
     sub add : Local {
         my ($self, $c) = @_;
         if ($c->roles(qw/admin/)) {
-            $c->req->output("Your account has the role 'admin.'");
+            $c->res->output("Your account has the role 'admin.'");
         } else {
-            $c->req->output("You're not allowed to be here.");
+            $c->res->output("You're not allowed to be here.");
         }
     }
 
 One thing you might need is to forward non-authenticated users to a login 
 form if they try to access restricted areas. If you want to do this 
 controller-wide (if you have one controller for your admin section) then it's 
-best to add a user check to a '!begin' action:
+best to add a user check to a 'begin' action:
 
     sub begin : Private {
         my ($self, $c) = @_;
         unless ($c->req->{user}) {
             $c->req->action(undef);  ## notice this!!
-            $c->forward('?login');
+            $c->forward('/user/login');
         }
     }
 
-Pay attention to $c->req->action(undef). This is needed because of the 
-way $c->forward works - C<forward> to C<login> gets called, but after that 
-Catalyst will still execute the action defined in the URI (e.g. if you 
-tried to go to C</add>, then first 'begin' will forward to 'login', but after
-that 'add' will nonetheless be executed). So $c->req->action(undef) undefines any 
-actions that were to be called and forwards the user where we want him/her 
-to be.
+Pay attention to $c->req->action(undef). This is needed because of the
+way $c->forward works - C<forward> to C<login> gets called, but after
+that Catalyst will still execute the action defined in the URI (e.g. if
+you tried to go to C</add>, then first 'begin' will forward to 'login',
+but after that 'add' will nonetheless be executed). So
+$c->req->action(undef) undefines any actions that were to be called and
+forwards the user where we want him/her to be.
 
 And this is all you need to do. 
 
@@ -351,7 +321,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:
@@ -373,7 +343,7 @@ 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
 
 Serving static content in Catalyst can be somewhat tricky; this recipe
@@ -440,7 +410,7 @@ 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' );
 
@@ -450,7 +420,7 @@ Edit the file and add the following methods:
     # also handle requests for /favicon.ico
     sub favicon : Path('/favicon.ico') {
         my ( $self, $c ) = @_;
-    
+
         $c->serve_static;
     }
 
@@ -463,7 +433,7 @@ favicon.ico by using this in your HTML header:
 
 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 OSX. For OSX the easiest
+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.
 
@@ -485,14 +455,13 @@ 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; variations, some of
-which could be simpler, are left as an exercise for the reader:
+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
@@ -505,6 +474,13 @@ which could be simpler, are left as an exercise for the reader:
         </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
@@ -519,8 +495,8 @@ the Catalyst Request object:
   $c->req->args([qw/arg1 arg2 arg3/]);
   $c->forward('/wherever');
 
-(See L<Catalyst::Manual::Intro#Flow_Control> for more information on
-passing arguments via C<forward>.)
+(See the L<Catalyst::Manual::Intro> Flow_Control section for more 
+information on passing arguments via C<forward>.)
 
 =head2 Configure your application
 
@@ -602,20 +578,201 @@ simple component in Catalyst that slurps in an outside Model:
 and that's it! Now C<Some::Other::CDBI::Module::Catalog> is part of your
 Cat app as C<MyApp::M::Catalog>.
 
-=head1 Serving static files with Apache.
+=head2 Delivering a Custom Error Page
 
-When deploying your application it's a waste to serve static files 
-with Catalyst. Instead, set up something like this:
+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
+a full Data::Dumper output of the C<$c> context object. When not in
+C<-Debug>, users see a simple "Please come back later" screen.
 
-    Alias /static/ "/my/static/files/"
-    <Location "/static">
-    SetHandler none
-    </Location>
+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:
 
-To match the location of your static files. 
+=head3 lib/MyApp.pm
 
+  use Catalyst qw/
+      Authentication
+      Authentication::Store::DBIC
+      Authentication::Credential::Password
+  /;
 
-=cut
+  __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);
+  }
+
+
+=head3 root/base/user/login.tt
+
+ [% 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
 
@@ -626,6 +783,9 @@ 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