Building Sites with Mason

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

Arguments

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" => 'president@whitehouse.gov' &>

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
reuven@lerner.co.il:

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:

$r->content_type("text/html");

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.

Initialization

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: