HTML::Mason::CGIHandler - Use Mason in a CGI environment
In httpd.conf or .htaccess:
Action html-mason /cgi-bin/mason_handler.cgi <FilesMatch "\.html$"> SetHandler html-mason </FilesMatch>
A script at /cgi-bin/mason_handler.pl :
#!/usr/bin/perl use HTML::Mason::CGIHandler; my $h = new HTML::Mason::CGIHandler ( data_dir => '/home/jethro/code/mason_data', allow_globals => [qw(%session $u)], ); $h->handle_request;
A .html component somewhere in the web server's document root:
<%args> $mood => 'satisfied' </%args> % $r->header_out(Location => "http://blahblahblah.com/moodring/$mood.html"); ...
This module lets you execute Mason components in a CGI environment. It lets you keep your top-level components in the web server's document root, using regular component syntax and without worrying about the particular details of invoking Mason on each request.
If you want to use Mason components from within a regular CGI script (or any other Perl program, for that matter), then you don't need this module. You can simply follow the directions in the Using Mason from a standalone script section of the administrator's manual.
This module also provides an
$r request object for use inside components, similar to the Apache request object under
HTML::Mason::ApacheHandler, but limited in functionality. Please note that we aim to replicate the
mod_perl functionality as closely as possible - if you find differences, do not depend on them to stay different. We may fix them in a future release. Also, if you need some missing functionality in
$r, let us know, we might be able to provide it.
Finally, this module alters the
$m to provide direct access to the CGI query, should such access be necessary.
Creates a new handler. Accepts any parameter that the Interpreter accepts.
comp_rootparameter is passed to
new(), the component root will be
Handles the current request, reading input from
STDINand sending headers and component output to
STDOUT. This method doesn't accept any parameters. The initial component will be the one specified in
handle_request(), but the first (only) parameter is a component path or component object. This is useful within a traditional CGI environment, in which you're essentially using Mason as a templating language but not an application server.
handle_component()will create a CGI query object, parse the query parameters, and send the HTTP header and component output to STDOUT. If you want to handle those parts yourself, see the Using Mason from a standalone script section of the administrator's manual.
handle_request(), but this method takes only a CGI object as its parameter. This can be quite useful if you want to use this module with CGI::Fast.
The component path will be the value of the CGI object's
HTML::Mason::FakeApacheobject, this method is expected to return a hash containing the arguments to be passed to the component. It is a separate method in order to make it easily overrideable in a subclass.
Returns the Mason Interpreter associated with this handler. The Interpreter lasts for the entire lifetime of the handler.
This works much like the
Apachemethod of the same name. When passed the name of a header, returns the value of the given outgoing header. When passed a name and a value, sets the value of the header. Setting the header to
undefwill actually unset the header (instead of setting its value to
undef), removing it from the table of headers that will be sent to the client.
The headers are eventually passed to the
One header currently gets special treatment - if you set a
Locationheader, you'll cause the
redirect()method to be used instead of the
header()method. This means that in order to do a redirect, all you need to do is:
$r->header_out(Location => 'http://redirect.to/here');
You may be happier using the
$m->redirectmethod, though, because it hides most of the complexities of sending headers and getting the status code right.
When passed an argument, sets the content type of the current request to the value of the argument. Use this method instead of setting a
Content-Typeheader directly with
header_out(), setting the content type to
undefwill remove any content type set previously.
When called without arguments, returns the value set by a previous call to
content_type(). The behavior when
content_type()hasn't already been set is undefined - currently it returns
If no content type is set during the request, the default MIME type
text/htmlwill be used.
This method returns the outgoing headers as a string, suitable for sending to the client.
This method returns a hash containing the parameters sent by the client. Multiple parameters of the same name are represented by array references. If both POST and query string arguments were submitted, these will be merged together.
$m object provided in components has all the functionality of the regular
$m, and the following:
Returns the current
CGIrequest object. This is handy for processing cookies or perhaps even doing HTML generation (but is that really what you want to do?). If you pass an argument to this method, you can set the request object to the argument passed. Use this with care, as it may affect components called after the current one (they may check the content length of the request, for example).
Note that the ApacheHandler class (for using Mason under mod_perl) also provides a
cgi_object()method that does the same thing as this one. This makes it easier to write components that function equally well under CGIHandler and ApacheHandler.
Returns the object that is used to emulate Apache's request object. In other words, this is the object that
$ris set to when you use this class.