| 1 |
NAME |
| 2 |
CGI::Application::Plugin::Forward - Pass control from one run mode to |
| 3 |
another |
| 4 |
|
| 5 |
VERSION |
| 6 |
Version 1.06 |
| 7 |
|
| 8 |
SYNOPSIS |
| 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 |
|
| 30 |
DESCRIPTION |
| 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 |
|
| 103 |
FORWARD 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 |
|
| 129 |
METHODS |
| 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 |
|
| 136 |
HOOKS |
| 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 |
|
| 192 |
AUTHOR |
| 193 |
Michael Graham, "<[email protected]>" |
| 194 |
|
| 195 |
BUGS |
| 196 |
Please report any bugs or feature requests to |
| 197 |
"[email protected]", 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 |
|
| 201 |
ACKNOWLEDGEMENTS |
| 202 |
Thanks to Mark Stosberg for the idea and...well...the implementation as |
| 203 |
well. |
| 204 |
|
| 205 |
COPYRIGHT & 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 |
|