AutoRunmode(3) User Contributed Perl Documentation AutoRunmode(3)NAMECGI::Application::Plugin::AutoRunmode - CGI::App plugin to
automatically register runmodes
SYNOPSIS
Using subroutine attributes:
package MyApp;
use base 'CGI::Application';
use CGI::Application::Plugin::AutoRunmode;
sub my_run_mode : StartRunmode {
# do something here
}
sub another_run_mode : Runmode {
# do something else
}
# you now have two run modes
# "my_run_mode" and "another_run_mode"
# "my_run_mode" is the start (default) run mode
Declare that every method in a (delegate) class is a run mode.
package MyAppRunmodes;
# the delegate class
sub my_run_mode {
my ($app, $delegate) = @_;
# do something here
}
sub another_run_mode {
# do something else
}
package MyApp;
use base 'CGI::Application';
sub setup{
my ($self) = @_;
my $delegate = 'MyAppRunmodes';
# $delegate can be a class name or an object
$self->param('::Plugin::AutoRunmode::delegate' => $delegate);
}
# you now have two run modes
# "my_run_mode" and "another_run_mode"
DESCRIPTION
This plugin for CGI::Application provides easy ways to setup run modes.
You can just write the method that implement a run mode, you do not
have to explicitly register it with CGI::App anymore.
There are two approaches:
Declare run modes with subroutine attributes.
You can flag methods in your CGI::App subclass with the attribute
"Runmode" or "StartRunmode" (these attributes are case-insensitive)
Declare that every method in a class is a run mode.
You can assign a delegate object, all whose methods will become
runmodes
You can also mix both approaches.
Delegate runmodes receive two parameters: The first one is the
CGI::App instance, followed by the delegate instance or class name.
This can be useful if you have delegate objects that contain state.
It is possible to chain multiple delegates by specifying an array
reference containing the delegate instances or class names. This
chain is checked from left to right and the runmode will be
delegated to the first match.
It both cases, the resulting runmodes will have the same name as the
subroutine that implements them. They are activated by a cgiapp_prerun
hook provided by this plugin (if you are using CGI::Application older
than version 4, hooks are not available, and you can import a
cgiapp_prerun method instead).
EXPORT
This module needs to export some symbols to do its job.
First of all, there are the handlers for the Runmode attribute.
In addition to that, the cgiapp_prerun hook is installed in your
application class. This is not done as an export per se, but the hook
installation is still done in the import subroutine. Sound confusing,
is confusing, but you do not really need to know what is going on
exactly, just keep in mind that in order to let things go on, you have
to "use" the module with the default exports:
use CGI::Application::Plugin::AutoRunmode;
and not
use CGI::Application::Plugin::AutoRunmode ();
# this will disable the Runmode attributes
# DO NOT DO THIS
You can also explicitly import the cgiapp_prerun method. This will
disable the installation of the hook. Basically, you only want to do
this if you are using CGI::Application prior to version 4, where hooks
are not supported.
use CGI::Application::Plugin::AutoRunmode
qw [ cgiapp_prerun];
# do this if you use CGI::Application version 3.x
How does it work?
After CGI::App has determined the name of the run mode to be executed
in the normal way, cgiapp_prerun checks if such a run mode exists in
the map configured by $self->run_modes().
If the run mode already exists, it gets executed normally (this module
does nothing). This means that you can mix the ways to declare run
modes offered by this plugin with the style provided by core CGI::App.
If that is not the case, it tries to find a method of the same name in
the application class (or its superclasses) that has been flagged as a
Runmode. If it finds one, it augments the mapping with a subroutine
reference to that method.
If that step fails, it looks if a delegate has been defined and
searches the methods of that delegate object for one that matches the
name of the runmode.
The runmode can then be executed by CGI::App as if it had been set up
by $self->run_modes() in the first place.
The run mode called "start"
Note that because the plugin only gets activated when you call a run
mode that is not registered in the usual run mode map, you cannot use
it to create a run mode called "start". The CGI:App base class always
registers a run mode of that name.
Does it still work if I change the run mode in cgiapp_prerun ?
If you have a cgiapp_prerun method and change the run mode there, the
installed hook will not be able to catch it (because of the ordering of
hooks).
So, if you do that, you have to explicitly make this call before
returning from cgiapp_prerun:
CGI::Application::Plugin::AutoRunmode::cgiapp_prerun($self);
Again, this is only necessary if you change the run mode (to one that
needs the auto-detection feature).
Also, this kind of code can be used with CGI::App 3.x if you have a
cgiapp_prerun.
StartRunmode
The attribute StartRunmode designates that subroutine to be the start
(default) run mode. If you use this feature, the "traditional" way of
setting the start run mode (calling "$self->start_mode('name')") is
disabled and can no longer be used in this application (including
subclasses and instance scripts).
ErrorRunmode
The attribute ErrorRunmode designates that subroutine to be the error
run mode. If you use this feature, the "traditional" way of setting the
error run mode (calling "$self->error_mode('name')") is disabled and
can no longer be used in this application (including subclasses and
instance scripts). This feature requires CGI::App of at least version
3.30.
Note that this "error run mode" is not a run mode that is directly
accessible using its name as a query parameter. It will only be
dispatched to internally if the original run mode produced an error.
This is exactly how plain CGI:App "error_mode" behaves as well (you
could still declare the method to also be a ":Runmode" ).
A word on security
The whole idea of this module (to reduce code complexity by
automatically mapping a URL to a subroutine that gets executed) is a
potential security hazard and great care has to be taken so that a
remote user cannot run code that you did not intend them to.
In order to prevent a carefully crafted URL to access code in other
packages, this module disallows non-word characters (such as : ) in
run mode names.
Also, you have to make sure that when using a delegate object, that it
(and its superclasses) only contain run modes (and no other
subroutines).
The following run mode names are disallowed by this module:
can isa VERSION AUTOLOAD new DESTROY
Effect on the run_modes map
This module only inserts the current run mode into the run_mode map
(unless it is already in there). It does not place any other :Runmodes
there. As a result of this behaviour, users of AutoRunmode will most
likely find the run mode map almost completely empty. This can lead to
strange results if you expect a more complete list of possible run
modes there. At this time, there is no workaround for this. Feel free
to complain to the author if you have a requirement here.
It is possible, however, to query the AutoRunmode plugin if an
AutoRunmode exists for a given name.
my $check = CGI::Application::Plugin::AutoRunmode::is_auto_runmode($self, $name)
This function returns a code ref if such an AutoRunmode exists.
SEE ALSO
· CGI::Application::Plugin::AutoRunmode::FileDelegate
· CGI::Application
· The CGI::App wiki at http://www.cgi-app.org/ <http://www.cgi-
app.org/>.
· CGI::Application::Plugin::ActionDispatch provides an alternative
set of attributes that dispatch according to PATH_INFO. It is very
similar to the mechanism used in the Catalyst framework.
AUTHOR
Thilo Planz, <thilo@cpan.org>
SUPPORT
Please use the request tracker at CPAN to report bugs or feature
requests:
https://rt.cpan.org/Public/Dist/Display.html?Name=CGI-Application-Plugin-AutoRunmode
<https://rt.cpan.org/Public/Dist/Display.html?Name=CGI-Application-
Plugin-AutoRunmode>
If you want to support the development of this module with money, you
can donate using Flattr: <https://flattr.com/thing/132835>
COPYRIGHT AND LICENSE
Copyright 2004-2011 by Thilo Planz
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2011-02-18 AutoRunmode(3)