1CGI::Prototype::Hidden(U3s)er Contributed Perl DocumentatCiGoIn::Prototype::Hidden(3)
2
6 CGI::Prototype::Hidden - Create a CGI application by subclassing -
7 hidden 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"
34 (configurable), found in the same @INC path, and is therefore
35 likely to be 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
52 artificial application, so check that out for at least an example of
53 the interfaces.
54 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 config_state_param
61 The name of the hidden field which will contain the state,
62 defaulting to "_state".
63 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 <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 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 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 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 config_default_page
85 The initial page if the state is missing, default "welcome".
86 config_wrapper
88 The name of the WRAPPER template, default "My/App/WRAPPER.tt".
89 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 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 [% PROCESS $template %]
101 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 [%-
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 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 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 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 MANAGEMENT SLOTS
146 You will most likely not need to change these, but you'll want to stay
147 away from their names.
148 name_to_page
150 Called with a page name, returns a page object. Will also autoload
151 the package.
152 plugin
154 This is still an experimental feature that will be reworked in
155 future releases.
156 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 For example, to have a "subpage" plugin, create a "subpage.tt" and
162 "subpage.pm" file, then include the tt with:
163 [% INCLUDE My/App/subpage.tt
165 self = self.plugin("subpage")
166 other = parms
167 go = here
168 %]
169 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 dispatch
175 Overridden from CGI::Prototype. Selects either the hidden field
176 state, or the default state, and returns the page object.
177 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 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 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 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 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 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 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 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 engine_config
223 Overridden from CGI::Prototype, so that the cached Template object
224 that is essentially:
225 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
235 CGI::Prototype, Template::Manual
236
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
244 Randal L. Schwartz, <merlyn@stonehenge.com>
245 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 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.
255perl v5.28.0 2011-07-30 CGI::Prototype::Hidden(3)