1HTML::Mason::CGIHandlerU(s3e)r Contributed Perl DocumentaHtTiMoLn::Mason::CGIHandler(3)
2
3
4

NAME

6       HTML::Mason::CGIHandler - Use Mason in a CGI environment
7

SYNOPSIS

9       In httpd.conf or .htaccess:
10
11           <LocationMatch "\.html$">
12               Action html-mason /cgi-bin/mason_handler.cgi
13               AddHandler html-mason .html
14           </LocationMatch>
15           <LocationMatch "^/cgi-bin/">
16               RemoveHandler .html
17           </LocationMatch>
18           <FilesMatch "(autohandler|dhandler)$">
19               Order allow,deny
20               Deny from all
21           </FilesMatch>
22
23       A script at /cgi-bin/mason_handler.pl :
24
25          #!/usr/bin/perl
26          use HTML::Mason::CGIHandler;
27
28          my $h = HTML::Mason::CGIHandler->new
29           (
30            data_dir  => '/home/jethro/code/mason_data',
31            allow_globals => [qw(%session $u)],
32           );
33
34          $h->handle_request;
35
36       A .html component somewhere in the web server's document root:
37
38          <%args>
39           $mood => 'satisfied'
40          </%args>
41          % $r->err_header_out(Location => "http://blahblahblah.com/moodring/$mood.html");
42          ...
43

DESCRIPTION

45       This module lets you execute Mason components in a CGI environment.  It
46       lets you keep your top-level components in the web server's document
47       root, using regular component syntax and without worrying about the
48       particular details of invoking Mason on each request.
49
50       If you want to use Mason components from within a regular CGI script
51       (or any other Perl program, for that matter), then you don't need this
52       module.  You can simply follow the directions in the Using Mason from a
53       standalone script section of the administrator's manual.
54
55       This module also provides an $r request object for use inside
56       components, similar to the Apache request object under
57       "HTML::Mason::ApacheHandler", but limited in functionality.  Please
58       note that we aim to replicate the "mod_perl" functionality as closely
59       as possible - if you find differences, do not depend on them to stay
60       different.  We may fix them in a future release.  Also, if you need
61       some missing functionality in $r, let us know, we might be able to
62       provide it.
63
64       Finally, this module alters the "HTML::Mason::Request" object $m to
65       provide direct access to the CGI query, should such access be
66       necessary.
67
68   "HTML::Mason::CGIHandler" Methods
69       ·   new()
70
71           Creates a new handler.  Accepts any parameter that the Interpreter
72           accepts.
73
74           If no "comp_root" parameter is passed to "new()", the component
75           root will be $ENV{DOCUMENT_ROOT}.
76
77       ·   handle_request()
78
79           Handles the current request, reading input from $ENV{QUERY_STRING}
80           or "STDIN" and sending headers and component output to "STDOUT".
81           This method doesn't accept any parameters.  The initial component
82           will be the one specified in $ENV{PATH_INFO}.
83
84       ·   handle_comp()
85
86           Like "handle_request()", but the first (only) parameter is a
87           component path or component object.  This is useful within a
88           traditional CGI environment, in which you're essentially using
89           Mason as a templating language but not an application server.
90
91           "handle_component()" will create a CGI query object, parse the
92           query parameters, and send the HTTP header and component output to
93           STDOUT.  If you want to handle those parts yourself, see the Using
94           Mason from a standalone script section of the administrator's
95           manual.
96
97       ·   handle_cgi_object()
98
99           Also like "handle_request()", but this method takes only a CGI
100           object as its parameter.  This can be quite useful if you want to
101           use this module with CGI::Fast.
102
103           The component path will be the value of the CGI object's
104           "path_info()" method.
105
106       ·   request_args()
107
108           Given an "HTML::Mason::FakeApache" object, this method is expected
109           to return a hash containing the arguments to be passed to the
110           component.  It is a separate method in order to make it easily
111           overrideable in a subclass.
112
113       ·   interp()
114
115           Returns the Mason Interpreter associated with this handler.  The
116           Interpreter lasts for the entire lifetime of the handler.
117
118   $r Methods
119       ·   headers_in()
120
121           This works much like the "Apache" method of the same name. In an
122           array context, it will return a %hash of response headers. In a
123           scalar context, it will return a reference to the case-insensitive
124           hash blessed into the "HTML::Mason::FakeTable" class. The values
125           initially populated in this hash are extracted from the CGI
126           environment variables as best as possible. The pattern is to merely
127           reverse the conversion from HTTP headers to CGI variables as
128           documented here:
129           <http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1>.
130
131       ·   header_in()
132
133           This works much like the "Apache" method of the same name. When
134           passed the name of a header, returns the value of the given
135           incoming header. When passed a name and a value, sets the value of
136           the header. Setting the header to "undef" will actually unset the
137           header (instead of setting its value to "undef"), removing it from
138           the table of headers returned from future calls to "headers_in()"
139           or "header_in()".
140
141       ·   headers_out()
142
143           This works much like the "Apache" method of the same name. In an
144           array context, it will return a %hash of response headers. In a
145           scalar context, it will return a reference to the case-insensitive
146           hash blessed into the "HTML::Mason::FakeTable" class. Changes made
147           to this hash will be made to the headers that will eventually be
148           passed to the "CGI" module's "header()" method.
149
150       ·   header_out()
151
152           This works much like the "Apache" method of the same name.  When
153           passed the name of a header, returns the value of the given
154           outgoing header.  When passed a name and a value, sets the value of
155           the header.  Setting the header to "undef" will actually unset the
156           header (instead of setting its value to "undef"), removing it from
157           the table of headers that will be sent to the client.
158
159           The headers are eventually passed to the "CGI" module's "header()"
160           method.
161
162       ·   err_headers_out()
163
164           This works much like the "Apache" method of the same name. In an
165           array context, it will return a %hash of error response headers. In
166           a scalar context, it will return a reference to the case-
167           insensitive hash blessed into the "HTML::Mason::FakeTable" class.
168           Changes made to this hash will be made to the error headers that
169           will eventually be passed to the "CGI" module's "header()" method.
170
171       ·   err_header_out()
172
173           This works much like the "Apache" method of the same name. When
174           passed the name of a header, returns the value of the given
175           outgoing error header. When passed a name and a value, sets the
176           value of the error header. Setting the header to "undef" will
177           actually unset the header (instead of setting its value to
178           "undef"), removing it from the table of headers that will be sent
179           to the client.
180
181           The headers are eventually passed to the "CGI" module's "header()"
182           method.
183
184           One header currently gets special treatment - if you set a
185           "Location" header, you'll cause the "CGI" module's "redirect()"
186           method to be used instead of the "header()" method.  This means
187           that in order to do a redirect, all you need to do is:
188
189            $r->err_header_out(Location => 'http://redirect.to/here');
190
191           You may be happier using the "$m->redirect" method, though, because
192           it hides most of the complexities of sending headers and getting
193           the status code right.
194
195       ·   content_type()
196
197           When passed an argument, sets the content type of the current
198           request to the value of the argument.  Use this method instead of
199           setting a "Content-Type" header directly with "header_out()".  Like
200           "header_out()", setting the content type to "undef" will remove any
201           content type set previously.
202
203           When called without arguments, returns the value set by a previous
204           call to "content_type()".  The behavior when "content_type()"
205           hasn't already been set is undefined - currently it returns
206           "undef".
207
208           If no content type is set during the request, the default MIME type
209           "text/html" will be used.
210
211       ·   method()
212
213           Returns the request method used for the current request, e.g.,
214           "GET", "POST", etc.
215
216       ·   http_header()
217
218           This method returns the outgoing headers as a string, suitable for
219           sending to the client.
220
221       ·   send_http_header()
222
223           Sends the outgoing headers to the client.
224
225       ·   notes()
226
227           This works much like the "Apache" method of the same name. When
228           passed a $key argument, it returns the value of the note for that
229           key. When passed a $value argument, it stores that value under the
230           key. Keys are case-insensitive, and both the key and the value must
231           be strings. When called in a scalar context with no $key argument,
232           it returns a hash reference blessed into the
233           "HTML::Mason::FakeTable" class.
234
235       ·   pnotes()
236
237           Like "notes()", but takes any scalar as an value, and stores the
238           values in a case-sensitive hash.
239
240       ·   subprocess_env()
241
242           Works like the "Apache" method of the same name, but is simply
243           populated with the current values of the environment. Still, it's
244           useful, because values can be changed and then seen by later
245           components, but the environment itself remains unchanged. Like the
246           "Apache" method, it will reset all of its values to the current
247           environment again if it's called without a $key argument.
248
249       ·   params()
250
251           This method returns a hash containing the parameters sent by the
252           client.  Multiple parameters of the same name are represented by
253           array references.  If both POST and query string arguments were
254           submitted, these will be merged together.
255
256   Added $m methods
257       The $m object provided in components has all the functionality of the
258       regular "HTML::Mason::Request" object $m, and the following:
259
260       ·   cgi_object()
261
262           Returns the current "CGI" request object.  This is handy for
263           processing cookies or perhaps even doing HTML generation (but is
264           that really what you want to do?).  If you pass an argument to this
265           method, you can set the request object to the argument passed.  Use
266           this with care, as it may affect components called after the
267           current one (they may check the content length of the request, for
268           example).
269
270           Note that the ApacheHandler class (for using Mason under mod_perl)
271           also provides a "cgi_object()" method that does the same thing as
272           this one.  This makes it easier to write components that function
273           equally well under CGIHandler and ApacheHandler.
274
275       ·   cgi_request()
276
277           Returns the object that is used to emulate Apache's request object.
278           In other words, this is the object that $r is set to when you use
279           this class.
280
281   "HTML::Mason::FakeTable" Methods
282       This class emulates the behavior of the "Apache::Table" class, and is
283       used to store manage the tables of values for the following attributes
284       of <$r>:
285
286       headers_in
287       headers_out
288       err_headers_out
289       notes
290       subprocess_env
291
292       "HTML::Mason::FakeTable" is designed to behave exactly like
293       "Apache::Table", and differs in only one respect. When a given key has
294       multiple values in an "Apache::Table" object, one can fetch each of the
295       values for that key using Perl's "each" operator:
296
297         while (my ($k, $v) = each %{$r->headers_out}) {
298             push @cookies, $v if lc $k eq 'set-cookie';
299         }
300
301       If anyone knows how Apache::Table does this, let us know! In the
302       meantime, use "get()" or "do()" to get at all of the values for a given
303       key ("get()" is much more efficient, anyway).
304
305       Since the methods named for these attributes return an
306       "HTML::Mason::FakeTable" object hash in a scalar reference, it seemed
307       only fair to document its interface.
308
309       ·   new()
310
311           Returns a new "HTML::Mason::FakeTable" object. Any parameters
312           passed to "new()" will be added to the table as initial values.
313
314       ·   add()
315
316           Adds a new value to the table. If the value did not previously
317           exist under the given key, it will be created. Otherwise, it will
318           be added as a new value to the key.
319
320       ·   clear()
321
322           Clears the table of all values.
323
324       ·   do()
325
326           Pass a code reference to this method to have it iterate over all of
327           the key/value pairs in the table. Keys will multiple values will
328           trigger the execution of the code reference multiple times for each
329           value. The code reference should expect two arguments: a key and a
330           value. Iteration terminates when the code reference returns false,
331           to be sure to have it return a true value if you wan it to iterate
332           over every value in the table.
333
334       ·   get()
335
336           Gets the value stored for a given key in the table. If a key has
337           multiple values, all will be returned when "get()" is called in an
338           array context, and only the first value when it is called in a
339           scalar context.
340
341       ·   merge()
342
343           Merges a new value with an existing value by concatenating the new
344           value onto the existing. The result is a comma-separated list of
345           all of the values merged for a given key.
346
347       ·   set()
348
349           Takes key and value arguments and sets the value for that key.
350           Previous values for that key will be discarded. The value must be a
351           string, or "set()" will turn it into one. A value of "undef" will
352           have the same behavior as "unset()".
353
354       ·   unset()
355
356           Takes a single key argument and deletes that key from the table, so
357           that none of its values will be in the table any longer.
358
359
360
361perl v5.32.0                      2020-07-28        HTML::Mason::CGIHandler(3)
Impressum