From: Tomas Doran <bobtfish@bobtfish.net>
Date: Sun, 4 Oct 2009 00:01:16 +0000 (+0000)
Subject: Clean up and add to the docs about forwarding.
X-Git-Tag: v5.8005~101
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=eecdf6ee1aafd7245b4970c7f92fe5dc3345aa23

Clean up and add to the docs about forwarding.
---

diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index f0895f5..e4d7fda 100644
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -1262,9 +1262,9 @@ be reset.
         # now $c->req->args is back to what it was before
     }
 
-    sub check_message : Private {
-        my ( $self, $c ) = @_;
-        my $first_argument = $c->req->args->[0]; # now = 'test1'
+    sub check_message : Action {
+        my ( $self, $c, $first_argument ) = @_;
+        my $also_first_argument = $c->req->args->[0]; # now = 'test1'
         # do something...
     }
 
@@ -1276,14 +1276,11 @@ you will have to refer to the method by absolute path.
   $c->forward('/my/controller/action');
   $c->forward('/default'); # calls default in main application
 
-Here are some examples of how to forward to classes and methods.
-
-    # FIXME - Forwarding to a model is unusual, a better example would show
-    #         forwarding to render in TT which is useful for drawing sub-parts of pages..
+You can also forward to classes and methods.
 
     sub hello : Global {
         my ( $self, $c ) = @_;
-        $c->forward(qw/MyApp::Model::Hello say_hello/);
+        $c->forward(qw/MyApp::View:Hello say_hello/);
     }
 
     sub bye : Global {
@@ -1291,7 +1288,7 @@ Here are some examples of how to forward to classes and methods.
         $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
     }
 
-    package MyApp::Model::Hello;
+    package MyApp::View::Hello;
 
     sub say_hello {
         my ( $self, $c ) = @_;
@@ -1303,6 +1300,28 @@ Here are some examples of how to forward to classes and methods.
         $c->res->body('Goodbye World!');
     }
 
+This mechanism is used by L<Catalyst::Action::RenderView> to forward
+to the C<process> method in a view class.
+
+It should be noted that whilst forward is useful, it is not the only way
+of calling other code in Catalyst. Forward just gives you stats in the debug
+screen, wraps the code you're calling in an exception handler and localises
+C<< $c->request->args >>.
+
+If you don't want or need these features then it's perfectly acceptable
+(and faster) to do something like this:
+
+sub hello : Global {
+    my ( $self, $c ) = @_;
+    $c->stash->{message} = 'Hello World!';
+    $self->check_message( $c, 'test1' );
+}
+
+sub check_message {
+    my ( $self, $c, $first_argument ) = @_;
+    # do something...
+}
+
 Note that C<forward> returns to the calling action and continues
 processing after the action finishes. If you want all further processing
 in the calling action to stop, use C<detach> instead, which will execute
@@ -1310,7 +1329,6 @@ the C<detach>ed action and not return to the calling sub. In both cases,
 Catalyst will automatically try to call process() if you omit the
 method.
 
-
 =head3 Testing
 
 Catalyst has a built-in http server for testing or local