README
1NAME
2 CGI::Application::Plugin::Forward - Pass control from one run mode to
3 another
4
5VERSION
6 Version 1.06
7
8SYNOPSIS
9 use base 'CGI::Application';
10 use CGI::Application::Plugin::Forward;
11
12 sub setup {
13 my $self = shift;
14 $self->run_modes([qw(
15 start
16 second_runmode
17 )]);
18 }
19 sub start {
20 my $self = shift;
21 return $self->forward('second_runmode');
22 }
23 sub second_runmode {
24 my $self = shift;
25
26 my $rm = $self->get_current_runmode; # 'second_runmode'
27
28 }
29
30DESCRIPTION
31 The forward method passes control to another run mode and returns its
32 output. This is equivalent to calling "$self->$other_runmode", except
33 that CGI::Application's internal value of the current run mode is
34 updated.
35
36 This means that calling "$self->get_current_runmode" after calling
37 "forward" will return the name of the new run mode. This is useful for
38 modules that depend on the name of the current run mode such as
39 CGI::Application::Plugin::AnyTemplate.
40
41 For example, here's how to pass control to a run mode named
42 "other_action" from "start" while updating the value of
43 "current_run_mode":
44
45 sub setup {
46 my $self = shift;
47 $self->run_modes({
48 start => 'start',
49 other_action => 'other_method',
50 });
51 }
52 sub start {
53 my $self = shift;
54 return $self->forward('other_action');
55 }
56 sub other_method {
57 my $self = shift;
58
59 my $rm = $self->get_current_runmode; # 'other_action'
60 }
61
62 Note that forward accepts the *name* of the run mode (in this case
63 *'other_action'*), which might not be the same as the name of the method
64 that handles the run mode (in this case *'other_method'*)
65
66 You can still call "$self->other_method" directly, but
67 "current_run_mode" will not be updated:
68
69 sub setup {
70 my $self = shift;
71 $self->run_modes({
72 start => 'start',
73 other_action => 'other_method',
74 });
75 }
76 sub start {
77 my $self = shift;
78 return $self->other_method;
79 }
80 sub other_method {
81 my $self = shift;
82
83 my $rm = $self->get_current_runmode; # 'start'
84 }
85
86 Forward will work with coderef-based runmodes as well:
87
88 sub setup {
89 my $self = shift;
90 $self->run_modes({
91 start => 'start',
92 anon_action => sub {
93 my $self = shift;
94 my $rm = $self->get_current_runmode; # 'anon_action'
95 },
96 });
97 }
98 sub start {
99 my $self = shift;
100 return $self->forward('anon_action');
101 }
102
103FORWARD vs. REDIRECT
104 Calling "forward" changes the run mode of your application, but it stays
105 within the same HTTP request.
106
107 To redirect to a new runmode using a completely new web request, you
108 might consider using the "redirect" method provided by
109 CGI::Application::Plugin::Redirect.
110
111 The advantage of using an external redirect as opposed to an internal
112 forward is that it provides a 'clean break' between pages.
113
114 For instance, in a typical BREAD application (Browse, Read, Edit, Add,
115 Delete), after the user completes an action, you usually return the user
116 to the Browse list. For instance, when the user adds a new record via a
117 POST form, and your app returns them to the list of records.
118
119 If you use "forward", then you are still in the same request as the
120 original *add record*. The user might hit *reload*, expecting to refresh
121 the list of records. But in fact, *reload* will attempt to repost the
122 *add record* form. The user's browser might present a warning about
123 reposting the same data. The browser may refuse to redisplay the page,
124 due for caching reasons.
125
126 So in this case, it may make more sense to do a fresh HTTP redirect back
127 to the Browse list.
128
129METHODS
130 forward
131 Runs another run mode passing any parameters you supply. Returns the
132 output of the new run mode.
133
134 return $self->forward('run_mode_name', @run_mode_params);
135
136HOOKS
137 Before the forwarded run mode is called, the "forward_prerun" hook is
138 called. You can use this hook to do any prep work that you want to do
139 before any new run mode gains control.
140
141 This is similar to CGI::Application's built in "cgiapp_prerun" method,
142 but it is called each time you call forward; not just the when your
143 application starts.
144
145 sub setup {
146 my $self = shift;
147 $self->add_callback('forward_prerun' => \&prepare_rm_stuff);
148 }
149
150 sub prepare_rm_stuff {
151 my $self = shift;
152 # do any necessary prep work here....
153 }
154
155 Note that your hooked method will only be called when you call forward.
156 If you never call "forward", the hook will not be called. In particuar,
157 the hook will not be called for your application's "start_mode". For
158 that, you still use "cgiapp_prerun".
159
160 If you want to have a method run for every run mode *including* the
161 "start_mode", then you can call the hook directly from "cgiapp_prerun".
162
163 sub setup {
164 my $self = shift;
165 $self->add_callback('forward_prerun' => \&prepare_rm_stuff);
166 }
167 sub cgiapp_prerun {
168 my $self = shift;
169 $self->prepare_rm_stuff;
170 }
171
172 sub prepare_rm_stuff {
173 my $self = shift;
174 # do any necessary prep work here....
175 }
176
177 Alternately, you can hook "cgiapp_prerun" to the "forward_prerun" hook:
178
179 sub setup {
180 my $self = shift;
181 $self->add_callback('forward_prerun' => \&cgiapp_prerun);
182 }
183 sub cgiapp_prerun {
184 my $self = shift;
185 # do any necessary prep work here....
186 }
187
188 This is a less flexible solution, since certain things that can be done
189 in "cgiapp_prerun" (like setting "prerun_mode") won't work when the
190 method is called from the "forward_prerun" hook.
191
192AUTHOR
193 Michael Graham, "<mag-perl@occamstoothbrush.com>"
194
195BUGS
196 Please report any bugs or feature requests to
197 "bug-cgi-application-plugin-forward@rt.cpan.org", or through the web
198 interface at <http://rt.cpan.org>. I will be notified, and then you'll
199 automatically be notified of progress on your bug as I make changes.
200
201ACKNOWLEDGEMENTS
202 Thanks to Mark Stosberg for the idea and...well...the implementation as
203 well.
204
205COPYRIGHT & LICENSE
206 Copyright 2005 Michael Graham, All Rights Reserved.
207
208 This program is free software; you can redistribute it and/or modify it
209 under the same terms as Perl itself.
210
211