fix methods and action names to match the next example (which is supposed to be equiv...

[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Intro.pod

diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index abef245..a5acd72 100644 (file)
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -23,7 +23,7 @@ possible to do things in a different way. Other web frameworks are
 I<initially> simpler to use, but achieve this by locking the programmer
 into a single set of tools. Catalyst's emphasis on flexibility means
 that you have to think more to use it. We view this as a feature.  For
-example, this leads to Catalyst being more suited to system integration
+example, this leads to Catalyst being better suited to system integration
 tasks than other web frameworks.
 
 =head3 MVC
@@ -53,7 +53,7 @@ L<Mason|HTML::Mason>, L<HTML::Template>...
 =item * B<Controller>
 
 Control the whole request phase, check parameters, dispatch actions, flow
-control. Catalyst itself!
+control. This is the meat of where Catalyst works.
 
 =back
 
@@ -104,7 +104,7 @@ example:
 
 Now http://localhost:3000/hello prints "Hello World!".
 
-Note that actions with the C< :Global > attribute are equivalent to
+Note that actions with the C< :Local > attribute are equivalent to
 using a C<:Path('action_name') > attribute, so our action could be
 equivalently:
 
@@ -122,6 +122,12 @@ separately - which will turn the built server into a fully fledged production
 ready server (although you'll probably want to run it behind a front end proxy
 if you end up using it).
 
+=item * PSGI Support
+
+Starting with Catalyst version 5.9 Catalyst ships with L<PSGI> integration
+for even more powerful and flexible testing and deployment options.  See
+L<Catalyst::PSGI> for details.
+
 =back
 
 =head3 Simplicity
@@ -476,9 +482,9 @@ application.
 
     use base qw/Catalyst::Controller/;
 
-    sub login : Path("login") { }
+    sub sign_in : Path("sign-in") { }
     sub new_password : Path("new-password") { }
-    sub logout : Path("logout") { }
+    sub sign_out : Path("sign-out") { }
 
     package MyApp::Controller::Catalog;
 
@@ -784,7 +790,7 @@ of Catalyst component class names.
 
 =item * B<Overriding the namespace>
 
-Note that __PACKAGE__->config->{namespace} can be used to override the
+Note that I<< __PACKAGE__->config->(namespace => ... ) >> can be used to override the
 current namespace when matching.  So:
 
     package MyApp::Controller::Example;
@@ -792,7 +798,7 @@ current namespace when matching.  So:
 would normally use 'example' as its namespace for matching, but if
 this is specially overridden with
 
-    __PACKAGE__->config->{namespace}='thing';
+    __PACKAGE__->config( namespace => 'thing' );
 
 it matches using the namespace 'thing' instead.
 
@@ -804,25 +810,29 @@ application (e.g. http://localhost:3000/ ):
 
     package MyApp::Controller::Root;
     use base 'Catalyst::Controller';
+
     # Sets the actions in this controller to be registered with no prefix
     # so they function identically to actions created in MyApp.pm
-    __PACKAGE__->config->{namespace} = '';
+
+    __PACKAGE__->config( namespace => '');
+
     sub default : Path  {
         my ( $self, $context ) = @_;
         $context->response->status(404);
         $context->response->body('404 not found');
     }
+
     1;
 
 
 The code
 
-    __PACKAGE__->config->{namespace} = '';
+    __PACKAGE__->config( namespace => '' );
 
 makes the controller act as if its namespace is empty.  As you'll see
-below, an empty namespace makes many of the URL-matching attributes,
-such as :Path, :Local and :Global matches, match at the start of the
-URL path.
+below, an empty namespace makes many of the URL-matching attributes, such
+as :Path and :Local match at the start of the URL path (i.e. the
+application root).
 
 =back
 
@@ -850,20 +860,30 @@ subroutine name together determine the path.
 =item * Root-level (C<:Global>)
 
     package MyApp::Controller::Foo;
-    sub foo : Global { }
 
-Matches http://localhost:3000/foo - that is, the action is mapped
-directly to the controller namespace, ignoring the function name.
+    sub bar : Global {
+        my ($self, $c) = @_;
+        $c->res->body(
+          $c->res->body('sub bar in Controller::Foo triggered on a request for '
+                         . $c->req->uri));
+    }
 
-C<:Global> always matches from root: it is sugar for C<:Path('/methodname')>.
-C<:Local> is simply sugar for C<:Path('methodname')>, which takes the package
-namespace as described above.
+1;
 
-    package MyApp::Controller::Root;
-    __PACKAGE__->config->{namespace}='';
-    sub foo : Local { }
+Matches http://localhost:3000/bar - that is, the action is mapped
+directly to the method name, ignoring the controller namespace.
+
+C<:Global> always matches from the application root: it is simply
+shorthandfor C<:Path('/methodname')>.  C<:Local> is shorthand for
+C<:Path('methodname')>, which takes the controller namespace as described
+above.
 
-Use whichever makes the most sense for your application.
+Usage of the C<Global> handler is rare in all but very old Catalyst
+applications (e.g. before Catalyst 5.7).  The use cases where C<Global>
+used to make sense are now largely replaced by the C<Chained> dispatch
+type, or by empty C<Path> declarations on an controller action.  C<Global>
+is still included in Catalyst for backwards compatibility, although
+legitimate use-cases for it may still exist.
 
 =item * Changing handler behaviour: eating arguments (C<:Args>)
 
@@ -1099,7 +1119,7 @@ turn.
     sub auto : Private { }
 
 C<auto>, however, doesn't override like this: providing they exist,
-C<MyApp::auto>, C<MyApp::Controller::Catalog::auto> and
+C<MyApp::Controller::Root::auto>, C<MyApp::Controller::Catalog::auto> and
 C<MyApp::Catalog::Order::auto> would be called in turn.
 
 Here are some examples of the order in which the various built-ins