Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AutoRunmode(3)	      User Contributed Perl Documentation	AutoRunmode(3)

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;

	       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
       o   CGI::Application::Plugin::AutoRunmode::FileDelegate

       o   CGI::Application

       o   The CGI::App	wiki at	<http://www.cgi-app.org/>.

       o   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>

       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.24.1			  2011-02-18			AutoRunmode(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHOR | SUPPORT | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Application::Plugin::AutoRunmode&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help