# Directives for your Apache config files. # Route all requests to the Mason handler. # PerlRequire /opt/mason/eg/handler.pl <Location /> SetHandler perl-script PerlHandler HTML::Mason </Location>
# Sample handler.pl file. # Start Mason and define the mod_perl handler routine. # package HTML::Mason; use HTML::Mason; # brings in subpackages: Parser, Interp, etc. use strict;
my $parser = new HTML::Mason::Parser; my $interp = new HTML::Mason::Interp (parser=>$parser, comp_root=>'/opt/www/htdocs', data_dir=>'/opt/mason/data'); my $ah = new HTML::Mason::ApacheHandler (interp=>$interp); chown ( [getpwnam('nobody')]->[2], [getgrnam('nobody')]->[2], $interp->files_written ); # chown nobody
sub handler { my ($r) = @_; $ah->handle_request($r); }
Mason's various pieces revolve around the notion of ``components''. A component is a mix of HTML, Perl, and special Mason commands, one component per file. So-called ''top-level`` components represent entire web-pages, while smaller components typically return HTML snippets for embedding in top-level components. This object-like architecture greatly simplifies site maintenance: change a shared component, and you instantly changed all dependant pages that refer to it across a site (or across many virtual sites).
Mason's component syntax lets designers separate a web page into programmatic and design elements. This means the esoteric Perl bits can be hidden near the bottom of a component, preloading simple variables for use above in the HTML. In our own experience, this frees content managers (i.e., non-programmers) to work on the layout without getting mired in programming details. Techies, however, still enjoy the full power of Perl.
One of the best ways to learn about Mason is to explore the samples/ directory created during installation. There you will find a collection of components, simple to complex, illustrating most of Mason's component syntax.
Other Mason features include:
Consider this simple Mason component:
% my $noun = 'World'; Hello <% $noun %>! How are ya?
The output of this component is:
Hello World! How are ya?
In this component you see a mix of standard HTML and Mason elements. The bare '%' prefixing the first line tells Mason that this is a line of Perl code. One line below, the embedded <% ... %> tag gets replaced with the return value of its contents, evaluated as a Perl expression.
Beyond this trivial example, components can also embed serious chunks of Perl code (say, to pull records from a database). They can also call other components, cache results for later reuse, and perform all the tricks you expect from a regular Perl program. See HTML::Mason::Components for a full tutorial on building, using and debugging Mason components.
Mason has a standard MakeMaker-driven installation. See the README file for details.
conf
files (httpd.conf
or srm.conf
), into which you insert directives to activate Mason's request handler,
and Mason's handler.pl
file which runs at Apache startup. handler.pl
does two things: it starts up Mason (which then runs persistently within
the httpd), and it defines a handler routine to receive HTTP requests.
The paragraphs below assume some knowledge of mod_perl, Apache configuration details, and the Apache request API. If you're rusty on any these topics, bone up by reading the documentation available at http://www.apache.org (Apache) and http://perl.apache.org (mod_perl). Here you will also find subscription details for the mod_perl mailing list--in my view the best mod_perl resource around.
# Additions to your httpd.conf PerlRequire /usr/local/mason/handler.pl
Alias /mason /usr/local/www/htdocs <Location /mason> SetHandler perl-script PerlHandler HTML::Mason </Location>
These directives tell Apache to first run handler.pl
, the Mason startup file. The ``Alias'' then maps any ``/mason'' URLs into
the DocumentRoot (assuming the DocumentRoot is /usr/local/www/htdocs).
Finally, the <Location> directive routes those requests to the handler routine HTML::Mason::handler
.
If you want to create HTML without necessarily using the .html extension, change your DefaultType:
DefaultType text/html
and make sure mod_mime_magic is not active.
That's it for the Apache configuration. Next you will need to configure
Mason's handler.pl
file, a sample of which is in
eg/handler.pl
. Here you must make some decisions:
httpd.conf
. To prevent ownership and permission conflicts, set the
chown()
parameters to match the UID and GID from your httpd.conf
. See the handler
section in the
Administrator's Guide guide for details.
The simplest remedy is to have Mason decline image and other non-HTML requests, thus letting Apache serve them in the normal way. The following line
return -1 if $r->content_type && $r->content_type !~ m|^text/|io;
declines all requests with a content type not starting with ``text/''. This allows text/html and text/plain to pass through but not much else. It is included (commented out) in the default handler.pl.
my $interp = new HTML::Mason::Interp (parser=>$parser, comp_root=>'/usr/local/www/htdocs' data_dir=>'/usr/local/mason/');
Set these to your own locations, then restart the server and go to some
standard URL on your site, prefixing the URL with ``/mason''. If all goes
well you should see the same page as without the ``/mason'' prefix. If not,
recheck your Apache config files and handler.pl
, and also tail your server's error log.
(If you are getting erroneous ``404 Not Found'' errors, Mason may be having trouble with your document and component root. Make sure ``LogLevel warn'' is in your Apache configuration file, then regenerate the error and check the error log for Mason warnings. One situation that will unfortunately confuse Mason is if your document or component root goes through a soft link. Try specifying your document and component root settings in terms of the true path. On Win32 systems, make sure the document and component roots are spelled with the same case.)
Assuming it worked, you now have a Mason ``lens'' through which to view
your HTML tree. Try adding a Mason tag to some HTML file, say <% 2+2 %>. If you hit Reload and see a ``4'', Mason's up and running. You
can now copy or link the samples/
directory into your new comp_root and check out the sample components in
your browser.
Once you feel comfortable with Mason, you can ``fully'' install it by deleting the ``Alias'' directive from your httpd.conf, and changing the <Location> mapping from ``/mason'' to just ``/''. Now all URLs serve through Mason. If you want to maintain a few directories that don't serve through Mason (e.g. for images), you can put in overrides like so:
<Location /plain> SetHandler */* </Location>
HTML::Mason::Admin describes how to configure Mason to work with multiple virtual servers on the same box.
Whoever is responsible for setting up and tuning Mason should read the Administrator's Manual (HTML::Mason::Admin). Details of Mason's core modules can be found in HTML::Mason::Parser, HTML::Mason::Interp, and HTML::Mason::ApacheHandler.
Most of this documentation assumes that you're running Mason on top of
mod_perl, since that is the most common configuration. If you are using
Mason outside of mod_perl, the documentation is still valid; you'll just
have to ignore mod_perl specific references like $r
and the
ApacheHandler object, and you'll want to read the STANDALONE MODE section
in
HTML::Mason::Interp.