1CGI::Prototype::Hidden(U3s)er Contributed Perl DocumentatCiGoIn::Prototype::Hidden(3)
2
6 CGI::Prototype::Hidden - Create a CGI application by subclassing - hid‐
7 den field
8
10 # in My/App.pm ---
11 package My::App;
12 use base qw(CGI::Prototype::Hidden);
13 # in /some/cgi-bin/program
15 use lib qw(/location);
17 use My::App;
18 My::App->activate;
19
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 1 Dispatching to a particular paged based on the "state" of the
26 application is performed according to param field.
27 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 3 The package for the class is autoloaded if needed.
32 4 The template for the class replaces ".pm" with ".tt" (config‐
34 urable), found in the same @INC path, and is therefore likely to be
35 in the same directory.
36 5 A "wrapper" template is automatically provided.
38 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 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 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 artifi‐
52 cial application, so check that out for at least an example of the
53 interfaces.
54 CONFIGURATION SLOTS
56 These methods or values are the ones you'll most likely change in your
58 application, although you can leave them all alone and it'll still be a
59 valid framework to create your entire application.
60 config_state_param
62 The name of the hidden field which will contain the state, default‐
63 ing to "_state".
64 In any form you create, or any constructed URL, you must be sure to
66 include this param as part of the form so that the right response
67 can be matched up for the submitted data. For example:
68 <form> [% self.CGI.hidden(self.config_state_param) %] First name:[%
70 self.CGI.textfield("first_name") %]<br> Last name: [%
71 self.CGI.textfield("last_name") %] <input type=submit> </form>
72 config_class_prefix
74 The class prefix placed ahead of the state name, default "My::App".
75 For example, the controller class for the "welcome" state will be
76 <My::App::welcome>.
77 You should change this if you are using mod_perl to something that
79 won't conflict with other usages of the same server space. For CGI
80 scripts, the default is an easy classname to remember.
81 Note that the template also use this name as their prefix, so that
83 your controller and template files end up in the same directory.
84 config_default_page
86 The initial page if the state is missing, default "welcome".
87 config_wrapper
89 The name of the WRAPPER template, default "My/App/WRAPPER.tt".
90 If you change "config_class_prefix", you'll want to change this as
92 well so that "WRAPPER.tt" ends up in the right directory. (I
93 debated doing that for you so you could just say "WRAPPER.TT", but
94 that'd make more complicated versions of this callback be even more
95 and more complicated.)
96 The wrapper template is called with "template" set to the wrapped
98 template, which should be processed in the wrapper. The smallest
99 wrapper is therefore:
100 [% PROCESS $template %]
102 However, typically, you'll want to define app-wide blocks and vari‐
104 ables, and maybe wrap the statement above in an exception catcher.
105 For example:
106 [%-
108 TRY;
109 content = PROCESS $template;
110 self.CGI.header;
111 self.CGI.start_html;
112 content;
113 self.CGI.end_html;
114 ### exceptions
115 ## for errors:
116 CATCH;
117 CLEAR;
118 self.CGI.header('text/plain');
119 -%]
120 An error has occurred. Remain calm.
121 Authorities have been notified. Do not leave the general area.
122 [%-
123 FILTER stderr -%]
124 ** [% template.filename %] error: [% error.info %] **
125 [%
126 END; # FILTER
127 END; # TRY
128 -%]
129 This sends back a plain message to the browser, as well as logging
131 the precise error text to "STDERR", and hopefully the web error
132 log.
133 config_compile_dir
135 The location of the compiled Perl templates, default "/tmp/com‐
136 pile-dir.$<" (where $< is the current user's numeric user ID).
137 You'll want this to be some place that the process can write, but
138 nobody else can. The default is functional, but not immune to
139 other hostile users on the same box, so you'll want to override
140 that for those cases.
141 config_tt_extension
143 The suffix replacing ".pm" when the module name is mapped to the
144 template name. By default, it's ".tt".
145 MANAGEMENT SLOTS
147 You will most likely not need to change these, but you'll want to stay
149 away from their names.
150 name_to_page
152 Called with a page name, returns a page object. Will also autoload
153 the package.
154 plugin
156 This is still an experimental feature that will be reworked in
157 future releases.
158 Called with a page name, returns a new page object that can be used
160 as "self" in a template, mixing in the code from the page's class
161 for additional heavy lifting.
162 For example, to have a "subpage" plugin, create a "subpage.tt" and
164 "subpage.pm" file, then include the tt with:
165 [% INCLUDE My/App/subpage.tt
167 self = self.plugin("subpage")
168 other = parms
169 go = here
170 %]
171 Now, within "subpage.tt", calls to "self.SomeMethod" will first
173 search the original page's lineage, and then the plugin class lin‐
174 eage for a definition for "SomeMethod".
175 dispatch
177 Overridden from CGI::Prototype. Selects either the hidden field
178 state, or the default state, and returns the page object.
179 shortname
181 Returns the simple name for the current page object by stripping
182 off the "config_class_prefix". Note that this will fail in the
183 event of prototype page constructed on the fly, rather than a named
184 class. Hmm, I'll have to think about what that implies.
185 render_enter
187 Overridden from CGI::Prototype. Forces the hidden state param to
188 the shortname of the current object, then calls "ren‐
189 der_enter_per_page".
190 render_enter_per_page
192 If you need page-specific render_enter items, put them here. The
193 default definition does nothing. This is to keep from having to
194 call superclass methods for "render_enter".
195 respond
197 Overridden from CGI::Prototype. Calls "respond_per_app" and then
198 "respond_per_page", looking for a true value, which is then
199 returned.
200 If you have site-wide buttons (like a button-bar on the side or top
202 of your form), look for them in "respond_per_app", and return the
203 new page from there. Otherwise, return "undef", and it'll fall
204 through to the per-page response.
205 respond_per_app
207 A hook for application-wide responses, defaulting to "undef".
208 Should return either a page object (to be rendered) or a false
209 value (selecting the per-page respond).
210 respond_per_page
212 If "respond_per_app" returns false, this hook is then evaluated.
213 It should return a page object to be rendered. The default returns
214 the current page object, so you "stay here" for rendering.
215 template
217 Overridden from CGI::Prototype. Returns the name of a template,
218 defined by replacing the double-colons in the classname of the cur‐
219 rent page with forward slashes, and then appending ".tt" (by
220 default, see "config_tt_extension"). Because @INC is added to the
221 "INCLUDE_PATH" for the engine, this should find the ".tt" file in
222 the same directory as the ".pm" file.
223 engine_config
225 Overridden from CGI::Prototype, so that the cached Template object
226 that is essentially:
227 Template->new
229 (
230 POST_CHOMP => 1,
231 INCLUDE_PATH => [@INC],
232 COMPILE_DIR => $self->config_compile_dir,
233 PROCESS => [$self->config_wrapper],
234 )
235
237 CGI::Prototype, Template::Manual
238
240 Please report any bugs or feature requests to bug-cgi-proto‐
241 type@rt.cpan.org, or through the web interface at http://rt.cpan.org. I
242 will be notified, and then you'll automatically be notified of progress
243 on your bug as I make changes.
244
246 Randal L. Schwartz, <merlyn@stonehenge.com>
247 Special thanks to Geekcruises.com and an unnamed large university for
249 providing funding for the development of this module.
250
252 Copyright (C) 2003, 2004, 2005 by Randal L. Schwartz
253 This library is free software; you can redistribute it and/or modify it
255 under the same terms as Perl itself, either Perl version 5.8.5 or, at
256 your option, any later version of Perl 5 you may have available.
257perl v5.8.8 2005-03-23 CGI::Prototype::Hidden(3)