1HTML::Mason::CGIHandlerU(s3e)r Contributed Perl DocumentaHtTiMoLn::Mason::CGIHandler(3)
2
6 HTML::Mason::CGIHandler - Use Mason in a CGI environment
7
9 In httpd.conf or .htaccess:
10 <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 A script at /cgi-bin/mason_handler.pl :
24 #!/usr/bin/perl
26 use HTML::Mason::CGIHandler;
27 my $h = HTML::Mason::CGIHandler->new
29 (
30 data_dir => '/home/jethro/code/mason_data',
31 allow_globals => [qw(%session $u)],
32 );
33 $h->handle_request;
35 A .html component somewhere in the web server's document root:
37 <%args>
39 $mood => 'satisfied'
40 </%args>
41 % $r->err_header_out(Location => "http://blahblahblah.com/moodring/$mood.html");
42 ...
43
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 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 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 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 "HTML::Mason::CGIHandler" Methods
69 · new()
70 Creates a new handler. Accepts any parameter that the Interpreter
72 accepts.
73 If no "comp_root" parameter is passed to "new()", the component
75 root will be $ENV{DOCUMENT_ROOT}.
76 · handle_request()
78 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 · handle_comp()
85 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 "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 · handle_cgi_object()
98 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 The component path will be the value of the CGI object's
104 "path_info()" method.
105 · request_args()
107 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 · interp()
114 Returns the Mason Interpreter associated with this handler. The
116 Interpreter lasts for the entire lifetime of the handler.
117 $r Methods
119 · headers_in()
120 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 <http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1>.
131 · header_in()
133 This works much like the "Apache" method of the same name. When
135 passed the name of a header, returns the value of the given
136 incoming header. When passed a name and a value, sets the value of
137 the header. Setting the header to "undef" will actually unset the
138 header (instead of setting its value to "undef"), removing it from
139 the table of headers returned from future calls to "headers_in()"
140 or "header_in()".
141 · headers_out()
143 This works much like the "Apache" method of the same name. In an
145 array context, it will return a %hash of response headers. In a
146 scalar context, it will return a reference to the case-insensitive
147 hash blessed into the "HTML::Mason::FakeTable" class. Changes made
148 to this hash will be made to the headers that will eventually be
149 passed to the "CGI" module's "header()" method.
150 · header_out()
152 This works much like the "Apache" method of the same name. When
154 passed the name of a header, returns the value of the given
155 outgoing header. When passed a name and a value, sets the value of
156 the header. Setting the header to "undef" will actually unset the
157 header (instead of setting its value to "undef"), removing it from
158 the table of headers that will be sent to the client.
159 The headers are eventually passed to the "CGI" module's "header()"
161 method.
162 · err_headers_out()
164 This works much like the "Apache" method of the same name. In an
166 array context, it will return a %hash of error response headers. In
167 a scalar context, it will return a reference to the case-
168 insensitive hash blessed into the "HTML::Mason::FakeTable" class.
169 Changes made to this hash will be made to the error headers that
170 will eventually be passed to the "CGI" module's "header()" method.
171 · err_header_out()
173 This works much like the "Apache" method of the same name. When
175 passed the name of a header, returns the value of the given
176 outgoing error header. When passed a name and a value, sets the
177 value of the error header. Setting the header to "undef" will
178 actually unset the header (instead of setting its value to
179 "undef"), removing it from the table of headers that will be sent
180 to the client.
181 The headers are eventually passed to the "CGI" module's "header()"
183 method.
184 One header currently gets special treatment - if you set a
186 "Location" header, you'll cause the "CGI" module's "redirect()"
187 method to be used instead of the "header()" method. This means
188 that in order to do a redirect, all you need to do is:
189 $r->err_header_out(Location => 'http://redirect.to/here');
191 You may be happier using the "$m->redirect" method, though, because
193 it hides most of the complexities of sending headers and getting
194 the status code right.
195 · content_type()
197 When passed an argument, sets the content type of the current
199 request to the value of the argument. Use this method instead of
200 setting a "Content-Type" header directly with "header_out()". Like
201 "header_out()", setting the content type to "undef" will remove any
202 content type set previously.
203 When called without arguments, returns the value set by a previous
205 call to "content_type()". The behavior when "content_type()"
206 hasn't already been set is undefined - currently it returns
207 "undef".
208 If no content type is set during the request, the default MIME type
210 "text/html" will be used.
211 · method()
213 Returns the request method used for the current request, e.g.,
215 "GET", "POST", etc.
216 · http_header()
218 This method returns the outgoing headers as a string, suitable for
220 sending to the client.
221 · send_http_header()
223 Sends the outgoing headers to the client.
225 · notes()
227 This works much like the "Apache" method of the same name. When
229 passed a $key argument, it returns the value of the note for that
230 key. When passed a $value argument, it stores that value under the
231 key. Keys are case-insensitive, and both the key and the value must
232 be strings. When called in a scalar context with no $key argument,
233 it returns a hash reference blessed into the
234 "HTML::Mason::FakeTable" class.
235 · pnotes()
237 Like "notes()", but takes any scalar as an value, and stores the
239 values in a case-sensitive hash.
240 · subprocess_env()
242 Works like the "Apache" method of the same name, but is simply
244 populated with the current values of the environment. Still, it's
245 useful, because values can be changed and then seen by later
246 components, but the environment itself remains unchanged. Like the
247 "Apache" method, it will reset all of its values to the current
248 environment again if it's called without a $key argument.
249 · params()
251 This method returns a hash containing the parameters sent by the
253 client. Multiple parameters of the same name are represented by
254 array references. If both POST and query string arguments were
255 submitted, these will be merged together.
256 Added $m methods
258 The $m object provided in components has all the functionality of the
259 regular "HTML::Mason::Request" object $m, and the following:
260 · cgi_object()
262 Returns the current "CGI" request object. This is handy for
264 processing cookies or perhaps even doing HTML generation (but is
265 that really what you want to do?). If you pass an argument to this
266 method, you can set the request object to the argument passed. Use
267 this with care, as it may affect components called after the
268 current one (they may check the content length of the request, for
269 example).
270 Note that the ApacheHandler class (for using Mason under mod_perl)
272 also provides a "cgi_object()" method that does the same thing as
273 this one. This makes it easier to write components that function
274 equally well under CGIHandler and ApacheHandler.
275 · cgi_request()
277 Returns the object that is used to emulate Apache's request object.
279 In other words, this is the object that $r is set to when you use
280 this class.
281 "HTML::Mason::FakeTable" Methods
283 This class emulates the behavior of the "Apache::Table" class, and is
284 used to store manage the tables of values for the following attributes
285 of <$r>:
286 headers_in
288 headers_out
289 err_headers_out
290 notes
291 subprocess_env
292 "HTML::Mason::FakeTable" is designed to behave exactly like
294 "Apache::Table", and differs in only one respect. When a given key has
295 multiple values in an "Apache::Table" object, one can fetch each of the
296 values for that key using Perl's "each" operator:
297 while (my ($k, $v) = each %{$r->headers_out}) {
299 push @cookies, $v if lc $k eq 'set-cookie';
300 }
301 If anyone knows how Apache::Table does this, let us know! In the
303 meantime, use "get()" or "do()" to get at all of the values for a given
304 key ("get()" is much more efficient, anyway).
305 Since the methods named for these attributes return an
307 "HTML::Mason::FakeTable" object hash in a scalar reference, it seemed
308 only fair to document its interface.
309 · new()
311 Returns a new "HTML::Mason::FakeTable" object. Any parameters
313 passed to "new()" will be added to the table as initial values.
314 · add()
316 Adds a new value to the table. If the value did not previously
318 exist under the given key, it will be created. Otherwise, it will
319 be added as a new value to the key.
320 · clear()
322 Clears the table of all values.
324 · do()
326 Pass a code reference to this method to have it iterate over all of
328 the key/value pairs in the table. Keys will multiple values will
329 trigger the execution of the code reference multiple times for each
330 value. The code reference should expect two arguments: a key and a
331 value. Iteration terminates when the code reference returns false,
332 to be sure to have it return a true value if you wan it to iterate
333 over every value in the table.
334 · get()
336 Gets the value stored for a given key in the table. If a key has
338 multiple values, all will be returned when "get()" is called in an
339 array context, and only the first value when it is called in a
340 scalar context.
341 · merge()
343 Merges a new value with an existing value by concatenating the new
345 value onto the existing. The result is a comma-separated list of
346 all of the values merged for a given key.
347 · set()
349 Takes key and value arguments and sets the value for that key.
351 Previous values for that key will be discarded. The value must be a
352 string, or "set()" will turn it into one. A value of "undef" will
353 have the same behavior as "unset()".
354 · unset()
356 Takes a single key argument and deletes that key from the table, so
358 that none of its values will be in the table any longer.
359
361 HTML::Mason, HTML::Mason::Admin, HTML::Mason::ApacheHandler
362perl v5.12.0 2010-05-03 HTML::Mason::CGIHandler(3)