/ 
CGI-Application-Plugin-AutoRunmode-0.05
River stage one • 6 direct dependents • 6 total dependents
/ CGI::Application::Plugin::AutoRunmode

NAME

CGI::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 
	qw [ cgiapp_prerun];

sub my_run_mode : Runmode {
	# do something here
}

sub another_run_mode : Runmode {
	# do something else
}

# you now have two run modes
# "my_run_mode" and "another_run_mode"

Using a delegate object

  	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';
	use CGI::Application::Plugin::AutoRunmode 
		qw [ cgiapp_prerun];
	   
		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 methods that implement a run mode, you do not have to explicitly register it with CGI::App anymore.

There are two approaches: You can flag methods in your CGI::App subclass with the attribute "Runmode", or 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 both cases, the resulting runmodes will have the same name as the subroutine that implements them, and you can use the cgiapp_prerun method provided by this plugin to activate them.

EXPORT

The module can export a cgiapp_prerun, which you should import unless you already have such a method.

use CGI::Application::Plugin::AutoRunmode 
	qw [ cgiapp_prerun];

If you already have a cgiapp_prerun, you have to invoke the plugin's code from within your method:

# if you already have your own cgiapp_prerun
# do this:
use CGI::Application::Plugin::AutoRunmode;

sub cgiapp_prerun{
	CGI::Application::Plugin::AutoRunmode::cgiapp_prerun(@_);
	# your code goes here
}

Even if you do not import cgiapp_prerun from the plugin, make sure you still have the default imports, which are necessary to enable the Runmode attribute. Unless you are not using these attributes (because you like the delegate object approach more), you must do

use CGI::Application::Plugin::AutoRunmode;

and not

use CGI::Application::Plugin::AutoRunmode ();
	# this will disable the Runmode attributes

using the callback interface

You can also use the new callback interface of CGI::Application::Callbacks. By calling the install method, this plugin will install itself as a callback in the LAST position of the PRERUN phase. This setup enables you to provide additional prerun modes, and you can also change the runmode from within these prerun modes.

package MyApp;
use base 'CGI::Application::Callbacks';
use CGI::Application::Plugin::AutoRunmode;

sub setup{
	my $self = shift;
	install CGI::Application::Plugin::AutoRunmode($self);
}

sub do_something : Runmode{
	# ....
}

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.

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

SEE ALSO

AUTHOR

Thilo Planz, <thilo@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2004/05 by Thilo Planz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.