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 compo‐
56 nents, 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 pro‐
62 vide 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 neces‐
66 sary.
67 "HTML::Mason::CGIHandler" Methods
69 * new()
71 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}
79 or "STDIN" and sending headers and component output to "STDOUT".
80 This method doesn't accept any parameters. The initial component
81 will be the one specified in $ENV{PATH_INFO}.
82 * handle_comp()
84 Like "handle_request()", but the first (only) parameter is a compo‐
85 nent path or component object. This is useful within a traditional
86 CGI environment, in which you're essentially using Mason as a tem‐
87 plating language but not an application server.
88 "handle_component()" will create a CGI query object, parse the
90 query parameters, and send the HTTP header and component output to
91 STDOUT. If you want to handle those parts yourself, see the Using
92 Mason from a standalone script section of the administrator's man‐
93 ual.
94 * handle_cgi_object()
96 Also like "handle_request()", but this method takes only a CGI
97 object as its parameter. This can be quite useful if you want to
98 use this module with CGI::Fast.
99 The component path will be the value of the CGI object's
101 "path_info()" method.
102 * request_args()
104 Given an "HTML::Mason::FakeApache" object, this method is expected
105 to return a hash containing the arguments to be passed to the com‐
106 ponent. It is a separate method in order to make it easily over‐
107 rideable in a subclass.
108 * interp()
110 Returns the Mason Interpreter associated with this handler. The
111 Interpreter lasts for the entire lifetime of the handler.
112 $r Methods
114 * headers_in()
116 This works much like the "Apache" method of the same name. In an
117 array context, it will return a %hash of response headers. In a
118 scalar context, it will return a reference to the case-insensitive
119 hash blessed into the "HTML::Mason::FakeTable" class. The values
120 initially populated in this hash are extracted from the CGI envi‐
121 ronment variables as best as possible. The pattern is to merely
122 reverse the conversion from HTTP headers to CGI variables as docu‐
123 mented here:
124 <http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1>.
125 * header_in()
127 This works much like the "Apache" method of the same name. When
128 passed the name of a header, returns the value of the given incom‐
129 ing header. When passed a name and a value, sets the value of the
130 header. Setting the header to "undef" will actually unset the
131 header (instead of setting its value to "undef"), removing it from
132 the table of headers returned from future calls to "headers_in()"
133 or "header_in()".
134 * headers_out()
136 This works much like the "Apache" method of the same name. In an
137 array context, it will return a %hash of response headers. In a
138 scalar context, it will return a reference to the case-insensitive
139 hash blessed into the "HTML::Mason::FakeTable" class. Changes made
140 to this hash will be made to the headers that will eventually be
141 passed to the "CGI" module's "header()" method.
142 * header_out()
144 This works much like the "Apache" method of the same name. When
145 passed the name of a header, returns the value of the given outgo‐
146 ing header. When passed a name and a value, sets the value of the
147 header. Setting the header to "undef" will actually unset the
148 header (instead of setting its value to "undef"), removing it from
149 the table of headers that will be sent to the client.
150 The headers are eventually passed to the "CGI" module's "header()"
152 method.
153 * err_headers_out()
155 This works much like the "Apache" method of the same name. In an
156 array context, it will return a %hash of error response headers. In
157 a scalar context, it will return a reference to the case-insensi‐
158 tive hash blessed into the "HTML::Mason::FakeTable" class. Changes
159 made to this hash will be made to the error headers that will even‐
160 tually be passed to the "CGI" module's "header()" method.
161 * err_header_out()
163 This works much like the "Apache" method of the same name. When
164 passed the name of a header, returns the value of the given outgo‐
165 ing error header. When passed a name and a value, sets the value of
166 the error header. Setting the header to "undef" will actually unset
167 the header (instead of setting its value to "undef"), removing it
168 from the table of headers that will be sent to the client.
169 The headers are eventually passed to the "CGI" module's "header()"
171 method.
172 One header currently gets special treatment - if you set a "Loca‐
174 tion" header, you'll cause the "CGI" module's "redirect()" method
175 to be used instead of the "header()" method. This means that in
176 order to do a redirect, all you need to do is:
177 $r->err_header_out(Location => 'http://redirect.to/here');
179 You may be happier using the "$m->redirect" method, though, because
181 it hides most of the complexities of sending headers and getting
182 the status code right.
183 * content_type()
185 When passed an argument, sets the content type of the current
186 request to the value of the argument. Use this method instead of
187 setting a "Content-Type" header directly with "header_out()". Like
188 "header_out()", setting the content type to "undef" will remove any
189 content type set previously.
190 When called without arguments, returns the value set by a previous
192 call to "content_type()". The behavior when "content_type()"
193 hasn't already been set is undefined - currently it returns
194 "undef".
195 If no content type is set during the request, the default MIME type
197 "text/html" will be used.
198 * method()
200 Returns the request method used for the current request, e.g.,
201 "GET", "POST", etc.
202 * http_header()
204 This method returns the outgoing headers as a string, suitable for
205 sending to the client.
206 * send_http_header()
208 Sends the outgoing headers to the client.
209 * notes()
211 This works much like the "Apache" method of the same name. When
212 passed a $key argument, it returns the value of the note for that
213 key. When passed a $value argument, it stores that value under the
214 key. Keys are case-insensitive, and both the key and the value must
215 be strings. When called in a scalar context with no $key argument,
216 it returns a hash reference blessed into the
217 "HTML::Mason::FakeTable" class.
218 * pnotes()
220 Like "notes()", but takes any scalar as an value, and stores the
221 values in a case-sensitive hash.
222 * subprocess_env()
224 Works like the "Apache" method of the same name, but is simply pop‐
225 ulated with the current values of the environment. Still, it's use‐
226 ful, because values can be changed and then seen by later compo‐
227 nents, but the environment itself remains unchanged. Like the
228 "Apache" method, it will reset all of its values to the current
229 environment again if it's called without a $key argument.
230 * params()
232 This method returns a hash containing the parameters sent by the
233 client. Multiple parameters of the same name are represented by
234 array references. If both POST and query string arguments were
235 submitted, these will be merged together.
236 Added $m methods
238 The $m object provided in components has all the functionality of the
240 regular "HTML::Mason::Request" object $m, and the following:
241 * cgi_object()
243 Returns the current "CGI" request object. This is handy for pro‐
244 cessing cookies or perhaps even doing HTML generation (but is that
245 really what you want to do?). If you pass an argument to this
246 method, you can set the request object to the argument passed. Use
247 this with care, as it may affect components called after the cur‐
248 rent one (they may check the content length of the request, for
249 example).
250 Note that the ApacheHandler class (for using Mason under mod_perl)
252 also provides a "cgi_object()" method that does the same thing as
253 this one. This makes it easier to write components that function
254 equally well under CGIHandler and ApacheHandler.
255 * cgi_request()
257 Returns the object that is used to emulate Apache's request object.
258 In other words, this is the object that $r is set to when you use
259 this class.
260 "HTML::Mason::FakeTable" Methods
262 This class emulates the behavior of the "Apache::Table" class, and is
264 used to store manage the tables of values for the following attributes
265 of <$r>:
266 headers_in
268 headers_out
269 err_headers_out
270 notes
271 subprocess_env
272 "HTML::Mason::FakeTable" is designed to behave exactly like
274 "Apache::Table", and differs in only one respect. When a given key has
275 multiple values in an "Apache::Table" object, one can fetch each of the
276 values for that key using Perl's "each" operator:
277 while (my ($k, $v) = each %{$r->headers_out}) {
279 push @cookies, $v if lc $k eq 'set-cookie';
280 }
281 If anyone knows how Apache::Table does this, let us know! In the mean‐
283 time, use "get()" or "do()" to get at all of the values for a given key
284 ("get()" is much more efficient, anyway).
285 Since the methods named for these attributes return an
287 "HTML::Mason::FakeTable" object hash in a scalar reference, it seemed
288 only fair to document its interface.
289 * new()
291 Returns a new "HTML::Mason::FakeTable" object. Any parameters
292 passed to "new()" will be added to the table as initial values.
293 * add()
295 Adds a new value to the table. If the value did not previously
296 exist under the given key, it will be created. Otherwise, it will
297 be added as a new value to the key.
298 * clear()
300 Clears the table of all values.
301 * do()
303 Pass a code reference to this method to have it iterate over all of
304 the key/value pairs in the table. Keys will multiple values will
305 trigger the execution of the code reference multiple times for each
306 value. The code reference should expect two arguments: a key and a
307 value. Iteration terminates when the code reference returns false,
308 to be sure to have it return a true value if you wan it to iterate
309 over every value in the table.
310 * get()
312 Gets the value stored for a given key in the table. If a key has
313 multiple values, all will be returned when "get()" is called in an
314 array context, and only the first value when it is called in a
315 scalar context.
316 * merge()
318 Merges a new value with an existing value by concatenating the new
319 value onto the existing. The result is a comma-separated list of
320 all of the values merged for a given key.
321 * set()
323 Takes key and value arguments and sets the value for that key. Pre‐
324 vious values for that key will be discarded. The value must be a
325 string, or "set()" will turn it into one. A value of "undef" will
326 have the same behavior as "unset()".
327 * unset()
329 Takes a single key argument and deletes that key from the table, so
330 that none of its values will be in the table any longer.
331
333 HTML::Mason, HTML::Mason::Admin, HTML::Mason::ApacheHandler
334perl v5.8.8 2007-04-17 HTML::Mason::CGIHandler(3)