1CGI::Prototype(3) User Contributed Perl Documentation CGI::Prototype(3)
2
6 CGI::Prototype - Create a CGI application by subclassing
7
9 package My::HelloWorld;
10 use base CGI::Prototype;
11 sub template { \ <<'END_OF_TEMPLATE' }
13 [% self.CGI.header; %]
14 Hello world at [% USE Date; Date.format(date.now) | html %]!
15 END_OF_TEMPLATE
16 My::HelloWorld->activate;
18
20 The core of every CGI application seems to be roughly the same:
21 • Analyze the incoming parameters, cookies, and URLs to determine the
23 state of the application (let's call this "dispatch").
24 • Based on the current state, analyze the incoming parameters to
26 respond to any form submitted ("respond").
27 • From there, decide what response page should be generated, and
29 produce it ("render").
30 CGI::Prototype creates a "Class::Prototyped" engine for doing all this,
32 with the right amount of callback hooks to customize the process.
33 Because I'm biased toward Template Toolkit for rendering HTML, I've
34 also integrated that as my rendering engine of choice. And, being a
35 fan of clean MVC designs, the classes become the controllers, and the
36 templates become the views, with clean separation of responsibilities,
37 and "CGI::Prototype" a sort of "archetypal" controller.
38 You can create the null application by simply activating it:
40 use CGI::Prototype;
42 CGI::Prototype->activate;
43 But this won't be very interesting. You'll want to subclass this class
45 in a "Class::Prototyped"-style manner to override most of its behavior.
46 Slots can be added to add or alter behavior. You can subclass your
47 subclasses when groups of your CGI pages share similar behavior. The
48 possibilities are mind-boggling.
49 Within the templates, "self" refers to the current controller. Thus,
51 you can define callbacks trivially. In your template, if you need some
52 data, you can pull it as a request:
53 [% my_data = self.get_some_big_data %]
55 which is supplied by simply adding the same slot (method or data) in
57 the controlling class:
58 sub get_some_big_data {
60 my $self = shift;
61 return $self->some_other_method(size => 'big');
62 }
63 And since the classes are hierarchical, you can start out with an
65 implementation for one page, then move it to a region or globally
66 quickly.
67 Although the name "CGI::Prototype" implies a CGI protocol, I see no
69 reason that this would not work with "Apache::Registry" in a "mod_perl"
70 environment, or a direct content handler such as:
71 package My::App;
73 use base CGI::Prototype;
74 sub handler {
75 __PACKAGE__->activate;
76 }
77 Note that the $r request object will have to be created if needed if
79 you use this approach.
80 CORE SLOTS
82 These slots provide core functionality. You will probably not need to
83 override these.
84 activate
86 Invoke the "activate" slot to "activate" your application, causing
87 it to process the incoming CGI values, select a page to be respond
88 to the parameters, which in turn selects a page to render, and then
89 responds with that page. For example, your App might consist only
90 of:
91 package My::App;
93 use base qw(CGI::Prototype);
94 My::App->activate;
95 Again, this will not be interesting, but it shows that the null app
97 is easy to create. Almost always, you will want to override some
98 of the "callback" slots below.
99 CGI Invoking "$self->CGI" gives you access to the CGI.pm object
101 representing the incoming parameters and other CGI.pm-related
102 values. For example,
103 $self->CGI->self_url
105 generates a self-referencing URL. From a template, this is:
107 [% self.CGI.self_url %]
109 for the same thing.
111 See "initialize_CGI" for how this slot gets established.
113 render
115 The "render" method uses the results from "engine" and "template"
116 to process a selected template through Template Toolkit. If the
117 result does not throw an error, "$self->display" is called to show
118 the result.
119 display
121 The "display" method is called to render the output of the template
122 under normal circumstances, normally dumping the first parameter to
123 "STDOUT". Test harnesses may override this method to cause the
124 output to appear into a variable, but normally this method is left
125 alone.
126 param
128 The "param" method is a convenience method that maps to
129 "$self->CGI->param", because accessing params is a very common
130 thing.
131 interstitial
133 Please note that this feature is still experimental and subject to
134 change.
135 Use this in your per-page respond methods if you have a lot of
137 heavy processing to perform. For example, suppose you're deleting
138 something, and it takes 5 seconds to do the first step, and 3
139 seconds to do the second step, and then you want to go back to
140 normal web interaction. Simulating the heavy lifting with sleep,
141 we get:
142 my $p = $self->interstitial
144 ({ message => "Your delete is being processed...",
145 action => sub { sleep 5 },
146 },
147 { message => "Just a few seconds more....",
148 action => sub { sleep 3 },
149 },
150 );
151 return $p if $p;
152 "interstitial" returns either a page that should be returned so
154 that it can be rendered (inside a wrapper that provides the
155 standard top and bottom of your application page), or "undef".
156 The list passed to "interstitial" should be a series of hashrefs
158 with one or more parameters reflecting the steps:
159 message
161 What the user should see while the step is computing.
162 (Default: "Working...".)
163 action
165 A coderef with the action performed server-side during the
166 message. (Default: no action.)
167 delay
169 The number of seconds the browser should wait before initiating
170 the next connection, triggering the start of "action".
171 (Default: 0 seconds.)
172 The user sees the first message at the first call to "interstitial"
174 (via the first returned page), at which time a meta-refresh will
175 immediately repost the same parameters as on the call that got you
176 here. (Thus, it's important not to have changed the params yet, or
177 you might end up in a different part of your code.) When the call
178 to "interstitial" is re-executed, the first coderef is then
179 performed. At the end of that coderef, the second interstitial
180 page is returned, and the user sees the second message, which then
181 performs the next meta-refresh, which gets us back to this call to
182 "interstitial" again (whew). The second coderef is executed while
183 the user is seeing the second message, and then "interstitial"
184 returns "undef", letting us roll through to the final code. Slick.
185 config_interstitial_param
187 This parameter is used by "interstitial" to determine the
188 processing step. You should ensure that the name doesn't conflict
189 with any other param that you might need.
190 The default value is "_interstitial".
192 CALLBACK SLOTS
194 engine
195 The engine returns a Template object that will be generating any
196 response. The object is computed lazily (with autoloading) when
197 needed.
198 The Template object is passed the configuration returned from the
200 "engine_config" callback.
201 engine_config
203 Returns a hashref of desired parameters to pass to the "Template"
204 "new" method as a configuration. Defaults to an empty hash.
205 prototype_enter
207 Called when the prototype mechanism is entered, at the very
208 beginning of each hit. Defaults to calling "-"initialize_CGI>,
209 which see.
210 Generally, you should not override this method. If you do, be sure
212 to call the SUPER method, in case future versions of this module
213 need additional initialization.
214 prototype_leave
216 Called when the prototype mechanism is exited, at the very end of
217 each hit. Defaults to no action.
218 Generally, you should not override this method. If you do, be sure
220 to call the SUPER method, in case future versions of this module
221 need additional teardown.
222 initialize_CGI
224 Sets up the CGI slot as an autoload, defaulting to creating a new
225 CGI.pm object. Called from "prototype_enter".
226 app_enter
228 Called when the application is entered, at the very beginning of
229 each hit. Defaults to no action.
230 app_leave
232 Called when the application is left, at the very end of each hit.
233 Defaults to no action.
234 control_enter
236 Called when a page gains control, either at the beginning for a
237 response, or in the middle when switched for rendering. Defaults
238 to nothing.
239 This is a great place to hang per-page initialization, because
241 you'll get this callback at most once per hit.
242 control_leave
244 Called when a page loses control, either after a response phase
245 because we're switching to a new page, or render phase after we've
246 delivered the new text to the browser.
247 This is a great place to hang per-page teardown, because you'll get
249 this callback at most once per hit.
250 render_enter
252 Called when a page gains control specifically for rendering
253 (delivering text to the browser), just after "control_enter" if
254 needed.
255 render_leave
257 Called when a page loses control specifically for rendering
258 (delivering text to the browser), just before "control_leave".
259 respond_enter
261 Called when a page gains control specifically for responding
262 (understanding the incoming parameters, and deciding what page
263 should render the response), just after "control_enter".
264 respond_leave
266 Called when a page loses control specifically for rendering
267 (understanding the incoming parameters, and deciding what page
268 should render the response), just before "control_leave" (if
269 needed).
270 template
272 Delivers a template document object (something compatible to the
273 "Template" "process" method, such as a "Template::Document" or a
274 filehandle or a reference to a scalar). The default is a simple
275 "this page intentionally left blank" template.
276 When rendered, the only extra global variable passed into the
278 template is the "self" variable, representing the controller
279 object. However, as seen earlier, this is sufficient to allow
280 access to anything you need from the template, thanks to Template
281 Toolkit's ability to call methods on an object and understand the
282 results.
283 For example, to get at the "barney" parameter:
285 The barney field is [% self.param("barney") | html %].
287 error
289 Called if an uncaught error is triggered in any of the other steps,
290 passing the error text or object as the first method parameter.
291 The default callback simply displays the output to the browser,
292 which is highly insecure and should be overridden, perhaps with
293 something that logs the error and puts up a generic error message
294 with an incident code for tracking.
295 dispatch
297 Called to analyze the incoming parameters to define which page
298 object gets control based on the incoming CGI parameters.
299 This callback must return a page object (the object taking control
301 during the response phase). By default, this callback returns the
302 application itself.
303 respond
305 Called to determine how to respond specifically to this set of
306 incoming parameters. Probably updates databases and such.
307 This callback must return a page object (the object taking control
309 during the render phase). By default, this callback returns the
310 same object that had control during the response phase ("stay here"
311 logic), which works most of the time.
312
314 Class::Prototyped, Template::Manual,
315 <http://www.stonehenge.com/merlyn/LinuxMag/col56.html>.
316
318 Please report any bugs or feature requests to
319 bug-cgi-prototype@rt.cpan.org, or through the web interface at
320 http://rt.cpan.org. I will be notified, and then you'll automatically
321 be notified of progress on your bug as I make changes.
322
324 Randal L. Schwartz, <merlyn@stonehenge.com>
325 Special thanks to Geekcruises.com and an unnamed large university for
327 providing funding for the development of this module.
328
330 Copyright (C) 2003, 2004, 2005 by Randal L. Schwartz
331 This library is free software; you can redistribute it and/or modify it
333 under the same terms as Perl itself, either Perl version 5.8.5 or, at
334 your option, any later version of Perl 5 you may have available.
335perl v5.38.0 2023-07-20 CGI::Prototype(3)