Building Sites with Mason

This month, Mr. Lerner introduces us to a Mod-perl module to aid in building large, dynamic web sites.

The above examples of header and footer components are good for simple sites. However, it would be more useful if our header and footer components could take arguments, allowing us to modify parts of their content as necessary.

Mason indeed allows components to send and receive arguments, giving an extra level of flexibility. To pass arguments to an invoked component, place a comma between the component's name and a list of name,value pairs. For example:

<& header, "address" => '' &>

Components can receive passed arguments in special <%args> sections, traditionally placed at the bottom of a component file. An <%args> section declares arguments for a component, with an optional default value if none are passed to the component. For example, the following <%args> section declares the $name and $address variables. An argument without a default variable is mandatory. $name has no default value, while $address has a default value of

$address => ''
We can rewrite footer.comp in this way:
<!-- begin component: footer.comp -->
<a href="<% $address %>"><% $name ? $name : $address %></a>
$name => ""
$address => ''
<!-- end component: footer.comp -->
Finally, we can rewrite output.html to send the required parameter without the optional parameter:
<& header.comp &>
<P>This is the body</P>
<& footer.comp, "name" => 'Reuven' &>

$m and $r

Experienced mod_perl programmers might like the idea of the components Mason provides. However, there are times when it is easiest to accomplish something by reaching into the guts of Apache and working with the mod_perl request object, traditionally called $r.

Mason provides each component with a copy of $r, so we can work with the internals of the server. For example, we can send an HTTP Content-type of “text/html” by using the content_type method:


Because <%perl> sections are invoked before the actual HTTP headers are returned, Mason components can modify all response headers in this way, including working with HTTP cookies.

A similar object, called $m, is specific to Mason and allows us to invoke methods having to do with Mason components and development. For example, we can retrieve the contents of a component with the $m->scomp method. The manual page at HTML::Mason::Devel lists many more methods that can be invoked on $m.


Mason gives us two sections, <%init> and <%once>, in which to run Perl code at the beginning of a component's execution.

An <%init> section is evaluated before any <%perl> sections, as well as any other Perl code in the component. This gives the component a chance to define variables and retrieve information on its environment. In effect, <%init> is the same as <%perl>, except it can be placed anywhere in the component, rather than at the top. Traditionally, <%init> sections are placed near the bottom, along with the other special sections.

An <%init> section is evaluated each time a component is invoked. However, there are items that need to be created only the first time a component is invoked, rather than every time. Such items can be put in a <%once> section. Lexicals and subroutines declared within a <%once> section remain throughout the life of the component, making them particularly useful for initializing the component's state. However, <%once> sections are not evaluated within the context of a Mason request, which means they cannot invoke other components.

Mason components that connect to a relational database with Perl's DBI often use a combination of <%once>, <%init> and $m to reuse database handles. We can do the following, for example, as suggested in the Mason documentation:

my $dbh;    # Declare $dbh only once
# If this is the first time we're running,
# connect to the database
if ($m->current_comp->first_time)
$dbh = DBI->connect("DBI:mysql:$database:localhost",
                 $username, $password) ||
die qq{DBI error from connect: "$DBI::errstr"};