Set up HTML::Mason, the Perl-based template management system

Once you have followed our guide on creating a local LAMP (Linux, Apache, MySQL and PHP/Perl) development environment, you can proceed to install those useful Perl packages for web site development. Among them, HTML::Mason, the Perl-based template management system is the one you will have to spend a lot of time to master. In this article, we describe Mason installation and setup in detail. In subsequent articles, we will provide more concrete examples on how to use Mason to manage your files and create dynamic web sites.

Though Mason can be used standalone as a template management system for your files, it is more often used together with mod_perl and Apache to build dynamic web sites. We suggest you install mod_perl first and then Mason and then you can use it in both ways.

To install mod_perl, download and unpack it and run the following commands, assuming that your Apache base installation directory is /opt/dev/apache:

perl Makefile.PL MP_APXS=/opt/dev/apache/bin/apxs
gmake
gmake install

Now your local Apache configuration file /opt/dev/apache/conf/httpd.conf should have the following line added automatically:

LoadModule perl_module modules/mod_perl.so

Now you can install Mason using the CPAN module. Just run perl -MCPAN -eshell and then at the CPAN command prompt, you can just type install HTML::Mason to install it.

Now we use a few short and simple examples to show how to configure and use Mason.

We first show examples when using Mason in a standalone script. This will require you create an HTML::Mason::Interp object as follows:

$interp = HTML::Mason::Interp->new
  (comp_root => $curdir,
  data_dir => "/tmp",
  out_method => \$outbuf
);

Here you need to specify the directory for comp_root which you can just think of is the place where you put your template files. The data_dir variable stores temporary files generated by Mason. The out_method, when passed a scalar reference, will store the output after Mason processes the template files.

Then you can call the interpreter's method exec to populate the earlier scalar variable with the output after processing the template file. You can also pass additional arguments to the exec method which can be referenced as the %ARGS hash variable in your Mason template file. The method call looks like this:

$interp->exec("/$file", user => 'john');

In your Mason template file, the $ARGS{'user'} will then have the value of john. For your convenience, you can download the sample standalone script that uses Mason to process a given template file directly. Then you can create the following two Mason template files under the same directory.

The first one is just a simple one-line template file named mason_welcome.txt.sample:

% print "Welcome to Mason!\n";

It shows that the percent sign % starts a line of Perl code in the template file. Then you can run

perl mason_standalone.perl.sample mason_welcome.txt.sample

which outputs

Welcome to Mason!

It is clear that the template file is processed. Now you can create another Mason template file that processes input argument.

<%perl>
my $user;
if ($ARGS{'user'}) {
  ($user = $ARGS{'user'}) =~ s/[^0-9a-zA-Z]//g;
} else {
  $user = 'guest';
}
</%perl>
Welcome, <% $user %>!

Here you use <%perl> and </%perl> to add a block of Perl code to the template file. Input arguments to the template are stored in the %ARGS hash variable. As can be seen from the example, you can also substitute Perl variable into the running text with the <% and %> tags. Now you can run the following command

perl mason_standalone.perl.sample mason_greetings.txt.sample

Remember earlier in the standalone Perl script we pass user => 'john' to the Mason interpreter, so the output is

Welcome, john!

You can see the user name is properly substituted.

Now we can move on to run Mason under mod_perl and Apache's context. For this you don't need to write any Perl script to create and execute the Mason interpreter. However you do need to make some changes to your Apache configuration files.

First you need to create an Apache configuration file to load Mason modules and define the root directory for Mason components. Please create a configuration file named mason.conf with the following content:

PerlModule HTML::Mason::ApacheHandler
PerlAddVar MasonCompRoot "main => /var/tmp/local/apache/htdocs/mason"
# We only need Mason at /mason directory
<LocationMatch "/mason/.*(\.html|\.txt|\.pl)$">
  SetHandler perl-script
  PerlHandler HTML::Mason::ApacheHandler
</LocationMatch>

In this configuration file, we first load the Mason module and define the Mason component root. Then we specify that for all the .html, .txt, .pl files under the /mason directory, they will be handled by Mason. Now you can include this configuration file into your main Apache configuration file by adding the following line to /opt/dev/apache/conf/httpd.conf:

Include conf/mason.conf

Assuming that your Apache's document root is /opt/dev/apache/htdocs, then you can create the /opt/dev/apache/htdocs/mason directory, copy the above two sample files mason_welcome.txt.sample and mason_greetings.txt.sample to that directory and change their suffix to .txt.

Now restart apache and point your browser to the following URLs:

http://<host>:<port>/mason/mason_welcome.txt

http://<host>:<port>/mason/mason_greetings.txt

The first one returns the following as before:

Welcome to Mason!

The second one returns the following:

Welcome, guest!

Please note here we are not using Mason standalone: If you need to pass arguments to the Mason template file, then you can do it through the query parameters in the URL or through HTTP POST request. Try the following:

http://<host>:<port>/mason/mason_greetings.txt?user=john

and you will get the output with the user name properly populated:

Welcome, john!

Now with Mason working either in a standalone Perl script or in a mod_perl/Apache environment, you can explore Mason more confidently. :)

Back to articles on setup

Copyright © 2008-2010, yuonlamp.com. All rights reserved.