/ 
HTML-Mason-0.2
River stage two • 42 direct dependents • 77 total dependents
/ Mason

NAME

Mason - High-performance, dynamic web site authoring system

SYNOPSIS

# 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 ( 60001, 60001, $interp->files_written );  # chown nobody

sub handler
{
    my ($r) = @_;
    $ah->handle_request($r);
}

DESCRIPTION

Mason is a tool for building, serving and managing large web sites. Its features make it an ideal backend for high load sites serving dynamic content, such as online newspapers or database driven e-commerce sites.

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:

Caching

Mason caches components after compilation, and offers an internal, shared, expireable data cache for use by components themselves.

Standalone Option

Mason is optimized for use with mod_perl, but can also be used as a standalone tool to generate other types of dynamic text files (similar to ePerl).

Debugging

Mason includes a debugging mode whereby HTTP requests can be captured to "debug files" for later replay inside Perl's command-line debugger (as opposed to the non-interactive mod_perl interpreter).

Previewer

Mason includes a powerful previewing utility which acts as a proxy between Mason and incoming requests. Using a web interface, users create "port profiles" that massage requests in all kinds of interesting ways: different browsers may be simulated, different request ports, different times of day, etc.

Mason works by intercepting innocent-looking requests (say, http://www.yoursite.com/index.html) and mapping them to requests for Mason components. Mason then compiles the component, runs it, and feeds the output back to the client.

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.

INSTALLATION

Mason has been tested under Linux and Solaris, but not yet (by us) under Win32. As an all-Perl solution, though, it should work on any machine that has working versions of Perl 5.004+, mod_perl, and the required CPAN modules.

Mason has a standard MakeMaker-driven installation. See the README file for details.

CONFIGURING MASON

Mason's configuration depends on two files: your Apache 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.

Single Site Configuration

The simplest Mason component is one composed of pure HTML, so the fast track is simply to attach Mason to some branch of your server's DocumentRoot, like so:

# 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, you might optionally change your DefaultType:

DefaultType text/html

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 about where certain files should live:

Where is the component root (comp_root)?

Mason introduces the idea of a "component root" which, like the DocumentRoot, is a virtual root for the component filesystem. In this example we equate the two roots; other configurations will opt to keep them separate.

Where is the data directory (data_dir)?

Mason generates various data files, which live in topical directories under Mason's "data directory".

What is the UID and GID that the server runs under?

If your web server is running on a privileged port like 80, the parent process runs as root and spawns children under the 'User' and 'Group' IDs listed in your 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.

Both comp_root and the data_dir are set when Mason creates a new Interp object:

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.

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.

HTML::Mason::Admin describes how to configure Mason to work with multiple virtual servers on the same box.

DOCUMENTATION ROADMAP

Once Mason is on its feet, the next step is to write a component or two. The Mason Developer's Manual (HTML::Mason::Components) is a complete tutorial for writing, using, and debugging components. A companion to the Developer's Manual is the Mason commands reference, HTML::Mason::Commands.

System Admins, or others interested in configuring Mason or tuning for performance, should read HTML::Mason::Admin. Details of Mason's core modules can be found in HTML::Mason::Parser, HTML::Mason::Interp, and HTML::Mason::ApacheHandler.

AUTHOR

Jonathan Swartz, swartz@transbay.net

SEE ALSO

HTML::Mason::Components, HTML::Mason::Commands, HTML::Mason::Parser, HTML::Mason::Interp, HTML::Mason::ApacheHandler