1CGI::Prototype::Hidden(U3s)er Contributed Perl DocumentatCiGoIn::Prototype::Hidden(3)
2
3
4

NAME

6       CGI::Prototype::Hidden - Create a CGI application by subclassing -
7       hidden field
8

SYNOPSIS

10         # in My/App.pm ---
11         package My::App;
12         use base qw(CGI::Prototype::Hidden);
13
14         # in /some/cgi-bin/program
15
16         use lib qw(/location);
17         use My::App;
18         My::App->activate;
19

DESCRIPTION

21       CGI::Prototype::Hidden extends CGI::Prototype by providing a hidden
22       field mechanism for state, and a dispatching algorithm based on that
23       hidden field.  In particular,
24
25       1.  Dispatching to a particular paged based on the "state" of the
26           application is performed according to param field.
27
28       2.  The name of the state is appended to an application-wide package
29           prefix to determine an appropriate class to handle the request.
30
31       3.  The package for the class is autoloaded if needed.
32
33       4.  The template for the class replaces ".pm" with ".tt"
34           (configurable), found in the same @INC path, and is therefore
35           likely to be in the same directory.
36
37       5.  A "wrapper" template is automatically provided.
38
39       Thus, a simple 10-page CGI application will require 23 files: 10
40       classes, 10 corresponding templates, a wrapper template, a master
41       application class, and a CGI script that loads the master application
42       class and activates it.
43
44       The default class is "My::App", but this can be overridden.  The
45       default state is "welcome", but this too can be overridden.  The
46       default hidden param name for the state is "_state", and if you think
47       this can be overridden, you are correct.  See the trend here?
48
49       A sample app is the best way to show all of this, of course.  We don't
50       have one yet... that's on the TODO list.  However, the functions have
51       all been exercised in the tests for this module, including an
52       artificial application, so check that out for at least an example of
53       the interfaces.
54
55   CONFIGURATION SLOTS
56       These methods or values are the ones you'll most likely change in your
57       application, although you can leave them all alone and it'll still be a
58       valid framework to create your entire application.
59
60       config_state_param
61           The name of the hidden field which will contain the state,
62           defaulting to "_state".
63
64           In any form you create, or any constructed URL, you must be sure to
65           include this param as part of the form so that the right response
66           can be matched up for the submitted data.  For example:
67
68           <form> [% self.CGI.hidden(self.config_state_param) %] First name:[%
69           self.CGI.textfield("first_name") %]<br> Last name: [%
70           self.CGI.textfield("last_name") %] <input type=submit> </form>
71
72       config_class_prefix
73           The class prefix placed ahead of the state name, default "My::App".
74           For example, the controller class for the "welcome" state will be
75           <My::App::welcome>.
76
77           You should change this if you are using mod_perl to something that
78           won't conflict with other usages of the same server space.  For CGI
79           scripts, the default is an easy classname to remember.
80
81           Note that the template also use this name as their prefix, so that
82           your controller and template files end up in the same directory.
83
84       config_default_page
85           The initial page if the state is missing, default "welcome".
86
87       config_wrapper
88           The name of the WRAPPER template, default "My/App/WRAPPER.tt".
89
90           If you change "config_class_prefix", you'll want to change this as
91           well so that "WRAPPER.tt" ends up in the right directory.  (I
92           debated doing that for you so you could just say "WRAPPER.TT", but
93           that'd make more complicated versions of this callback be even more
94           and more complicated.)
95
96           The wrapper template is called with "template" set to the wrapped
97           template, which should be processed in the wrapper.  The smallest
98           wrapper is therefore:
99
100             [% PROCESS $template %]
101
102           However, typically, you'll want to define app-wide blocks and
103           variables, and maybe wrap the statement above in an exception
104           catcher.  For example:
105
106             [%-
107             TRY;
108               content = PROCESS $template;
109               self.CGI.header;
110               self.CGI.start_html;
111               content;
112               self.CGI.end_html;
113             ### exceptions
114             ## for errors:
115             CATCH;
116               CLEAR;
117               self.CGI.header('text/plain');
118             -%]
119             An error has occurred.  Remain calm.
120             Authorities have been notified.  Do not leave the general area.
121             [%-
122               FILTER stderr -%]
123             ** [% template.filename %] error: [% error.info %] **
124             [%
125               END; # FILTER
126             END; # TRY
127             -%]
128
129           This sends back a plain message to the browser, as well as logging
130           the precise error text to "STDERR", and hopefully the web error
131           log.
132
133       config_compile_dir
134           The location of the compiled Perl templates, default
135           "/tmp/compile-dir.$<" (where $< is the current user's numeric user
136           ID).  You'll want this to be some place that the process can write,
137           but nobody else can.  The default is functional, but not immune to
138           other hostile users on the same box, so you'll want to override
139           that for those cases.
140
141       config_tt_extension
142           The suffix replacing ".pm" when the module name is mapped to the
143           template name.  By default, it's ".tt".
144
145   MANAGEMENT SLOTS
146       You will most likely not need to change these, but you'll want to stay
147       away from their names.
148
149       name_to_page
150           Called with a page name, returns a page object.  Will also autoload
151           the package.
152
153       plugin
154           This is still an experimental feature that will be reworked in
155           future releases.
156
157           Called with a page name, returns a new page object that can be used
158           as "self" in a template, mixing in the code from the page's class
159           for additional heavy lifting.
160
161           For example, to have a "subpage" plugin, create a "subpage.tt" and
162           "subpage.pm" file, then include the tt with:
163
164             [% INCLUDE My/App/subpage.tt
165                  self = self.plugin("subpage")
166                  other = parms
167                  go = here
168             %]
169
170           Now, within "subpage.tt", calls to "self.SomeMethod" will first
171           search the original page's lineage, and then the plugin class
172           lineage for a definition for "SomeMethod".
173
174       dispatch
175           Overridden from CGI::Prototype.  Selects either the hidden field
176           state, or the default state, and returns the page object.
177
178       shortname
179           Returns the simple name for the current page object by stripping
180           off the "config_class_prefix".  Note that this will fail in the
181           event of prototype page constructed on the fly, rather than a named
182           class.  Hmm, I'll have to think about what that implies.
183
184       render_enter
185           Overridden from CGI::Prototype.  Forces the hidden state param to
186           the shortname of the current object, then calls
187           "render_enter_per_page".
188
189       render_enter_per_page
190           If you need page-specific render_enter items, put them here.  The
191           default definition does nothing.  This is to keep from having to
192           call superclass methods for "render_enter".
193
194       respond
195           Overridden from CGI::Prototype.  Calls "respond_per_app" and then
196           "respond_per_page", looking for a true value, which is then
197           returned.
198
199           If you have site-wide buttons (like a button-bar on the side or top
200           of your form), look for them in "respond_per_app", and return the
201           new page from there.  Otherwise, return "undef", and it'll fall
202           through to the per-page response.
203
204       respond_per_app
205           A hook for application-wide responses, defaulting to "undef".
206           Should return either a page object (to be rendered) or a false
207           value (selecting the per-page respond).
208
209       respond_per_page
210           If "respond_per_app" returns false, this hook is then evaluated.
211           It should return a page object to be rendered.  The default returns
212           the current page object, so you "stay here" for rendering.
213
214       template
215           Overridden from CGI::Prototype.  Returns the name of a template,
216           defined by replacing the double-colons in the classname of the
217           current page with forward slashes, and then appending ".tt" (by
218           default, see "config_tt_extension").  Because @INC is added to the
219           "INCLUDE_PATH" for the engine, this should find the ".tt" file in
220           the same directory as the ".pm" file.
221
222       engine_config
223           Overridden from CGI::Prototype, so that the cached Template object
224           that is essentially:
225
226             Template->new
227               (
228                POST_CHOMP => 1,
229                INCLUDE_PATH => [@INC],
230                COMPILE_DIR => $self->config_compile_dir,
231                PROCESS => [$self->config_wrapper],
232               )
233

SEE ALSO

235       CGI::Prototype, Template::Manual
236

BUG REPORTS

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

AUTHOR

244       Randal L. Schwartz, <merlyn@stonehenge.com>
245
246       Special thanks to Geekcruises.com and an unnamed large university for
247       providing funding for the development of this module.
248
250       Copyright (C) 2003, 2004, 2005 by Randal L. Schwartz
251
252       This library is free software; you can redistribute it and/or modify it
253       under the same terms as Perl itself, either Perl version 5.8.5 or, at
254       your option, any later version of Perl 5 you may have available.
255
256
257
258perl v5.38.0                      2023-07-20         CGI::Prototype::Hidden(3)
Impressum