1AutoRunmode(3)        User Contributed Perl Documentation       AutoRunmode(3)
2
3
4

NAME

6       CGI::Application::Plugin::AutoRunmode - CGI::App plugin to
7       automatically register runmodes
8

SYNOPSIS

10       Using subroutine attributes:
11
12               package MyApp;
13               use base 'CGI::Application';
14               use CGI::Application::Plugin::AutoRunmode;
15
16               sub my_run_mode : StartRunmode {
17                       # do something here
18               }
19
20               sub another_run_mode : Runmode {
21                       # do something else
22               }
23
24               # you now have two run modes
25               # "my_run_mode" and "another_run_mode"
26               # "my_run_mode" is the start (default) run mode
27
28       Declare that every method in a (delegate) class is a run mode.
29
30               package MyAppRunmodes;
31               # the delegate class
32                       sub my_run_mode  {
33                               my ($app, $delegate) = @_;
34                                       # do something here
35                       }
36
37                       sub another_run_mode  {
38                                       # do something else
39                       }
40
41               package MyApp;
42               use base 'CGI::Application';
43
44                       sub setup{
45                               my ($self) = @_;
46                               my $delegate = 'MyAppRunmodes';
47                                       # $delegate can be a class name or an object
48                               $self->param('::Plugin::AutoRunmode::delegate' => $delegate);
49                       }
50
51                # you now have two run modes
52                # "my_run_mode" and "another_run_mode"
53

DESCRIPTION

55       This plugin for CGI::Application provides easy ways to setup run modes.
56       You can just write the method that implement a run mode, you do not
57       have to explicitly register it with CGI::App anymore.
58
59       There are two approaches:
60
61       Declare run modes with subroutine attributes.
62           You can flag methods in your CGI::App subclass with the attribute
63           "Runmode" or "StartRunmode" (these attributes are case-insensitive)
64
65       Declare that every method in a class is a run mode.
66           You can assign a delegate object, all whose methods will become
67           runmodes
68
69           You can also mix both approaches.
70
71           Delegate runmodes receive two parameters: The first one is the
72           CGI::App instance, followed by the delegate instance or class name.
73           This can be useful if you have delegate objects that contain state.
74
75           It is possible to chain multiple delegates by specifying an array
76           reference containing the delegate instances or class names. This
77           chain is checked from left to right and the runmode will be
78           delegated to the first match.
79
80       It both cases, the resulting runmodes will have the same name as the
81       subroutine that implements them. They are activated by a cgiapp_prerun
82       hook provided by this plugin (if you are using CGI::Application older
83       than version 4, hooks are not available, and you can import a
84       cgiapp_prerun method instead).
85
86   EXPORT
87       This module needs to export some symbols to do its job.
88
89       First of all, there are the handlers for the Runmode attribute.
90
91       In addition to that, the cgiapp_prerun hook is installed in your
92       application class.  This is not done as an export per se, but the hook
93       installation is still done in the import subroutine. Sound confusing,
94       is confusing, but you do not really need to know what is going on
95       exactly, just keep in mind that in order to let things go on, you have
96       to "use" the module with the default exports:
97
98               use CGI::Application::Plugin::AutoRunmode;
99
100       and not
101
102               use CGI::Application::Plugin::AutoRunmode ();
103                       # this will disable the Runmode attributes
104                       # DO NOT DO THIS
105
106       You can also explicitly import the cgiapp_prerun method.  This will
107       disable the installation of the hook.  Basically, you only want to do
108       this if you are using CGI::Application prior to version 4, where hooks
109       are not supported.
110
111               use CGI::Application::Plugin::AutoRunmode
112                       qw [ cgiapp_prerun];
113                       # do this if you use CGI::Application version 3.x
114
115   How does it work?
116       After CGI::App has determined the name of the run mode to be executed
117       in the normal way, cgiapp_prerun checks if such a run mode exists in
118       the map configured by $self->run_modes().
119
120       If the run mode already exists, it gets executed normally (this module
121       does nothing). This means that you can mix the ways to declare run
122       modes offered by this plugin with the style provided by core CGI::App.
123
124       If that is not the case, it tries to find a method of the same name in
125       the application class (or its superclasses) that has been flagged as a
126       Runmode.  If it finds one, it augments the mapping with a subroutine
127       reference to that method.
128
129       If that step fails, it looks if a delegate has been defined and
130       searches the methods of that delegate object for one that matches the
131       name of the runmode.
132
133       The runmode can then be executed by CGI::App as if it had been set up
134       by $self->run_modes() in the first place.
135
136       The run mode called "start"
137
138       Note that because the plugin only gets activated when you call a run
139       mode that is not registered in the usual run mode map, you cannot use
140       it to create a run mode called "start". The CGI:App base class always
141       registers a run mode of that name.
142
143   Does it still work if I change the run mode in cgiapp_prerun ?
144       If you have a cgiapp_prerun method and change the run mode there, the
145       installed hook will not be able to catch it (because of the ordering of
146       hooks).
147
148       So, if you do that, you have to explicitly make this call before
149       returning from cgiapp_prerun:
150
151          CGI::Application::Plugin::AutoRunmode::cgiapp_prerun($self);
152
153       Again, this is only necessary if you change the run mode (to one that
154       needs the auto-detection feature).
155
156       Also, this kind of code can be used with CGI::App 3.x if you have a
157       cgiapp_prerun.
158
159   StartRunmode
160       The attribute StartRunmode designates that subroutine to be the start
161       (default) run mode. If you use this feature, the "traditional" way of
162       setting the start run mode (calling "$self->start_mode('name')") is
163       disabled and can no longer be used in this application (including
164       subclasses and instance scripts).
165
166   ErrorRunmode
167       The attribute ErrorRunmode designates that subroutine to be the error
168       run mode. If you use this feature, the "traditional" way of setting the
169       error run mode (calling "$self->error_mode('name')") is disabled and
170       can no longer be used in this application (including subclasses and
171       instance scripts). This feature requires CGI::App of at least version
172       3.30.
173
174       Note that this "error run mode" is not a run mode that is directly
175       accessible using its name as a query parameter.  It will only be
176       dispatched to internally if the original run mode produced an error.
177       This is exactly how plain CGI:App "error_mode" behaves as well (you
178       could still declare the method to also be a ":Runmode" ).
179
180   A word on security
181       The whole idea of this module (to reduce code complexity by
182       automatically mapping a URL to a subroutine that gets executed) is a
183       potential security hazard and great care has to be taken so that a
184       remote user cannot run code that you did not intend them to.
185
186       In order to prevent a carefully crafted URL to access code in other
187       packages, this module disallows non-word characters (such as : )  in
188       run mode names.
189
190       Also, you have to make sure that when using a delegate object, that it
191       (and its superclasses) only contain run modes (and no other
192       subroutines).
193
194       The following run mode names are disallowed by this module:
195
196               can isa VERSION AUTOLOAD new DESTROY
197
198   Effect on the run_modes map
199       This module only inserts the current run mode into the run_mode map
200       (unless it is already in there). It does not place any other :Runmodes
201       there. As a result of this behaviour, users of AutoRunmode will most
202       likely find the run mode map almost completely empty. This can lead to
203       strange results if you expect a more complete list of possible run
204       modes there. At this time, there is no workaround for this.  Feel free
205       to complain to the author if you have a requirement here.
206
207       It is possible, however, to query the AutoRunmode plugin if an
208       AutoRunmode exists for a given name.
209
210         my $check = CGI::Application::Plugin::AutoRunmode::is_auto_runmode($self, $name)
211
212       This function returns a code ref if such an AutoRunmode exists.
213

SEE ALSO

215       •   CGI::Application::Plugin::AutoRunmode::FileDelegate
216
217       •   CGI::Application
218
219       •   The CGI::App wiki at <http://www.cgi-app.org/>.
220
221       •   CGI::Application::Plugin::ActionDispatch provides an alternative
222           set of attributes that dispatch according to PATH_INFO. It is very
223           similar to the mechanism used in the Catalyst framework.
224

AUTHOR

226       Thilo Planz, <thilo@cpan.org>
227

SUPPORT

229       Please use the request tracker at CPAN to report bugs or feature
230       requests:
231       <https://rt.cpan.org/Public/Dist/Display.html?Name=CGI-Application-Plugin-AutoRunmode>
232
233       If you want to support the development of this module with money, you
234       can donate using Flattr: <https://flattr.com/thing/132835>
235
237       Copyright 2004-2011 by Thilo Planz
238
239       This library is free software; you can redistribute it and/or modify it
240       under the same terms as Perl itself.
241
242
243
244perl v5.34.0                      2021-07-22                    AutoRunmode(3)
Impressum