1CGI::Prototype(3)     User Contributed Perl Documentation    CGI::Prototype(3)
2
3
4

NAME

6       CGI::Prototype - Create a CGI application by subclassing
7

SYNOPSIS

9         package My::HelloWorld;
10         use base CGI::Prototype;
11
12         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
17         My::HelloWorld->activate;
18

DESCRIPTION

20       The core of every CGI application seems to be roughly the same:
21
22       ·   Analyze the incoming parameters, cookies, and URLs to determine the
23           state of the application (let's call this "dispatch").
24
25       ·   Based on the current state, analyze the incoming parameters to
26           respond to any form submitted ("respond").
27
28       ·   From there, decide what response page should be generated, and
29           produce it ("render").
30
31       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
39       You can create the null application by simply activating it:
40
41         use CGI::Prototype;
42         CGI::Prototype->activate;
43
44       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
50       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
54         [% my_data = self.get_some_big_data %]
55
56       which is supplied by simply adding the same slot (method or data) in
57       the controlling class:
58
59         sub get_some_big_data {
60           my $self = shift;
61           return $self->some_other_method(size => 'big');
62         }
63
64       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
68       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
72         package My::App;
73         use base CGI::Prototype;
74         sub handler {
75           __PACKAGE__->activate;
76         }
77
78       Note that the $r request object will have to be created if needed if
79       you use this approach.
80
81   CORE SLOTS
82       These slots provide core functionality.  You will probably not need to
83       override these.
84
85       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
92             package My::App;
93             use base qw(CGI::Prototype);
94             My::App->activate;
95
96           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
100       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
104             $self->CGI->self_url
105
106           generates a self-referencing URL.  From a template, this is:
107
108             [% self.CGI.self_url %]
109
110           for the same thing.
111
112           See "initialize_CGI" for how this slot gets established.
113
114       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
120       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
127       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
132       interstitial
133           Please note that this feature is still experimental and subject to
134           change.
135
136           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
143             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
153           "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
157           The list passed to "interstitial" should be a series of hashrefs
158           with one or more parameters reflecting the steps:
159
160           message
161               What the user should see while the step is computing.
162               (Default: "Working...".)
163
164           action
165               A coderef with the action performed server-side during the
166               message.  (Default: no action.)
167
168           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
173           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
186       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
191           The default value is "_interstitial".
192
193   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
199           The Template object is passed the configuration returned from the
200           "engine_config" callback.
201
202       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
206       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
211           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
215       prototype_leave
216           Called when the prototype mechanism is exited, at the very end of
217           each hit.  Defaults to no action.
218
219           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
223       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
227       app_enter
228           Called when the application is entered, at the very beginning of
229           each hit.  Defaults to no action.
230
231       app_leave
232           Called when the application is left, at the very end of each hit.
233           Defaults to no action.
234
235       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
240           This is a great place to hang per-page initialization, because
241           you'll get this callback at most once per hit.
242
243       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
248           This is a great place to hang per-page teardown, because you'll get
249           this callback at most once per hit.
250
251       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
256       render_leave
257           Called when a page loses control specifically for rendering
258           (delivering text to the browser), just before "control_leave".
259
260       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
265       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
271       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
277           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
284           For example, to get at the "barney" parameter:
285
286             The barney field is [% self.param("barney") | html %].
287
288       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
296       dispatch
297           Called to analyze the incoming parameters to define which page
298           object gets control based on the incoming CGI parameters.
299
300           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
304       respond
305           Called to determine how to respond specifically to this set of
306           incoming parameters.  Probably updates databases and such.
307
308           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

SEE ALSO

314       Class::Prototyped, Template::Manual,
315       <http://www.stonehenge.com/merlyn/LinuxMag/col56.html>.
316

BUG REPORTS

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

AUTHOR

324       Randal L. Schwartz, <merlyn@stonehenge.com>
325
326       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
332       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.
335
336
337
338perl v5.28.1                      2011-07-30                 CGI::Prototype(3)
Impressum