CGI::Prototype::HiddenUser Contributed Perl DocumentaCGI::Prototype::Hidden(3)NAMECGI::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;
DESCRIPTIONCGI::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.14.1 2011-07-30 CGI::Prototype::Hidden(3)