HTML::Mason::CGIHandler - Use Mason in a CGI environment
In httpd.conf or .htaccess:
<LocationMatch "\.html$">
Action html-mason /cgi-bin/mason_handler.cgi
AddHandler html-mason .html
</LocationMatch>
<LocationMatch "^/cgi-bin/">
RemoveHandler .html
</LocationMatch>
<FilesMatch "(autohandler|dhandler)$">
Order allow,deny
Deny from all
</FilesMatch>
A script at /cgi-bin/mason_handler.pl :
#!/usr/bin/perl
use HTML::Mason::CGIHandler;
my $h = HTML::Mason::CGIHandler->new
(
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->err_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 HTML::Mason::Request object $m to
provide direct access to the CGI query, should such access be necessary.
HTML::Mason::CGIHandler Methods
Creates a new handler. Accepts any parameter that the Interpreter accepts.
If no comp_root parameter is passed to new(), the component root
will be $ENV{DOCUMENT_ROOT}.
$ENV{QUERY_STRING}
or STDIN and sending headers and component output to STDOUT.
This method doesn't accept any parameters. The initial component
will be the one specified in $ENV{PATH_INFO}.
Like 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.
Also like 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
path_info() method.
HTML::Mason::FakeApache object, 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.
Apache method of the same name. In an array
context, it will return a %hash of response headers. In a scalar context,
it will return a reference to the case-insensitive hash blessed into the
HTML::Mason::FakeTable class. The values initially populated in this hash are
extracted from the CGI environment variables as best as possible. The pattern
is to merely reverse the conversion from HTTP headers to CGI variables as
documented here: http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1.
Apache method of the same name. When passed the
name of a header, returns the value of the given incoming header. When passed
a name and a value, sets the value of the header. Setting the header to
undef will actually unset the header (instead of setting its value to
undef), removing it from the table of headers returned from future calls to
headers_in() or header_in().
Apache method of the same name. In an array
context, it will return a %hash of response headers. In a scalar context,
it will return a reference to the case-insensitive hash blessed into the
HTML::Mason::FakeTable class. Changes made to this hash will be made to the
headers that will eventually be passed to the CGI module's header()
method.
This works much like the Apache method 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 undef will 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 CGI module's header()
method.
Apache method of the same name. In an array
context, it will return a %hash of error response headers. In a scalar
context, it will return a reference to the case-insensitive hash blessed into
the HTML::Mason::FakeTable class. Changes made to this hash will be made to
the error headers that will eventually be passed to the CGI module's
header() method.
This works much like the Apache method of the same name. When passed the
name of a header, returns the value of the given outgoing error header. When
passed a name and a value, sets the value of the error header. Setting the
header to undef will 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 CGI module's header() method.
One header currently gets special treatment - if you set a Location
header, you'll cause the CGI module's 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->err_header_out(Location => 'http://redirect.to/here');
You may be happier using the $m->redirect method, 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-Type header directly with header_out(). Like
header_out(), setting the content type to undef will 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 undef.
If no content type is set during the request, the default MIME type
text/html will be used.
Apache method of the same name. When passed
a $key argument, it returns the value of the note for that key. When
passed a $value argument, it stores that value under the key. Keys are
case-insensitive, and both the key and the value must be strings. When
called in a scalar context with no $key argument, it returns a hash
reference blessed into the HTML::Mason::FakeTable class.
notes(), but takes any scalar as an value, and stores the
values in a case-sensitive hash.
Apache method of the same name, but is simply populated with
the current values of the environment. Still, it's useful, because values can
be changed and then seen by later components, but the environment itself
remains unchanged. Like the Apache method, it will reset all of its values
to the current environment again if it's called without a $key argument.
$m methods
The $m object provided in components has all the functionality of
the regular HTML::Mason::Request object $m, and the following:
Returns the current CGI request 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.
$r is set to when you use
this class.
HTML::Mason::FakeTable Methods
This class emulates the behavior of the Apache::Table class, and is
used to store manage the tables of values for the following attributes
of <$r>:
HTML::Mason::FakeTable is designed to behave exactly like Apache::Table,
and differs in only one respect. When a given key has multiple values in an
Apache::Table object, one can fetch each of the values for that key using
Perl's each operator:
while (my ($k, $v) = each %{$r->headers_out}) {
push @cookies, $v if lc $k eq 'set-cookie';
}
If anyone knows how Apache::Table does this, let us know! In the meantime, use
get() or do() to get at all of the values for a given key (get() is
much more efficient, anyway).
Since the methods named for these attributes return an
HTML::Mason::FakeTable object hash in a scalar reference, it seemed only
fair to document its interface.
HTML::Mason::FakeTable object. Any parameters passed
to new() will be added to the table as initial values.
get() is called in an array context, and
only the first value when it is called in a scalar context.
set() will
turn it into one. A value of undef will have the same behavior as
unset().