X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FAuthentication.pod;h=26707fee82c2911fc3ec8c9ae6b978d47a5a54bb;hb=d0afb3a93f0c51d32e9074957fff4e8b5aae0369;hp=0c8e2b348e841028f69d6944326c5023e4294294;hpb=33aee7ed93ee23ff174aa8affcaf935148a67230;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Manual/Tutorial/Authentication.pod b/lib/Catalyst/Manual/Tutorial/Authentication.pod
index 0c8e2b3..26707fe 100644
--- a/lib/Catalyst/Manual/Tutorial/Authentication.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authentication.pod
@@ -45,7 +45,7 @@ L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
 
 =item 9
 
-L<Appendices|Catalyst::Manual::Tutorial::Appendicies>
+L<Appendices|Catalyst::Manual::Tutorial::Appendices>
 
 =back
 
@@ -63,8 +63,7 @@ B<TIP>: Note that all of the code for this part of the tutorial can be
 pulled from the Catalyst Subversion repository in one step with the
 following command:
 
-    svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@###
-    IMPORTANT: Does not work yet.  Will be completed for final version.
+    svn co http://dev.catalyst.perl.org/repos/Catalyst/tags/examples/Tutorial/MyApp/5.7/Authentication MyApp
 
 
 =head1 BASIC AUTHENTICATION
@@ -414,15 +413,21 @@ you could have a C<User> controller with both C<login> and C<logout>
 actions.  Remember, Catalyst is designed to be very flexible, and leaves
 such matters up to you, the designer and programmer.
 
-Then open C<lib/MyApp/Controller/Login.pm> and add:
+Then open C<lib/MyApp/Controller/Login.pm>, locate the C<sub index : 
+Private> method (this was automatically inserted by the helpers when we 
+created the Login controller above), and delete this line:
 
-    =head2 base
+    $c->response->body('Matched MyApp::Controller::Login in Login.');
+
+Then update it to match:
+
+    =head2 index
     
     Login logic
     
     =cut
     
-    sub base :Path :Args(0) {
+    sub index : Private {
         my ($self, $c) = @_;
     
         # Get the username and password from form
@@ -453,29 +458,34 @@ at the login page but receive an error message.  If the C<username> and
 C<password> values are not present in the form, the user will be taken
 to the empty login form.
 
-We are using C<sub base :Path :Args(0) {...}> here to specifically match 
-the URL C</login>.  C<Path> actions (aka, "literal actions") create URI 
-matches relative to the namespace of the controller where they are defined.  
-Although C<Path> supports arguments that allow relative and absolute paths 
-to be defined, here we use an empty C<Path> definition to match on just the 
-name of the controller itself.  The method name, C<base>, is arbitrary.  
-We make the match even more specific with the C<:Args(0)> action modifier 
--- this forces the match on I<only> C</login>, not C</login/somethingelse>.
-
 Note that we could have used something like C<sub default :Private>; 
 however, the use of C<default> actions is discouraged because it does
 not receive path args as with other actions.  The recommended practice 
 is to only use C<default> in C<MyApp::Controller::Root>.
 
-Next, create a corresponding method in C<lib/MyApp/Controller/Logout.pm>:
+Another option would be to use something like 
+C<sub base :Path :Args(0) {...}> (where the C<...> refers to the login 
+code shown in C<sub index : Private> above). We are using C<sub base 
+:Path :Args(0) {...}> here to specifically match the URL C</login>. 
+C<Path> actions (aka, "literal actions") create URI matches relative to 
+the namespace of the controller where they are defined.  Although 
+C<Path> supports arguments that allow relative and absolute paths to be 
+defined, here we use an empty C<Path> definition to match on just the 
+name of the controller itself.  The method name, C<base>, is arbitrary. 
+We make the match even more specific with the C<:Args(0)> action 
+modifier -- this forces the match on I<only> C</login>, not 
+C</login/somethingelse>.
 
-    =head2 base
+Next, update the corresponding method in C<lib/MyApp/Controller/Logout.pm>
+to match:
+
+    =head2 index
     
     Logout logic
     
     =cut
     
-    sub base :Path :Args(0) {
+    sub index : Private {
         my ($self, $c) = @_;
     
         # Clear the user's state
@@ -485,8 +495,9 @@ Next, create a corresponding method in C<lib/MyApp/Controller/Logout.pm>:
         $c->response->redirect($c->uri_for('/'));
     }
 
-Note that we are using the same C<sub base :Path :Args(0) {...}> style
-of action as with the login logic.
+As with the login controller, be sure to delete the 
+C<$c->response->body('Matched MyApp::Controller::Logout in Logout.');>
+line of the C<sub index>.
 
 
 =head2 Add a Login Form TT Template Page
@@ -533,11 +544,17 @@ the following method:
     
     # Note that 'auto' runs after 'begin' but before your actions and that
     # 'auto' "chain" (all from application path to most specific class are run)
+    # See the 'Actions' section of 'Catalyst::Manual::Intro' for more info.
     sub auto : Private {
         my ($self, $c) = @_;
     
-        # Allow unauthenticated users to reach the login page
-        if ($c->request->path =~ /login/) {
+        # Allow unauthenticated users to reach the login page.  This
+        # allows anauthenticated users to reach any action in the Login
+        # controller.  To lock it down to a single action, we could use:
+        #   if ($c->action eq $c->controller('Login')->action_for('index'))
+        # to only allow unauthenticated access to the C<index> action we
+        # added above.
+        if ($c->controller eq $c->controller('Login')) {
             return 1;
         }
     
@@ -575,9 +592,18 @@ C<default>, C<index>, and C<auto>.
 
 =item *
 
+With C<begin>, C<end>, C<default>, C<index> private actions, only the
+most specific action of each type will be called.  For example, if you
+define a C<begin> action in your controller it will I<override> a 
+C<begin> action in your application/root controller -- I<only> the
+action in your controller will be called.
+
+=item *
+
 Unlike the other actions where only a single method is called for each 
 request, I<every> auto action along the chain of namespaces will be 
-called.
+called.  Each C<auto> action will be called I<from the application/root
+controller down through the most specific class>.
 
 =back
 
@@ -654,11 +680,11 @@ bottom:
       <a href="[% Catalyst.uri_for('form_create') %]">Create</a>
     </p>
 
-Reload your browser and you should now see a "Login" and "Create" links
-at the bottom of the page (as mentioned earlier, you can update 
-template files without reloading the development server).  Click this 
-link to return to the login page.  This time you I<should> see the 
-"You are already logged in" message.
+Reload your browser and you should now see a "Login" and "Create" links 
+at the bottom of the page (as mentioned earlier, you can update template 
+files without reloading the development server).  Click the first link 
+to return to the login page.  This time you I<should> see the "You are 
+already logged in" message.
 
 Finally, click the C<You can logout here> link on the C</login> page.
 You should stay at the login page, but the message should change to "You
@@ -740,7 +766,8 @@ C<password_hash_type> are new, everything else is the same):
             # This is the model object created by Catalyst::Model::DBIC from your
             # schema (you created 'MyAppDB::User' but as the Catalyst startup
             # debug messages show, it was loaded as 'MyApp::Model::MyAppDB::User').
-            # NOTE: Omit 'MyApp::Model' to avoid a component lookup issue in Catalyst 5.66
+            # NOTE: Omit 'MyApp::Model' here just as you would when using 
+            # '$c->model("MyAppDB::User)'
             user_class: MyAppDB::User
             # This is the name of the field in your 'users' table that contains the user's name
             user_field: username
@@ -764,13 +791,22 @@ You should now be able to go to L<http://localhost:3000/books/list> and
 login as before.  When done, click the "Logout" link on the login page
 (or point your browser at L<http://localhost:3000/logout>).
 
+B<Note:> If you receive the debug screen in your browser with a 
+C<Can't call method "stash" on an undefined value...> error message,
+make sure that you are using v0.07 of 
+L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>.
+The following command can be a useful way to quickly dump the version number
+of this module on your system:
+
+    perl -MCatalyst::Plugin::Authorization::ACL -e 'print $Catalyst::Plugin::Authorization::ACL::VERSION, "\n";'
+
 
 =head1 AUTHOR
 
 Kennedy Clark, C<hkclark@gmail.com>
 
 Please report any errors, issues or suggestions to the author.  The
-most recent version of the Catlayst Tutorial can be found at
+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/>.
 
 Copyright 2006, Kennedy Clark, under Creative Commons License