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

[hkclark at dev.catalyst.perl.org]

Author: hkclark
Date: 2009-02-24 17:07:54 +0000 (Tue, 24 Feb 2009)
New Revision: 9392

Modified:
   Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
Log:
More updates to action type summary based on input from MST

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 14:46:48 UTC (rev 9391)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod	2009-02-24 17:07:54 UTC (rev 9392)
@@ -294,43 +294,31 @@
 is used to pass information between components and provide access to 
 Catalyst and plugin functionality.
 
-Catalyst actions are regular Perl methods, but they make use 
-of attributes (the "C<: Local>" next to the "C<sub list>" in the code 
+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:
+optional... you will see attributes written both ways).  Most Catalyst 
+Controllers use one of five action types:
 
 =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.
+B<:Private> -- Use C<:Private> for methods that you want to make into 
+an action, but you do not want Catalyst to directly expose the action 
+to your users.  Catalyst will not map C<:Private> methods to a URI. 
+Use them for various sorts of "special" methods (the C<begin>, 
+C<auto>, etc. discussed below) or for methods you want to be able to 
+C<forward> or C<detach> to.  (If the method is a plain old "helper 
+method" that you don't want to be an action at all, then just define 
+the method without any attribute -- you can call it in your code, but 
+the Catalyst dispatcher will ignore it.)
 
 =over 4
 
-There are five types of build-in C<Private> actions: C<begin>, 
-C<end>, C<default>, C<index>, and C<auto>.
+There are five types of "special" build-in C<:Private> actions: 
+C<begin>, C<end>, C<default>, C<index>, and C<auto>.
 
 =item *
 
@@ -351,20 +339,32 @@
 
 =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 
+B<:Path> -- C<:Path> actions let you map a method to an explicit URI 
+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>) 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
+C<http://localhost:3000/books/list> but "C<:Path('/list')>" would match 
+on C<http://localhost:3000/list>.  You can use C<:Args()> to specify 
+how many arguments an action should except.  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 
+B<:Local> -- C<:Local> is merely a shorthand for 
+"C<:Path('_name_of_method_')>".  For example, these are equivalent:
+"C<sub create_book :Local {...}>" and 
+"C<sub create_book :Path('create_book') {...}>".
+
+=item *
+
+B<:Global> -- C<:Global> is merely a shorthand for 
+"C<:Path('/_name_of_method_')>".  For example, these are equivalent:
+"C<sub create_book :Global {...}>" and 
+"C<sub create_book :Path('/create_book') {...}>".
+
+=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 
@@ -376,7 +376,7 @@
 
 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>).
+types not discussed here (C<Regex> and C<LocalRegex>).
 
 
 =head1 CATALYST VIEWS