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

FreeBSD Manual Pages

  
 
  

home | help
CGI::Prototype::HiddenUser Contributed Perl DocumentaCGI::Prototype::Hidden(3)

NAME
       CGI::Prototype::Hidden -	Create a CGI application by subclassing	-
       hidden field

SYNOPSIS
	 # in My/App.pm	---
	 package My::App;
	 use base qw(CGI::Prototype::Hidden);

	 # in /some/cgi-bin/program

	 use lib qw(/location);
	 use My::App;
	 My::App->activate;

DESCRIPTION
       CGI::Prototype::Hidden extends CGI::Prototype by	providing a hidden
       field mechanism for state, and a	dispatching algorithm based on that
       hidden field.  In particular,

       1.  Dispatching to a particular paged based on the "state" of the
	   application is performed according to param field.

       2.  The name of the state is appended to	an application-wide package
	   prefix to determine an appropriate class to handle the request.

       3.  The package for the class is	autoloaded if needed.

       4.  The template	for the	class replaces ".pm" with ".tt"
	   (configurable), found in the	same @INC path,	and is therefore
	   likely to be	in the same directory.

       5.  A "wrapper" template	is automatically provided.

       Thus, a simple 10-page CGI application will require 23 files: 10
       classes,	10 corresponding templates, a wrapper template,	a master
       application class, and a	CGI script that	loads the master application
       class and activates it.

       The default class is "My::App", but this	can be overridden.  The
       default state is	"welcome", but this too	can be overridden.  The
       default hidden param name for the state is "_state", and	if you think
       this can	be overridden, you are correct.	 See the trend here?

       A sample	app is the best	way to show all	of this, of course.  We	don't
       have one	yet... that's on the TODO list.	 However, the functions	have
       all been	exercised in the tests for this	module,	including an
       artificial application, so check	that out for at	least an example of
       the interfaces.

   CONFIGURATION SLOTS
       These methods or	values are the ones you'll most	likely change in your
       application, although you can leave them	all alone and it'll still be a
       valid framework to create your entire application.

       config_state_param
	   The name of the hidden field	which will contain the state,
	   defaulting to "_state".

	   In any form you create, or any constructed URL, you must be sure to
	   include this	param as part of the form so that the right response
	   can be matched up for the submitted data.  For example:

	   <form> [% self.CGI.hidden(self.config_state_param) %] First name:[%
	   self.CGI.textfield("first_name") %]<br> Last	name: [%
	   self.CGI.textfield("last_name") %] <input type=submit> </form>

       config_class_prefix
	   The class prefix placed ahead of the	state name, default "My::App".
	   For example,	the controller class for the "welcome" state will be
	   <My::App::welcome>.

	   You should change this if you are using mod_perl to something that
	   won't conflict with other usages of the same	server space.  For CGI
	   scripts, the	default	is an easy classname to	remember.

	   Note	that the template also use this	name as	their prefix, so that
	   your	controller and template	files end up in	the same directory.

       config_default_page
	   The initial page if the state is missing, default "welcome".

       config_wrapper
	   The name of the WRAPPER template, default "My/App/WRAPPER.tt".

	   If you change "config_class_prefix",	you'll want to change this as
	   well	so that	"WRAPPER.tt" ends up in	the right directory.  (I
	   debated doing that for you so you could just	say "WRAPPER.TT", but
	   that'd make more complicated	versions of this callback be even more
	   and more complicated.)

	   The wrapper template	is called with "template" set to the wrapped
	   template, which should be processed in the wrapper.	The smallest
	   wrapper is therefore:

	     [%	PROCESS	$template %]

	   However, typically, you'll want to define app-wide blocks and
	   variables, and maybe	wrap the statement above in an exception
	   catcher.  For example:

	     [%-
	     TRY;
	       content = PROCESS $template;
	       self.CGI.header;
	       self.CGI.start_html;
	       content;
	       self.CGI.end_html;
	     ### exceptions
	     ##	for errors:
	     CATCH;
	       CLEAR;
	       self.CGI.header('text/plain');
	     -%]
	     An	error has occurred.  Remain calm.
	     Authorities have been notified.  Do not leave the general area.
	     [%-
	       FILTER stderr -%]
	     **	[% template.filename %]	error: [% error.info %]	**
	     [%
	       END; # FILTER
	     END; # TRY
	     -%]

	   This	sends back a plain message to the browser, as well as logging
	   the precise error text to "STDERR", and hopefully the web error
	   log.

       config_compile_dir
	   The location	of the compiled	Perl templates,	default
	   "/tmp/compile-dir.$<" (where	$< is the current user's numeric user
	   ID).	 You'll	want this to be	some place that	the process can	write,
	   but nobody else can.	 The default is	functional, but	not immune to
	   other hostile users on the same box,	so you'll want to override
	   that	for those cases.

       config_tt_extension
	   The suffix replacing	".pm" when the module name is mapped to	the
	   template name.  By default, it's ".tt".

   MANAGEMENT SLOTS
       You will	most likely not	need to	change these, but you'll want to stay
       away from their names.

       name_to_page
	   Called with a page name, returns a page object.  Will also autoload
	   the package.

       plugin
	   This	is still an experimental feature that will be reworked in
	   future releases.

	   Called with a page name, returns a new page object that can be used
	   as "self" in	a template, mixing in the code from the	page's class
	   for additional heavy	lifting.

	   For example,	to have	a "subpage" plugin, create a "subpage.tt" and
	   "subpage.pm"	file, then include the tt with:

	     [%	INCLUDE	My/App/subpage.tt
		  self = self.plugin("subpage")
		  other	= parms
		  go = here
	     %]

	   Now,	within "subpage.tt", calls to "self.SomeMethod"	will first
	   search the original page's lineage, and then	the plugin class
	   lineage for a definition for	"SomeMethod".

       dispatch
	   Overridden from CGI::Prototype.  Selects either the hidden field
	   state, or the default state,	and returns the	page object.

       shortname
	   Returns the simple name for the current page	object by stripping
	   off the "config_class_prefix".  Note	that this will fail in the
	   event of prototype page constructed on the fly, rather than a named
	   class.  Hmm,	I'll have to think about what that implies.

       render_enter
	   Overridden from CGI::Prototype.  Forces the hidden state param to
	   the shortname of the	current	object,	then calls
	   "render_enter_per_page".

       render_enter_per_page
	   If you need page-specific render_enter items, put them here.	 The
	   default definition does nothing.  This is to	keep from having to
	   call	superclass methods for "render_enter".

       respond
	   Overridden from CGI::Prototype.  Calls "respond_per_app" and	then
	   "respond_per_page", looking for a true value, which is then
	   returned.

	   If you have site-wide buttons (like a button-bar on the side	or top
	   of your form), look for them	in "respond_per_app", and return the
	   new page from there.	 Otherwise, return "undef", and	it'll fall
	   through to the per-page response.

       respond_per_app
	   A hook for application-wide responses, defaulting to	"undef".
	   Should return either	a page object (to be rendered) or a false
	   value (selecting the	per-page respond).

       respond_per_page
	   If "respond_per_app"	returns	false, this hook is then evaluated.
	   It should return a page object to be	rendered.  The default returns
	   the current page object, so you "stay here" for rendering.

       template
	   Overridden from CGI::Prototype.  Returns the	name of	a template,
	   defined by replacing	the double-colons in the classname of the
	   current page	with forward slashes, and then appending ".tt" (by
	   default, see	"config_tt_extension").	 Because @INC is added to the
	   "INCLUDE_PATH" for the engine, this should find the ".tt" file in
	   the same directory as the ".pm" file.

       engine_config
	   Overridden from CGI::Prototype, so that the cached Template object
	   that	is essentially:

	     Template->new
	       (
		POST_CHOMP => 1,
		INCLUDE_PATH =>	[@INC],
		COMPILE_DIR => $self->config_compile_dir,
		PROCESS	=> [$self->config_wrapper],
	       )

SEE ALSO
       CGI::Prototype, Template::Manual

BUG REPORTS
       Please report any bugs or feature requests to
       bug-cgi-prototype@rt.cpan.org, or through the web interface at
       http://rt.cpan.org. I will be notified, and then	you'll automatically
       be notified of progress on your bug as I	make changes.

AUTHOR
       Randal L. Schwartz, <merlyn@stonehenge.com>

       Special thanks to Geekcruises.com and an	unnamed	large university for
       providing funding for the development of	this module.

COPYRIGHT AND LICENSE
       Copyright (C) 2003, 2004, 2005 by Randal	L. Schwartz

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.5 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.24.1			  2011-07-30	     CGI::Prototype::Hidden(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | BUG REPORTS | AUTHOR | COPYRIGHT AND LICENSE

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

home | help