my $i = new HTML::Mason::Interp (data_dir=>'/usr/local/mason',
comp_root=>'/usr/local/www/htdocs/',
...other params...);
new() constructor.
If you want to call components outside of mod_perl (e.g. from CGI or a stand-alone Perl script), see the STANDALONE MODE section below.
code_cache_max_size => 20*1024*1024
code_cache_max_size => 20_000_000
Default is 10 MB. See the Code Cache section of the Admin Guide for further details.
You may also specify multiple component roots to be searched in the spirit of Perl's @INC. To do so you must specify a list of lists:
comp_root => [[key1, root1], [key2, root2], ...]
Each pair consists of a key and root. The key is a string that identifies the root mnemonically to a component developer. Data cache and object directories are split up by these keys to make sure different components sharing the same path have different cache and object files. The key is also included whenever Mason prints the component title, as in an error message.
For example:
comp_root => [['private', '/usr/home/joe/comps'],
['main', '/usr/local/www/htdocs']]
This specifies two component roots, a main component tree and a private tree which overrides certain components. The order is respected ala @INC, so 'private' is searched first and 'main' second.
time() value (seconds since the epoch). On time-sensitive
sites, this can be used to set up port-based time/date simulations, e.g. a
port that looks one day into the future.
With no current_time parameter (the default), $m->time reports the true time.
If this parameter is false, then $SIG{__DIE__} will not be overridden at all. Defaults to:
sub { Carp::confess($_[0]) }
my $fh = new IO::File ">mason.out";
...
out_method => sub { $fh->print($_[0]) }
By default, out_method prints to standard output. (In a mod_perl environment this is automatically redirected to the HTTP client.)
preloads => ['/foo/index.html','/bar/*.pl']
Default is the empty list. This should only be used for components that are frequently viewed and rarely updated. See the preloading section of the Admin Guide for further details.
$m->file(). Does not require a trailing slash. For example, if the file root is
'/foo/bar', then $m->file('baz/bap') will read the file '/foo/bar/baz/bap'. Undefined by default; if left
undefined, relative path names to $m->file() are prepended with the current component directory.
my $interp = new HTML::Mason::Interp (...);
my $p = $interp->parser;
my $comproot = $interp->comp_root;
$interp->out_method(\$buf);
The following properties can be queried but not modified: comp_root, data_dir, system_log_file, system_log_separator, preloads.
varname is a variable name, optionally preceded with a prefix ($, @, or
%); if the prefix is omitted then $ is assumed. varname is followed by a value, in the case of a scalar, or by one or more values
in the case of a list or hash. For example:
# Set a global variable $dbh containing the database handle
$interp->set_global(dbh => DBI->connect(...));
# Set a global hash %session from a local hash
$interp->set_global('%session', %s);
The global is set in the package that components run in: usually
HTML::Mason::Commands, although this can be overridden via the Parser parameter in_package. The lines above, for example, are equivalent to:
$HTML::Mason::Commands::dbh = DBI->connect(...);
%HTML::Mason::Commands::session = %s;
assuming that in_package has not been changed.
Any global that you set should also be registered with the Parser parameter allow_globals; otherwise you'll get warnings from
strict.
When using Mason outside of mod_perl, just create an Interp object; you do
not need the ApacheHandler object. Once you've created an interpreter, the
main thing you'll want to do with it is call a component and do something
with the output. To call a component, use Interp's exec()
method:
$interp->exec(<comp> [,<..list of component params..>]);
where comp is a component path or component object.
Component parameters are given as a series of name/value pairs, just as
they are with $m->comp. exec returns the return value of the component. Component output is sent
to standard output by default, but you can change this by specifying out_method.
#!/usr/bin/perl -w
use CGI;
use HTML::Mason;
use HTML::Mason::Utils qw(cgi_request_args);
my $interp = new HTML::Mason::Interp (comp_root=>'...',
data_dir=>'...');
my $q = new CGI;
my $comp = $ENV{'PATH_TRANSLATED'};
my $root = $interp->comp_root;
$comp =~ s/^$root//
or die "Requested file '$comp' is outside component root '$root'";
my %args = cgi_request_args($q, $q->request_method);
print $q->header;
$interp->exec($comp, %args);
The relevant portions of the httpd.conf file look like:
DocumentRoot /path/to/comp/root
ScriptAlias /cgi-bin/ /path/to/cgi-bin/
Action html-mason /cgi-bin/handler.cgi
<Directory /path/to/comp/root>
SetHandler html-mason
</Directory>
This simply causes Apache to call handler.cgi every time a file under the component root is requested.
It should be noted that because this script simply prints standard HTTP headers and then executes a component, there would be no way of sending non-OK responses to the browser from your components.
A more complex handler.cgi script might look like this:
#!/usr/bin/perl -w
use CGI;
use HTML::Mason;
use HTML::Mason::Compiler::ToObject;
use HTML::Mason::Utils qw(cgi_request_args);
use HTTP::Headers;
my $parser = new HTML::Mason::Parser (allow_globals='$H');
my $interp = new HTML::Mason::Interp (comp_root=>'...',
data_dir=>'...',
parser=>$parser);
my $q = new CGI;
my $comp = $ENV{'PATH_TRANSLATED'};
my $root = $interp->comp_root;
$comp =~ s/^$root//
or die "Requested file '$comp' is outside component root '$root'";
my %args = cgi_request_args($q, $q->request_method);
# Gather all component output into a buffer.
my $buffer;
$interp->out_method(\$buffer);
my $H = new HTTP::Headers;
$interp->set_global('$H'=>$H);
eval { $interp->exec($comp, %args) };
if ($@) {
handle_error($@);
} else {
unless ($H->header('content-type')) {
$H->header('content-type' => 'text/html');
}
print $H->as_string;
print $buffer;
}
This script offers components the use of a global named $h which can be used to set headers (for example, for a redirect). It also
catches errors in the execution of the script and has a routine to handle
them.
my $outbuf;
my $interp = new HTML::Mason::Interp (comp_root=>'<component root>',
data_dir=>'<data directory>',
out_method=>\$outbuf);
my $retval = $interp->exec('<component path>', <args>...);
open(F,">mason.out");
print F $outbuf;
close(F);
print "return value of component was: $retval\n";
This allows you to use Mason as a pure text templating solution -- like Text::Template and its brethren, but with more power (and of course more complexity).