From: Kennedy Clark <hkclark@gmail.com>
Date: Tue, 24 Feb 2009 17:07:54 +0000 (+0000)
Subject: More updates to action type summary based on input from MST
X-Git-Tag: v5.8005~203
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=245b41d18d896641288e60c37d687ae25c716db1

More updates to action type summary based on input from MST
---

diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
index b6d944d..fef48fe 100644
--- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
@@ -294,43 +294,31 @@ Context object is automatically passed to all Catalyst components.  It
 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:
-
-=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>:
+optional... you will see attributes written both ways).  Most Catalyst 
+Controllers use one of five action types:
 
 =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 @@ controller down through the most specific class>.
 
 =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 @@ for more information on chained actions.
 
 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