[Catalyst-commits] r9391 - Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial

hkclark at dev.catalyst.perl.org hkclark at dev.catalyst.perl.org
Tue Feb 24 14:46:48 GMT 2009


Author: hkclark
Date: 2009-02-24 14:46:48 +0000 (Tue, 24 Feb 2009)
New Revision: 9391

Modified:
   Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod
   Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authorization.pod
   Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
   Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
Log:
More updates for Chained.  Rewrite the discussion about different action types and move it into MoreCatalystBasics.pod.

Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod	2009-02-24 03:22:26 UTC (rev 9390)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod	2009-02-24 14:46:48 UTC (rev 9391)
@@ -392,7 +392,8 @@
             if ($c->authenticate({ username => $username,
                                    password => $password  } )) {
                 # If successful, then let them use the application
-                $c->response->redirect($c->uri_for('/books/list'));
+                $c->response->redirect($c->uri_for(
+                    $c->controller('Books')->action_for('list')));
                 return;
             } else {
                 # Set an error message
@@ -524,71 +525,16 @@
         return 1;
     }
 
+As discussed in 
+L<Catalyst::Manual::Tutorial::MoreCatalystBasics/CREATE A CATALYST CONTROLLER>, 
+every C<auto> method from the application/root controller down to the 
+most specific controller will be called.  By placing the 
+authentication enforcement code inside the C<auto> method of 
+C<lib/MyApp/Controller/Root.pm> (or C<lib/MyApp.pm>), it will be 
+called for I<every> request that is received by the entire 
+application.
 
-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 *
-
-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 *
-
-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 *
-
-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 *
-
-There are five types of build-in C<Private> actions: C<begin>, C<end>,
-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.  Each C<auto> action will be called I<from the application/root
-controller down through the most specific class>.
-
-=back
-
-By placing the authentication enforcement code inside the C<auto> method
-of C<lib/MyApp/Controller/Root.pm> (or C<lib/MyApp.pm>), it will be
-called for I<every> request that is received by the entire application.
-
-
 =head2 Displaying Content Only to Authenticated Users
 
 Let's say you want to provide some information on the login page that
@@ -655,7 +601,7 @@
 
     <p>
       <a href="[% c.uri_for('/login') %]">Login</a>
-      <a href="[% c.uri_for('form_create') %]">Create</a>
+      <a href="[% c.uri_for(c.controller.action_for('form_create')) %]">Create</a>
     </p>
 
 Reload your browser and you should now see a "Login" and "Create" links
@@ -820,7 +766,7 @@
         $c->flash->{status_msg} = "Book deleted";
     
         # Redirect the user back to the list page
-        $c->response->redirect($c->uri_for('/books/list'));
+        $c->response->redirect($c->uri_for($self->action_for('list')));
     }
 
 Next, open C<root/src/wrapper.tt2> and update the TT code to pull from

Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authorization.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authorization.pod	2009-02-24 03:22:26 UTC (rev 9390)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authorization.pod	2009-02-24 14:46:48 UTC (rev 9391)
@@ -168,7 +168,7 @@
     [% # 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(c.controller('books').action_for('form_create')) %]">Admin Create</a>
+      <a href="[% c.uri_for(c.controller.action_for('form_create')) %]">Admin Create</a>
     [% END %]
     </p>
 

Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod	2009-02-24 03:22:26 UTC (rev 9390)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod	2009-02-24 14:46:48 UTC (rev 9391)
@@ -631,13 +631,32 @@
 links will be used instead of full HTML buttons).
 
 Also notice that we are using a more advanced form of C<uri_for> than 
-we have seen before.  Here we use C<$c-E<gt>controller-E<gt>action_for>
-to automatically generate a URI appropriate for that action while
-inserting the C<book.id> value into the appropriate place.  Now, if 
-you ever change C<:PathPart('delete')> in your controller method to
-C<:PathPart('kill')>, then your links will automatically update without
-any changes to your .tt2 template file.
+we have seen before.  Here we use C<$c-E<gt>controller-
+E<gt>action_for> to automatically generate a URI appropriate for that 
+action based on the method we want to link to while inserting the 
+C<book.id> value into the appropriate place.  Now, if you ever change 
+C<:PathPart('delete')> in your controller method to 
+C<:PathPart('kill')>, then your links will automatically update 
+without any changes to your .tt2 template file.  As long as the name 
+of your method does not changed ("delete" here), then your links will 
+still be correct.  There are a few shortcuts and options when using
+C<action_for()>:
 
+=over 4
+
+=item *
+
+If you are referring to a method in the current controller, you can
+use C<$self-E<gt>action_for('_method_name_')>.
+
+=item *
+
+If you are referring to a method in a different controller, you need
+to include that as an argument to C<controller()>, as in
+C<$c-E<gt>controller('_controller_name_')-E<gt>action_for('_method_name_')>.
+
+=back
+
 B<Note:> You should use more than just a simple link with your 
 applications. Consider using some sort of of confirmation page 
 (typically with unique actions in your controller for both the 
@@ -820,7 +839,8 @@
         # Set a status message to be displayed at the top of the view
         $c->stash->{status_msg} = "Book deleted.";
     
-        # Redirect the user back to the list page
+        # Redirect the user back to the list page.  Note the use
+        # of $self->action_for as earlier in this section (BasicCRUD)
         $c->response->redirect($c->uri_for($self->action_for('list'));
     }
 

Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod	2009-02-24 03:22:26 UTC (rev 9390)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod	2009-02-24 14:46:48 UTC (rev 9391)
@@ -294,28 +294,91 @@
 is used to pass information between components and provide access to 
 Catalyst and plugin functionality.
 
-B<Note:> Catalyst actions are regular Perl methods, but they make use 
-of Nicholas Clark's C<attributes> module (that's the "C<: Local>" next 
-to the C<sub list> in the code above) to provide additional 
-information to the Catalyst dispatcher logic.  Many newer Catalyst 
-applications are switching to the use of "Literal" C<:Path> actions 
-and C<Args> attribute in lieu of C<: Local> and C<: Private>.  For 
-example, C<sub any_method :Path :Args(0)> can be used instead of C<sub 
-index :Private> (because no path was supplied to C<Path> it matches 
-the "empty" URL in the namespace of that module... the same thing 
-C<sub index> would do) or C<sub list :Path('list') :Args(0)> could be 
-used instead of the C<sub list : Local> above (the C<list> argument to 
-C<Path> would make it match on the URL C<list> under C<books>, the 
-namespace of the current module).  See "Action Types" in 
-L<Catalyst::Manual::Intro|Catalyst::Manual::Intro> as well as Part 5 
-of this tutorial (Authentication) for additional information.  Another 
-popular but more advanced feature is C<Chained> actions that allow a 
-single URL to "chain together" multiple action method calls, each with 
-an appropriate number of arguments (see 
-L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained> for 
-details).
+Catalyst actions are regular Perl methods, but they make use 
+of attributes (the "C<: Local>" next to the "C<sub list>" in the code 
+above) to provide additional information to the Catalyst dispatcher 
+logic (note that the space between the colon and the attribute name is 
+optional... you will see them written both ways).  Over time, the 
+recommended style for most Catalyst applications has changed:
 
+=over 4
 
+=item * From "C<:Local>" and "C<:Private>"
+
+=item * To "C<:Path>" and "C<:Args>"
+
+=item * To "C<:Chained>"
+
+=back
+
+Although all three styles work just fine, the newer forms offer more 
+advanced capbilities and allow you to be more expressive with the URIs 
+that your application uses.
+
+Here is a quick summary of the most commonly used action types: 
+C<Local>, C<Private>, C<Path> and C<Chained>:
+
+=over 4
+
+=item *
+
+B<Local and Private> -- 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.
+
+=over 4
+
+There are five types of build-in C<Private> actions: C<begin>, 
+C<end>, 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.  Each C<auto> action will be called I<from the application/root
+controller down through the most specific class>.
+
+=back
+
+=item *
+
+B<Path> -- C<Path> actions were the next style of action types to
+become popular and essentially 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>) and it let's you be very specific with
+what arguments each controller method will accept.  See
+L<Catalyst::Manual::Intro/Action_types> for more information and a few
+examples.
+
+=item *
+
+B<Chained> -- Newer Catalyst applications tend to use the Chained 
+dispatch form of action types because of its power and flexibility.  
+It allows a series of controller methods to automatically be dispatched
+to service a single user request.  See 
+L<Catalyst::Manual::Tutorial::BasicCRUD|Catalyst::Manual::Tutorial::BasicCRUD> 
+and L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained> 
+for more information on chained actions.
+
+=back
+
+You should refer to L<Catalyst::Manual::Intro/Action_types> for 
+additional information and for coverage of some lesser-used action 
+types not discussed here (C<Regex>, C<LocalRegex> and C<Global>).
+
+
 =head1 CATALYST VIEWS
 
 As mentioned in Part 2 of the tutorial, views are where you render 




More information about the Catalyst-commits mailing list