1CGI::Application::PlugiUns:e:rFoCrownatrrdi(b3u)ted PerlCGDIo:c:uAmpepnltiactaitoinon::Plugin::Forward(3)
2
3
4

NAME

6       CGI::Application::Plugin::Forward - Pass control from one run mode to
7       another
8

VERSION

10       Version 1.06
11

SYNOPSIS

13           use base 'CGI::Application';
14           use CGI::Application::Plugin::Forward;
15
16           sub setup {
17               my $self = shift;
18               $self->run_modes([qw(
19                   start
20                   second_runmode
21               )]);
22           }
23           sub start {
24               my $self = shift;
25               return $self->forward('second_runmode');
26           }
27           sub second_runmode {
28               my $self = shift;
29
30               my $rm = $self->get_current_runmode;  # 'second_runmode'
31
32           }
33

DESCRIPTION

35       The forward method passes control to another run mode and returns its
36       output.  This is equivalent to calling "$self->$other_runmode", except
37       that CGI::Application's internal value of the current run mode is
38       updated.
39
40       This means that calling "$self->get_current_runmode" after calling
41       "forward" will return the name of the new run mode.  This is useful for
42       modules that depend on the name of the current run mode such as
43       CGI::Application::Plugin::AnyTemplate.
44
45       For example, here's how to pass control to a run mode named
46       "other_action" from "start" while updating the value of
47       "current_run_mode":
48
49           sub setup {
50               my $self = shift;
51               $self->run_modes({
52                   start         => 'start',
53                   other_action  => 'other_method',
54               });
55           }
56           sub start {
57               my $self = shift;
58               return $self->forward('other_action');
59           }
60           sub other_method {
61               my $self = shift;
62
63               my $rm = $self->get_current_runmode;  # 'other_action'
64           }
65
66       Note that forward accepts the name of the run mode (in this case
67       'other_action'), which might not be the same as the name of the method
68       that handles the run mode (in this case 'other_method')
69
70       You can still call "$self->other_method" directly, but
71       "current_run_mode" will not be updated:
72
73           sub setup {
74               my $self = shift;
75               $self->run_modes({
76                   start         => 'start',
77                   other_action  => 'other_method',
78               });
79           }
80           sub start {
81               my $self = shift;
82               return $self->other_method;
83           }
84           sub other_method {
85               my $self = shift;
86
87               my $rm = $self->get_current_runmode;  # 'start'
88           }
89
90       Forward will work with coderef-based runmodes as well:
91
92           sub setup {
93               my $self = shift;
94               $self->run_modes({
95                   start         => 'start',
96                   anon_action   => sub {
97                       my $self = shift;
98                       my $rm = $self->get_current_runmode;  # 'anon_action'
99                   },
100               });
101           }
102           sub start {
103               my $self = shift;
104               return $self->forward('anon_action');
105           }
106

FORWARD vs. REDIRECT

108       Calling "forward" changes the run mode of your application, but it
109       stays within the same HTTP request.
110
111       To redirect to a new runmode using a completely new web request, you
112       might consider using the "redirect" method provided by
113       CGI::Application::Plugin::Redirect.
114
115       The advantage of using an external redirect as opposed to an internal
116       forward is that it provides a 'clean break' between pages.
117
118       For instance, in a typical BREAD application (Browse, Read, Edit, Add,
119       Delete), after the user completes an action, you usually return the
120       user to the Browse list.  For instance, when the user adds a new record
121       via a POST form, and your app returns them to the list of records.
122
123       If you use "forward", then you are still in the same request as the
124       original add record.  The user might hit reload, expecting to refresh
125       the list of records.  But in fact, reload will attempt to repost the
126       add record form.  The user's browser might present a warning about
127       reposting the same data.  The browser may refuse to redisplay the page,
128       due for caching reasons.
129
130       So in this case, it may make more sense to do a fresh HTTP redirect
131       back to the Browse list.
132

METHODS

134   forward
135       Runs another run mode passing any parameters you supply.  Returns the
136       output of the new run mode.
137
138           return $self->forward('run_mode_name', @run_mode_params);
139

HOOKS

141       Before the forwarded run mode is called, the "forward_prerun" hook is
142       called. You can use this hook to do any prep work that you want to do
143       before any new run mode gains control.
144
145       This is similar to CGI::Application's built in "cgiapp_prerun" method,
146       but it is called each time you call forward; not just the when your
147       application starts.
148
149           sub setup {
150               my $self = shift;
151               $self->add_callback('forward_prerun' => \&prepare_rm_stuff);
152           }
153
154           sub prepare_rm_stuff {
155               my $self = shift;
156               # do any necessary prep work here....
157           }
158
159       Note that your hooked method will only be called when you call forward.
160       If you never call "forward", the hook will not be called.  In
161       particuar, the hook will not be called for your application's
162       "start_mode".  For that, you still use "cgiapp_prerun".
163
164       If you want to have a method run for every run mode including the
165       "start_mode", then you can call the hook directly from "cgiapp_prerun".
166
167           sub setup {
168               my $self = shift;
169               $self->add_callback('forward_prerun' => \&prepare_rm_stuff);
170           }
171           sub cgiapp_prerun {
172               my $self = shift;
173               $self->prepare_rm_stuff;
174           }
175
176           sub prepare_rm_stuff {
177               my $self = shift;
178               # do any necessary prep work here....
179           }
180
181       Alternately, you can hook "cgiapp_prerun" to the "forward_prerun" hook:
182
183           sub setup {
184               my $self = shift;
185               $self->add_callback('forward_prerun' => \&cgiapp_prerun);
186           }
187           sub cgiapp_prerun {
188               my $self = shift;
189               # do any necessary prep work here....
190           }
191
192       This is a less flexible solution, since certain things that can be done
193       in "cgiapp_prerun" (like setting "prerun_mode") won't work when the
194       method is called from the "forward_prerun" hook.
195

AUTHOR

197       Michael Graham, "<mag-perl@occamstoothbrush.com>"
198

BUGS

200       Please report any bugs or feature requests to
201       "bug-cgi-application-plugin-forward@rt.cpan.org", or through the web
202       interface at <http://rt.cpan.org>.  I will be notified, and then you'll
203       automatically be notified of progress on your bug as I make changes.
204

ACKNOWLEDGEMENTS

206       Thanks to Mark Stosberg for the idea and...well...the implementation as
207       well.
208
210       Copyright 2005 Michael Graham, All Rights Reserved.
211
212       This program is free software; you can redistribute it and/or modify it
213       under the same terms as Perl itself.
214
215
216
217perl v5.34.0                      2022-01-2C0GI::Application::Plugin::Forward(3)
Impressum