Perl Cd Bookshelf [Electronic resources] نسخه متنی

21.16. Templating with HTML::Mason

You
want to separate presentation (HTML formatting) from logic (Perl
code) in your program. Your web site has a lot of components with
only slight variations between them. You'd like to abstract out
common elements and build your pages from templates without having a
lot of "if I'm in this page, then print this; else if I'm in some
other page . . . " conditional statements in a single master
template.

21.16.2. Solution

21.16.3. Discussion

HTML::Mason (also simply called Mason) offers the power of Perl in
templates. The basic unit of a web site built with Mason is the
component—a file that produces output. The file can be HTML,
Perl, or a mixture of both. Components can take arguments and execute
arbitrary Perl code. Mason has many features, documented at
http://masonhq.com and in
Embedding Perl in HTML with Mason by Dave
Rolsky and Ken Williams (O'Reilly; online at http://masonbook.com).

Mason works equally well with CGI, mod_perl, and non-web programs.
For the purposes of this recipe, however, we look at how to use it
with mod_perl. The rest of this recipe contains a few demonstrations
to give you a feel for what you can do with Mason and how your site
will be constructed. There are more tricks, traps, and techniques for
everything we discuss, though, so be sure to visit the web site and
read the book for the full story.

21.16.3.1. Configuration

Install
the HTML-Mason distribution from CPAN and add the following to your
httpd.conf:

PerlModule HTML::Mason::ApacheHandler
<Location /mason>
SetHandler perl-script
PerlHandler HTML::Mason::ApacheHandler
DefaultType text/html
</Location>

This tells mod_perl that every URL that starts with
/mason is handled by Mason. So if you request
/mason/hellol, the file
mason/hellol in your document directory will
be compiled and executed as a Mason component. The DefaultType
directive lets you omit the l from component
names.

Next create a directory for Mason to cache the compiled components
in. Mason does this to speed up execution.

cd $SERVER_ROOT
mkdir mason

Then make a mason directory for components to
live in:

cd $DOCUMENT_ROOT
mkdir mason

Now you're ready for "Hello, World". Put this in
mason/hello:

Hello, <% ("World", "Puny Human")[rand 2] %>

Restart Apache and load up the mason/hello page. If you reload it, you
should see "Hello, World" and "Hello, Puny Human" randomly. If not,
look at the Mason FAQ (http://www.masonhq.com/docs/faq/), which
answers most commonly encountered problems.

21.16.3.2. Basic Mason syntax

There are four types of new markup in
Mason components: substitutions, Perl code, component calls, and
block tags. You saw a substitution in the "Hello World" example:
<% ... %> evaluates the contents as Perl
code and inserts the result into the surrounding text.

Perl code is marked with a % at the start of the
line:

% $now = localtime; # embedded Perl
This page was generated on <% $now %>.

Because substitutions can be almost any Perl code you like, this
could have been written more simply as:

This page was generated on <% scalar localtime %>.

If either of these variations were saved in
footer.mas, you could include it simply by
saying:

<& footer.mas &>

This is an example of a component call—Mason runs the component
and inserts its result into the document that made the call.

Block tags define different regions of your component.
<%perl> ... </%perl> identifies Perl
code. While % at the start of a line indicates
that just that line is Perl code, you can have any number of lines in
a <%perl> block.

A <%init> ... </%init> block is like
an INIT block in Perl. The code in the block is executed before the
main body of code. It lets you store definitions, initialization,
database connections, etc. at the bottom of your component, where
they're out of the way of the main logic.

The <%args> ... </%args> block lets
you define arguments to your component, optionally with default
values. For example, here's greet.mas:

<%args>
$name => "Larry"
$town => "Mountain View"
</%args>
Hello, <% $name %>. How's life in <% $town %>?

Calling it with:

<& greet.mas &>

emits:

Hello, Larry. How's life in Mountain View?

You can provide options on the component call:

<& greet.mas, name => "Nat", town => "Fort Collins" &>

That emits:

Hello, Nat. How's life in Fort Collins?

Because there are default values, you can supply only some of the
arguments:

<& greet.mas, name => "Bob" &>

That emits:

Hello, Bob. How's life in Mountain View?

Arguments are also how Mason components access form parameters. Take
this form:

<form action="compliment">
How old are you? <input type="text" name="age"> <br />
<input type="submit">
</form>

Here's a compliment component that could take
that parameter:

<%args>
$age
</%args>
Hi. Are you really <% $age %>? You don't look it!

21.16.3.3. Objects

All
Mason components have access to a $m variable,
which contains an HTML::Mason::Request object. Methods on this object
give access to Mason features. For example, you can redirect with:

$m->redirect($URL);

The $r variable is the mod_perl request object, so
you have access to the information and functions of Apache from your
Mason handlers. For example, you can discover the client's IP address
with:

$ip = $r->connection->remote_ip;

21.16.3.4. Autohandlers

When
a page is requested through Mason, Mason can do more than simply
execute the code in that page. Mason inspects each directory between
the component root and the requested page, looking for components
called autohandler. This forms a
wrapping chain, with the top-level autohandler
at the start of the chain and the requested page at the end. Mason
then executes the code at the start of the chain. Each autohandler
can say "insert the output of the next component in the chain here."

Imagine a newspaper site. Some parts don't change, regardless of
which article you're looking at: the banner at the top, the random
selection of ads, the list of sections down the lefthand side.
However, the actual article text varies from article to article.
Implement this in Mason with a directory structure like this:

/sports
/sports/autohandler
/sports/story1
/sports/story2
/sports/story3

The individual story files contain only the text of each story. The
autohandler builds the page (the banner, the ads, the navigation
bar), and when it wants to insert the content of the story, it says:

% $m->call_next;

This tells Mason to call the next component in the chain (the story)
and insert its output here.

The technique of having a chain of components is called
inheritance, and autohandlers aren't the only
way to do it. In a component, you can designate a parent with:

<%flags>
inherit = 'parent.mas'
</%flags>

This lets you have different types of content in the one directory,
and each contained component gets to identify its surrounding page
(its parent).

21.16.3.5. Dhandlers

Sometimes
it's nice to provide the illusion of a directory full of pages, when
in reality they are all dynamically generated. For example, stories
kept in a database could be accessed through URLs like:

/sports/1
/sports/2
/sports/3

The Mason way to dynamically generate the pages at these URLs is with
a component called dhandler in the
sports directory. The
dhandler component accesses the name of the
missing page (123 in this case) by calling:

$m->dhandler_arg

You could then use this to retrieve the story from the database and
insert it into a page template.

21.16.4. See Also

Recipe 15.11 in mod_perl Developer's Cookbook;
Embedding Perl in HTML with Mason; http://www.masonhq.com and http://www.masonbook.com

21.15. Benchmarking a mod_perl Application		21.17. Templating with Template Toolkit

---

Copyright © 2003 O'Reilly & Associates. All rights reserved.