X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=0410d790a46ef837e300e6fe0d1247a692228844;hb=121baf930c9edc6187e05e3f168ff56502d9af34;hp=2c1b1394f3b912aea139d5e1953aa54148325154;hpb=016373e66232c6862ae37037e06735bd39f3894f;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod
index 2c1b139..0410d79 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">
@@ -285,13 +255,13 @@ best to add a user check to a 'begin' action:
         }
     }
 
-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. 
 
@@ -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.
 
@@ -616,7 +586,7 @@ 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.
 
-To use a custom error page, use a special C<end> method to short-circut
+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
@@ -629,7 +599,7 @@ C<end> method; see L<Catalyst::Plugin::FillInForm>).
             $c->stash->{errors}   = $c->error;
             $c->stash->{template} = 'errors.tt';
             $c->forward('MyApp::View::TT');
-            $c->{error} = [];
+            $c->error(0);
         }
     
         return 1 if $c->response->status =~ /^3\d\d$/;
@@ -646,6 +616,110 @@ 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/Session::FastMmap Authentication::CDBI/;
+
+  __PACKAGE__->config->{authentication} = {
+    'user_class'        => 'ScratchPad::M::MyDB::Customer',
+    'user_field'        => 'username',
+    'password_field'    => 'password',
+    'password_hash'     => '',
+  };
+
+  sub auto : Private {
+    my ($self, $c) = @_;
+    my $login_path = 'user/login';
+
+    # allow people to actually reach the login page!
+    if ($c->req->path eq $login_path) {
+      return 1;
+    }
+
+    # if we have a user ... we're OK
+    if ( $c->req->user ) {
+      $c->session->{'authed_user'} =
+        MyApp::M::MyDB::Customer->retrieve(
+          'username' => $c->req->user
+        );
+    }
+
+    # otherwise they're not logged in
+    else {
+      # force the login screen to be shown
+      $c->res->redirect($c->req->base . $login_path);
+    }
+
+    # 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->req->param('username') ) {
+      # try to log the user in
+      $c->session_login(
+        $c->req->param('username'),
+        $c->req->param('password'),
+      );
+
+      # if we have a user we're logged in
+      if ( $c->req->user ) {
+        $c->res->redirect('/some/page');
+      }
+
+      # otherwise we failed to login, try again!
+      else {
+        $c->stash->{'message'} = 
+           'Unable to authenticate the login details supplied';
+      }
+    }
+  }
+
+  sub logout : Path('/user/logout') {
+    my ($self, $c) = @_;
+    # logout the session, and remove information we've stashed
+    $c->session_logout;
+    delete $c->session->{'authed_user'};
+
+    # do the 'default' action
+    $c->res->redirect($c->req->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 %]
+
 =head1 AUTHOR
 
 Sebastian Riedel, C<sri@oook.de>