From: Kennedy Clark <hkclark@gmail.com>
Date: Tue, 24 Feb 2009 02:52:47 +0000 (+0000)
Subject: Misc updates in support of moving to Chained
X-Git-Tag: v5.8005~206
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=e075db0c03ded5b1d100852f9ba9c040e2499109

Misc updates in support of moving to Chained
---

diff --git a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod
index 80c872c..03d9273 100644
--- a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod
+++ b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod
@@ -156,7 +156,7 @@ following method:
             # Set a status message for the user
             $c->flash->{status_msg} = 'Book created';
             # Return to the books list
-            $c->response->redirect($c->uri_for('list')); 
+            $c->response->redirect($c->uri_for($self->action_for('list'))); 
             $c->detach;
         } else {
             # Get the authors from the DB
@@ -260,7 +260,7 @@ Open C<root/src/books/formfu_create.tt2> in your editor and enter the following:
     [%# Render the HTML::FormFu Form %]
     [% form %]
     
-    <p><a href="[% c.uri_for('list') %]">Return to book list</a></p>
+    <p><a href="[% c.uri_for(c.controller.action_for('list')) %]">Return to book list</a></p>
 
 
 =head2 Add Links for Create and Update via C<HTML::FormFu>
@@ -270,7 +270,7 @@ the bottom of the existing file:
 
     <p>
       HTML::FormFu:
-      <a href="[% c.uri_for('formfu_create') %]">Create</a>
+      <a href="[% c.uri_for(c.controller.action_for('formfu_create')) %]">Create</a>
     </p>
 
 This adds a new link to the bottom of the book list page that we can
@@ -473,7 +473,7 @@ bottom:
         # Make sure we were able to get a book
         unless ($book) {
             $c->flash->{error_msg} = "Invalid book -- Cannot edit";
-            $c->response->redirect($c->uri_for('list'));
+            $c->response->redirect($c->uri_for($self->action_for('list')));
             $c->detach;
         }
     
@@ -489,7 +489,7 @@ bottom:
             # Set a status message for the user
             $c->flash->{status_msg} = 'Book edited';
             # Return to the books list
-            $c->response->redirect($c->uri_for('list'));
+            $c->response->redirect($c->uri_for($self->action_for('list')));
             $c->detach;
         } else {
             # Get the authors from the DB
@@ -553,9 +553,9 @@ following:
     ...
     <td>
       [% # Add a link to delete a book %]
-      <a href="[% c.uri_for('delete', book.id) %]">Delete</a>
+      <a href="[% c.uri_for(c.controller.action_for('delete', [book.id])) %]">Delete</a>
       [% # Add a link to edit a book %]
-      <a href="[% c.uri_for('formfu_edit', book.id) %]">Edit</a>
+      <a href="[% c.uri_for(c.controller.action_for('formfu_edit', [book.id])) %]">Edit</a>
     </td>
     ...
 
diff --git a/lib/Catalyst/Manual/Tutorial/Authentication.pod b/lib/Catalyst/Manual/Tutorial/Authentication.pod
index 63c346c..d8c4978 100644
--- a/lib/Catalyst/Manual/Tutorial/Authentication.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authentication.pod
@@ -417,7 +417,7 @@ and partly for code clarity) only to use C<default> in
 C<MyApp::Controller::Root>, and then mainly to generate the 404 not 
 found page for the application.
 
-Instead, we are using C<sub base :Path :Args(0) {...}> here to
+Instead, we are using C<sub somename :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
@@ -525,36 +525,42 @@ the following method:
     }
 
 
-B<Note:> Catalyst provides a number of different types of actions,
-such as C<Local>, C<Regex>, C<Private> and the new C<Path>.  You
-should refer to L<Catalyst::Manual::Intro|Catalyst::Manual::Intro> for
-a more detailed explanation, but the following bullet points provide a
-quick introduction:
+B<Note:> Catalyst provides a number of different types of actions, 
+such as C<Chained>, C<Local>, C<Regex>, C<Private> and C<Path>.  You 
+should refer to L<Catalyst::Manual::Intro/Action_types> for a more 
+detailed explanation, but the following bullet points provide a quick 
+introduction:
 
 =over 4
 
 =item *
 
-The majority of applications have traditionally used C<Local> actions
-for items that respond to user requests and C<Private> actions for
-those that do not directly respond to user input.
+In the past, the majority of applications have traditionally used 
+C<Local> actions for items that respond to user requests and 
+C<Private> actions for those that do not directly respond to user 
+input.
 
 =item *
 
-Newer Catalyst applications tend to use C<Path> actions and the
-C<Args> attribute because of their power and flexibility.  You can
-specify the path to match relative to the namespace of the current
-module as an argument to C<Path>.  For example C<Path('list')> in
-C<lib/MyApp/Controller/Books.pm> would match on the URL
-C<http://localhost:3000/books/list> but C<Path('/list')> would
-match on C<http://localhost:3000/list>.
+As discussed in Part 4 of the tutorial, newer Catalyst applications 
+tend to use the Chained dispatch form of action types because of its
+power and flexibility. See 
+L<Catalyst::Manual::Tutorial::BasicCRUD|Catalyst::Manual::Tutorial::BasicCRUD>
+and
+L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained>
+for more information on chained actions.
 
 =item *
 
-Automatic "chaining" of actions by the dispatcher is a powerful
-feature that allows multiple methods to handle a single URL.  See
-L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained>
-for more information on chained actions.
+C<Path> actions provide a limited subset of what can be found done 
+with Chained actions.  You can match on different portions of the URI 
+(for example C<Path('list')> in C<lib/MyApp/Controller/Books.pm> would 
+match on the URL C<http://localhost:3000/books/list> but 
+C<Path('/list')> would match on C<http://localhost:3000/list>).  You 
+can also specify the number of arguments to match via C<Args> much 
+like the endpoint of a chain.  However, becaused Chained actions offer 
+these features and so much more (at the expense of some additional 
+complexity), Chained action types are generally recommened.
 
 =item *
 
diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod
index d340d20..b59facf 100644
--- a/lib/Catalyst/Manual/Tutorial/Authorization.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod
@@ -162,13 +162,13 @@ lines to the bottom of the file:
     [% # Use $c->check_user_roles() to check authz -%]
     [% IF c.check_user_roles('user') %]
       [% # Give normal users a link for 'logout' %]
-      <a href="[% c.uri_for('/logout') %]">Logout</a>
+      <a href="[% c.uri_for('/logout') %]">User Logout</a>
     [% END %]
     
     [% # Can also use $c->user->check_roles() to check authz -%]
     [% IF c.check_user_roles('admin') %]
       [% # Give admin users a link for 'create' %]
-      <a href="[% c.uri_for('form_create') %]">Create</a>
+      <a href="[% c.uri_for(c.controller('books').action_for('form_create')) %]">Admin Create</a>
     [% END %]
     </p>
 
@@ -195,7 +195,7 @@ updating C<url_create> to match the following code:
     
     =cut
     
-    sub url_create : Local {
+    sub url_create :Chained('base') :PathPart('url_create') :Args(3) {
         # In addition to self & context, get the title, rating & author_id args
         # from the URL.  Note that Catalyst automatically puts extra information
         # after the "/<controller_name>/<action_name/" into @_
@@ -230,7 +230,7 @@ updating C<url_create> to match the following code:
             # Set the TT template to use
             $c->stash->{template} = 'books/create_done.tt2';
         } else {
-            # Provide very simple feedback to the user
+            # Provide very simple feedback to the user.
             $c->response->body('Unauthorized!');
         }
     }
@@ -244,12 +244,12 @@ way to demonstrate that TT templates will not be used if the response
 body has already been set.  In reality you would probably want to use a
 technique that maintains the visual continuity of your template layout
 (for example, using the "status" or "error" message feature added in
-Part 3).
+Part 3 or C<detach> to an action that shows an "unauthorized" page).
 
 B<TIP>: If you want to keep your existing C<url_create> method, you can
 create a new copy and comment out the original by making it look like a
-Pod comment.  For example, put something like C<=begin> before C<sub add
-: Local {> and C<=end> after the closing C<}>.
+Pod comment.  For example, put something like C<=begin> before 
+C<sub add : Local {> and C<=end> after the closing C<}>.
 
 
 =head2 Try Out Authentication And Authorization
@@ -408,7 +408,7 @@ Then run the Catalyst development server script:
 Log in as C<test02>.  Once at the book list, click the "Create" link
 to try the C<form_create> action.  You should receive a red
 "Unauthorized!"  error message at the top of the list.  (Note that in
-the example code the "Create" link code in C<root/src/books/list.tt2>
+the example code the "Admin Create" link code in C<root/src/books/list.tt2>
 is inside an C<IF> statement that only displays the list to
 admin-level users.)  If you log in as C<test01> you should be able to
 view the C<form_create> form and add a new book.
diff --git a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
index 78db797..d636da4 100644
--- a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
+++ b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
@@ -1,4 +1,4 @@
-=head1 NAME
+ =head1 NAME
 
 Catalyst::Manual::Tutorial::BasicCRUD - Catalyst Tutorial - Part 4: Basic CRUD
 
@@ -620,7 +620,7 @@ and 2) the four lines for the Delete link near the bottom).
         </td>
         <td>
           [% # Add a link to delete a book %]
-          <a href="[% c.uri_for(c.controller.action_for('delete'), [ book.id ]) %]">Delete</a>
+          <a href="[% c.uri_for(c.controller.action_for('delete'), [book.id]) %]">Delete</a>
         </td>
       </tr>
     [% END -%]
@@ -663,6 +663,13 @@ operate on an existing book can chain directly off base.
 To add the C<object> method, edit C<lib/MyApp/Controller/Books.pm>
 and add the following code:
 
+    =head2 object
+    
+    Fetch the specified book object based on the book ID and store
+    it in the stash
+    
+    =cut
+    
     sub object :Chained('base') :PathPart('id') :CaptureArgs(1) {
         my ($self, $c, $id) = @_;
         
@@ -814,7 +821,7 @@ C<sub delete> method to match:
         $c->stash->{status_msg} = "Book deleted.";
     
         # Redirect the user back to the list page
-        $c->response->redirect($c->uri_for($c->controller->action_for('list'));
+        $c->response->redirect($c->uri_for($self->action_for('list'));
     }
 
 
@@ -856,7 +863,7 @@ method to match the following:
         $c->stash->{object}->delete;
     
         # Redirect the user back to the list page with status msg as an arg
-        $c->response->redirect($c->uri_for($c->controller->action_for('list'), 
+        $c->response->redirect($c->uri_for($self->action_for('list'), 
             {status_msg => "Book deleted."}));
     }