In this case Mason constructs the following search path:
/newsfeeds/LocalNews/Story1 => no such thing
/newsfeeds/LocalNews/dhandler => no such thing
/newsfeeds/dhandler => found! (search ends)
/dhandler
The found dhandler would read "LocalNews/Story1" from "$m->dhandler_arg"
and use it as a retrieval key into a database of stories.
Here's how a simple /newsfeeds/dhandler might look:
<& header &>
<% $headline %>
<% $body %>
<& footer &>
<%init>
my $arg = $m->dhandler_arg; # get rest of path
my ($section, $story) = split("/", $arg); # split out pieces
my $sth = $DBH->prepare
(qq{SELECT headline,body FROM news
WHERE section = ? AND story = ?);
$sth->execute($section, $story);
my ($headline, $body) = $sth->fetchrow_array;
return 404 if !$headline; # return "not found" if no such story
By default dhandlers do not get a chance to handle requests to a
directory itself (e.g. /newsfeeds). These are automatically deferred to
Apache, which generates an index page or a FORBIDDEN error. Often this
is desirable, but if necessary the administrator can let in directory
requests as well; see the allowing directory requests section of the
administrator's manual.
A component or dhandler that does not want to handle a particular
request may defer control to the next dhandler by calling "$m->decline".
When using dhandlers under mod_perl, you may find that sometimes Apache
will not set a content type for a response. This usually happens when a
dhandler handles a request for a non-existent file or directory. You can
add a "" or "" block containing a "SetType"
directive to your Apache config file, or you can just set the content
type dynamically by calling "$r->content_type".
The administrator can customize the file name used for dhandlers with
the dhandler_name parameter.
autohandlers
Autohandlers allow you to grab control and perform some action just
before Mason calls the top-level component. This might mean adding a
standard header and footer, applying an output filter, or setting up
global variables.
Autohandlers are directory based. When Mason determines the top-level
component, it checks that directory and all parent directories for a
component called autohandler. If found, the autohandler is called first.
After performing its actions, the autohandler typically calls
"$m->call_next" to transfer control to the original intended component.
"$m->call_next" works just like "$m->comp" except that the component
path and arguments are implicit. You can pass additional arguments to
"$m->call_next"; these are merged with the original arguments, taking
precedence in case of conflict. This allows you, for example, to
override arguments passed in the URL.
Here is an autohandler that adds a common header and footer to each page
underneath its directory:
McHuffy Incorporated
% $m->call_next;
Copyright 1999 McHuffy Inc.
Same idea, using components for the header/footer:
<& /shared/header &>
% $m->call_next;
<& /shared/footer &>
The next autohandler applies a filter to its pages, adding an absolute
hostname to relative image URLs:
% $m->call_next;
<%filter>
s{(]+src=\")/} {$1}ig;
Most of the time autohandler can simply call "$m->call_next" without
needing to know what the next component is. However, should you need it,
the component object is available from "$m->fetch_next". This is useful
for calling the component manually, e.g. if you want to suppress some
original arguments or if you want to use "$m->scomp" to store and
process the output.
If more than one autohandler applies to a page, each autohandler gets a
chance to run. The top-most autohandler runs first; each "$m->call_next"
transfers control to the next autohandler and finally to the originally
called component. This allows you, for example, to combine general
site-wide templates and more specific section-based templates.
Autohandlers can be made even more powerful in conjunction with Mason's
object-oriented style features: methods, attributes, and inheritance. In
the interest of space these are discussed in a separate section,
Object-Oriented Techniques.
The administrator can customize the file name used for autohandlers with
the autohandler_name parameter.
dhandlers vs. autohandlers
dhandlers and autohandlers both provide a way to exert control over a
large set of URLs. However, each specializes in a very different
application. The key difference is that dhandlers are invoked only when
no appropriate component exists, while autohandlers are invoked only in
conjunction with a matching component.
As a rule of thumb: use an autohandler when you have a set of components
to handle your pages and you want to augment them with a
template/filter. Use a dhandler when you want to create a set of
"virtual URLs" that don't correspond to any actual components, or to
provide default behavior for a directory.
dhandlers and autohandlers can even be used in the same directory. For
example, you might have a mix of real URLs and virtual URLs to which you
would like to apply a common template/filter.
## PASSING PARAMETERS
This section describes Mason's facilities for passing parameters to
components (either from HTTP requests or component calls) and for
accessing parameter values inside components.
In Component Calls
Any Perl data type can be passed in a component call:
<& /sales/header, s => 'dog', l => [2, 3, 4], h => {a => 7, b => 8} &>
This command passes a scalar ($s), a list (@l), and a hash (%h). The
list and hash must be passed as references, but they will be
automatically dereferenced in the called component.
In HTTP requests
Consider a CGI-style URL with a query string:
or an HTTP request with some POST content. Mason automatically parses
the GET/POST values and makes them available to the component as
parameters.
Accessing Parameters
Component parameters, whether they come from GET/POST or another
component, can be accessed in two ways.
1. Declared named arguments: Components can define an "<%args>" section
listing argument names, types, and default values. For example:
<%args>
$a
@b # a comment
%c
# another comment
$d => 5
$e => $d*2
@f => ('foo', 'baz')
%g => (joe => 1, bob => 2)
Here, *$a*, *@b*, and *%c* are required arguments; the component
generates an error if the caller leaves them unspecified. *$d*, *$e*,
*@f* and *%g* are optional arguments; they are assigned the specified
default values if unspecified. All the arguments are available as
lexically scoped ("my") variables in the rest of the component.
Arguments are separated by one or more newlines. Comments may be used at
the end of a line or on their own line.
Default expressions are evaluated in top-to-bottom order, and one
expression may reference an earlier one (as $e references $d above).
Only valid Perl variable names may be used in "<%args>" sections.
Parameters with non-valid variable names cannot be pre-declared and must
be fetched manually out of the %ARGS hash (see below). One common
example of undeclarable parameters are the "button.x/button.y"
parameters sent for a form submit.
2. %ARGS hash: This variable, always available, contains all of the
parameters passed to the component (whether or not they were declared).
It is especially handy for dealing with large numbers of parameters,
dynamically named parameters, or parameters with non-valid variable
names. %ARGS can be used with or without an "<%args>" section, and its
contents are unrelated to what you have declared in "<%args>".
Here's how to pass all of a component's parameters to another component:
<& template, %ARGS &>
Parameter Passing Examples
The following examples illustrate the different ways to pass and receive
parameters.
1. Passing a scalar *id* with value 5.
In a URL: /my/URL?id=5
In a component call: <& /my/comp, id => 5 &>
In the called component, if there is a declared argument named...
$id, then $id will equal 5
@id, then @id will equal (5)
%id, then an error occurs
In addition, $ARGS{id} will equal 5.
2. Passing a list *colors* with values red, blue, and green.
In a URL: /my/URL?colors=red&colors=blue&colors=green
In an component call: <& /my/comp, colors => ['red', 'blue', 'green'] &>
In the called component, if there is a declared argument named...
$colors, then $colors will equal ['red', 'blue', 'green']
@colors, then @colors will equal ('red', 'blue', 'green')
%colors, then an error occurs
In addition, $ARGS{colors} will equal ['red', 'blue', 'green'].
3. Passing a hash *grades* with pairs Alice => 92 and Bob => 87.
In a URL: /my/URL?grades=Alice&grades=92&grades=Bob&grades=87
In an component call: <& /my/comp, grades => {Alice => 92, Bob => 87} &>
In the called component, if there is a declared argument named...
@grades, then @grades will equal ('Alice', 92, 'Bob', 87)
%grades, then %grades will equal (Alice => 92, Bob => 87)
In addition, $grade and $ARGS{grades} will equal
['Alice',92,'Bob',87] in the URL case, or {Alice => 92, Bob => 87}
in the component call case. (The discrepancy exists because, in a
query string, there is no detectable difference between a list or
hash.)
Using @_ instead
If you don't like named parameters, you can pass a traditional list of
ordered parameters:
<& /mktg/prods.html', 'dog', [2, 3, 4], {a => 7, b => 8} &>
and access them as usual through Perl's @_ array:
my ($scalar, $listref, $hashref) = @_;
In this case no "<%args>" section is necessary.
We generally recommend named parameters for the benefits of readability,
syntax checking, and default value automation. However using @_ may be
convenient for very small components, especially subcomponents created
with "<%def>".
Before Mason 1.21, @_ contained *copies* of the caller's arguments. In
Mason 1.21 and beyond, this unnecessary copying was eliminated and @_
now contains *aliases* to the caller's arguments, just as with regular
Perl subroutines. For example, if a component updates $_[0], the
corresponding argument is updated (or an error occurs if it is not
updateable).
Most users won't notice this change because "<%args>" variables and the
%ARGS hash always contain copies of arguments.
See perlsub for more information on @_ aliasing.
## INITIALIZATION AND CLEANUP
The following sections contain blocks of Perl to execute at specific
times.
<%init>
This section contains initialization code that executes as soon as the
component is called. For example: checking that a user is logged in;
selecting rows from a database into a list; parsing the contents of a
file into a data structure.
Technically an "<%init>" block is equivalent to a "<%perl>" block at the
beginning of the component. However, there is an aesthetic advantage of
placing this block at the end of the component rather than the
beginning.
We've found that the most readable components (especially for
non-programmers) contain HTML in one continuous block at the top, with
simple substitutions for dynamic elements but no distracting blocks of
Perl code. At the bottom an "<%init>" block sets up the substitution
variables. This organization allows non-programmers to work with the
HTML without getting distracted or discouraged by Perl code. For
example:
<% $headline %>
<% $headline %>
By <% $author %>, <% $date %>
<% $body %>
<%init>
# Fetch article from database
my $dbh = [DBI::connect] ...;
my $sth = $dbh->prepare("select * from articles where id = ?");
$sth->execute($article_id);
my ($headline, $date, $author, $body) = $sth->fetchrow_array;
# Massage the fields
$headline = uc($headline);
my ($year, $month, $day) = split('-', $date);
$date = "$month/$day";
<%args>
$article_id
<%cleanup>
This section contains cleanup code that executes just before the
component exits. For example: closing a database connection or closing a
file handle.
A "<%cleanup>" block is equivalent to a "<%perl>" block at the end of
the component. This means it will NOT execute if the component
explicitly returns, or if an abort or error occurs in that component or
one of its children. Because of this limitation, and because Perl is
usually so good about cleaning up at the end of a lexical scope (e.g.
component), "<%cleanup>" sections are rarely needed.
If you need code that is guaranteed to run when the component or request
exits, consider using a mod_perl cleanup handler, or creating a custom
class with a DESTROY method.
<%once>
This code executes once when the component is loaded. Variables declared
in this section can be seen in all of a component's code and persist for
the lifetime of the component.
This section is useful for declaring persistent component-scoped lexical
variables (especially objects that are expensive to create), declaring
subroutines (both named and anonymous), and initializing state.
This code does not run inside a request context. You cannot call
components or access $m or $r from this section. Also, do not attempt to
"return()" from a "<%once>" section; the current compiler cannot
properly handle it.
Normally this code will execute individually from every HTTP child that
uses the component. However, if the component is preloaded, this code
will only execute once in the parent. Unless you have total control over
what components will be preloaded, it is safest to avoid initializing
variables that can't survive a fork(), e.g. DBI handles. Use code like
this to initialize such variables in the "<%init>" section:
<%once>
my $dbh; # declare but don't assign
...
<%init>
$dbh ||= [DBI::connect] ...
...
In addition, using $m or $r in this section will not work in a preloaded
component, because neither of those variable exist when a component is
preloaded.
<%shared>
As with "<%once>", lexical ("my") variables declared in this section can
be seen in all the rest of a component's code: the main body,
subcomponents, and methods. However, unlike "<%once>", the code runs
once per request (whenever the component is used) and its variables last
only until the end of the request.
A "<%shared>" section is useful for initializing variables needed in,
say, the main body and one more subcomponents or methods. See
Object-Oriented Techniques for an example of usage.
It's important to realize that you do not have access to the %ARGS hash
or variables created via an "<%args>" block inside a shared section.
However, you can access arguments via $m->request_args.
Additionally, you cannot call a components' own methods or subcomponents
from inside a "<%shared>", though you can call other components.
Avoid using "<%shared>" for side-effect code that needs to run at a
predictable time during page generation. You may assume only that
"<%shared>" runs just before the first code that needs it and runs at
most once per request.
In the current implementation, the scope sharing is done with closures,
so variables will only be shared if they are visible at compile-time in
the other parts of the component. In addition, you can't rely on the
specific destruction time of the shared variables, because they may not
be destroyed until the first time the "<%shared>" section executes in a
future request. "<%init>" offers a more predictable execution and
destruction time.
Currently any component with a "<%shared>" section incurs an extra
performance penalty, because Mason must recreate its anonymous
subroutines the first time each new request uses the component. The
exact penalty varies between systems and for most applications will be
unnoticeable. However, one should avoid using "<%shared>" when patently
unnecessary, e.g. when an "<%init>" would work just as well.
Do not attempt to "return()" from a "<%shared>" section; the current
compiler cannot properly handle it.
## EMBEDDED COMPONENTS
<%def *name*>
Each instance of this section creates a *subcomponent* embedded inside
the current component. Inside you may place anything that a regular
component contains, with the exception of "<%def>", "<%method>",
"<%once>", and "<%shared>" tags.
The *name* consists of characters in the set "[\w._-]". To call a
subcomponent simply use its name in <& &> or "$m->comp". A subcomponent
can only be seen from the surrounding component.
If you define a subcomponent with the same name as a file-based
component in the current directory, the subcomponent takes precedence.
You would need to use an absolute path to call the file-based component.
To avoid this situation and for general clarity, we recommend that you
pick a unique way to name all of your subcomponents that is unlikely to
interfere with file-based components. A commonly accepted practice is to
start subcomponent names with ".".
While inside a subcomponent, you may use absolute or relative paths to
call file-based components and also call any of your "sibling"
subcomponents.
The lexical scope of a subcomponent is separate from the main component.
However a subcomponent can declare its own "<%args>" section and have
relevant values passed in. You can also use a "<%shared>" section to
declare variables visible from both scopes.
In the following example, we create a ".link" subcomponent to produce a
standardized hyperlink:
<%def .link>
<% $label %>
<%args>
$site
$label=>ucfirst($site)
Visit these sites:
- <& .link, site=>'yahoo' &>
- <& .link, site=>'cmp', label=>'CMP Media' &>
- <& .link, site=>'excite' &>
<%method *name*>
Each instance of this section creates a *method* embedded inside the
current component. Methods resemble subcomponents in terms of naming,
contents, and scope. However, while subcomponents can only be seen from
the parent component, methods are meant to be called from other
components.
There are two ways to call a method. First, via a path of the form
"comp:method":
<& /foo/bar:method1 &>
$m->comp('/foo/bar:method1');
Second, via the call_method component method:
my $comp = $m->fetch_comp('/foo/bar');
...
$comp->call_method('method1');
Methods are commonly used in conjunction with autohandlers to make
templates more flexible. See Object-Oriented Techniques for more
information.
You cannot create a subcomponent and method with the same name. This is
mostly to prevent obfuscation and accidental errors.
## FLAGS AND ATTRIBUTES
The "<%flags>" and "<%attr>" sections consist of key/value pairs, one
per line, joined by '=>'. In each pair, the key must be any valid Perl
"bareword identifier" (made of letters, numbers, and the underscore
character), and the value may be any scalar value, including references.
An optional comment may follow each line.
<%flags>
Use this section to set official Mason flags that affect the current
component's behavior.
Currently there is only one flag, "inherit", which specifies the
component's *parent* in the form of a relative or absolute component
path. A component inherits methods and attributes from its parent; see
Object-Oriented Techniques for examples.
<%flags>
inherit=>'/site_handler'
<%attr>
Use this section to assign static key/value attributes that can be
queried from other components.
<%attr>
color => 'blue'
fonts => [qw(arial geneva helvetica)]
To query an attribute of a component, use the "attr" method:
my $color = $comp->attr('color')
where $comp is a component object.
Mason evaluates attribute values once when loading the component. This
makes them faster but less flexible than methods.
## FILTERING
This section describes several ways to apply filtering functions over
the results of the current component. By separating out and hiding a
filter that, say, changes HTML in a complex way, we allow
non-programmers to work in a cleaner HTML environment.
<%filter> section
The "<%filter>" section allows you to arbitrarily filter the output of
the current component. Upon entry to this code, $_ contains the
component output, and you are expected to modify it in place. The code
has access to component arguments and can invoke subroutines, call other
components, etc.
This simple filter converts the component output to UPPERCASE:
<%filter>
tr/a-z/A-Z/
The following navigation bar uses a filter to "unlink" and highlight the
item corresponding to the current page:
Home | Products |
Background | Financials |
Tech Support | Contact Us
<%filter>
my $uri = $r->uri;
s{(.*?)} {$1}i;
This allows a designer to code such a navigation bar intuitively without
"if" statements surrounding each link! Note that the regular expression
need not be very robust as long as you have control over what will
appear in the body.
A filter block does not have access to variables declared in a
component's "<%init>" section, though variables declared in the
"<%args>", "<%once>" or "<%shared>" blocks are usable in a filter.
It should be noted that a filter cannot rely on receiving all of a
component's output at once, and so may be called multiple times with
different chunks of output. This can happen if autoflush is on, or if a
filter-containing component, or the components it calls, call the
"$m->flush_buffer()" method.
You should never call Perl's "return()" function inside a filter
section, or you will not see any output at all.
You can use Component Calls with Content if you want to filter specific
parts of a component rather than the entire component.
## COMMENT MARKERS
There are several ways to place comments in components, i.e. arbitrary
text that is ignored by the parser.
<%doc>
Text in this section is treated as a comment and ignored. Most useful
for a component's main documentation. One can easily write a program to
sift through a set of components and pull out their "<%doc>" blocks to
form a reference page.
<% # comment... %>
A "<% %>" tag is considered a comment if all of its lines are either
whitespace, or begin with a '#' optionally preceded by whitespace. For
example,
<% # This is a single-line comment %>
<%
# This is a
# multi-line comment
%>
%# comment
Because a line beginning with "%" is treated as Perl, "%#" automatically
works as a comment. However we prefer the "<% # comment %>" form over
"%#", because it stands out a little more as a comment and because it is
more flexible with regards to preceding whitespace.
% if (0) { }
Anything between these two lines
% if (0) {
...
% }
will be skipped by Mason, including component calls. While we don't
recommend this for comments per se, it is a useful notation for
"commenting out" code that you don't want to run.
HTML/XML/... comments
HTML and other markup languages will have their own comment markers, for
example "". Note two important differences with these comments
versus the above comments:
* They will be sent to the client and appear in the source of the
page.
* They do not block component calls and other code from running, so
don't try to use them to comment out code!
## OTHER SYNTAX
<%text>
Text in this section is printed as-is with all Mason syntax ignored.
This is useful, for example, when documenting Mason itself from a
component:
<%text>
% This is an example of a Perl line.
<% This is an example of an expression block. %>
This works for almost everything, but doesn't let you output ""
itself! When all else fails, use "$m->print":
% $m->print('The tags are <%text> and .');
Escaping expressions
Mason has facilities for *escaping* the output from "<% %>" tags, on
either a site-wide or a per-expression basis.
Any "<% %>" expression may be terminated by a '|' and one or more escape
flags (plus arbitrary whitespace), separated by commas:
<% $file_data |h %>
The current valid flags are:
* h
Escape HTML ('<' => '<', etc.) using "[HTML::Entities::encode]()".
Before Perl 5.8.0 this module assumes that text is in the ISO-8859-1
character set; see the next section for how to override this
escaping. After 5.8.0, the encoding assumes that text is in Unicode.
* u
Escape a URL query string (':' => '%3A', etc.) - all but
[a-zA-Z0-9_.-]
* n
This is a special flag indicating that the default escape flags
should *not* be used for this substitution.
The administrator may specify a set of default escape flags via the
default_escape_flags parameter. For example, if the administrator sets
default_escape_flags to "['h']", then all <% %> expressions will
automatically be HTML-escaped. In this case you would use the "n" flag
to turn off HTML-escaping for a specific expression:
<% $html_block |n %>
Multiple escapes can be specified as a comma-separated list:
<% $uri | u, n %>
The old pre-defined escapes, 'h', 'u', and 'n', can be used *without*
commas, so that this is legal:
<% $uri | un %>
However, this only works for these three escapes, and no others. If you
are using user-defined escapes as well, you *must* use a comma:
<% $uri | u, add_session %>
User-defined Escapes
Besides the default escapes mentioned above, it is possible for the user
to define their own escapes or to override the built-in 'h' and 'u'
escapes.
This is done via the Interp object's escape_flags parameter or
set_escape() method. Escape names may be any number of characters as
long as it matches the regex "/^[\w-]+$/". The one exception is that you
cannot override the 'n' flag.
Each escape flag is associated with a subroutine reference. The
subroutine should expect to receive a scalar reference, which should be
manipulated in place. Any return value from this subroutine is ignored.
Escapes can be defined at any time but using an escape that is not
defined will cause an error when executing that component.
A common use for this feature is to override the built-in HTML escaping,
which will not work with non-ISO-8559-1 encodings. If you are using such
an encoding and want to switch the 'h' flag to do escape just the
minimal set of characters ("<", ">", "&", """), put this in your Apache
configuration:
PerlSetVar MasonEscapeFlags "h => \&[HTML::Mason::Escapes::basic_html_escape]"
Or, in a top-level autohandler:
$m->interp->set_escape( h => \&[HTML::Mason::Escapes::basic_html_escape] );
Or you could write your own escape function for a particular encoding:
$ah->interp->set_escape( h => \&my_html_escape );
And of course this can be used for all sorts of other things, like a
naughty words filter for the easily offended:
$interp->set_escape( 'no-naughty' => \&remove_naughty_words );
Manually applying escapes
You can manually apply one or more escapes to text using the Interp
object's "apply_escapes()" method. e.g.
$m->interp->apply_escapes( 'some html content', 'h' );
Backslash at end of line
A backslash (\) at the end of a line suppresses the newline. In HTML
components, this is mostly useful for fixed width areas like ""
tags, since browsers ignore white space for the most part. An example:
foo
% if (1) {
bar
% }
baz
outputs
foo
bar
baz
because of the newlines on lines 2 and 4. (Lines 3 and 5 do not generate
a newline because the entire line is taken by Perl.) To suppress the
newlines:
foo\
% if (1) {
bar\
% }
baz
which prints
foobarbaz
## DATA CACHING
Mason's data caching interface allows components to cache the results of
computation for improved performance. Anything may be cached, from a
block of HTML to a complex data structure.
Each component gets its own private, persistent data cache. Except under
special circumstances, one component does not access another component's
cache. Each cached value may be set to expire at a certain time.
Data caching is implemented on top of one of two external caching APIs:
"[Cache::Cache]", which is stable but has not changed in years, or "CHI",
which has picked up where "[Cache::Cache]" has left off and is actively
maintained. You control which one Mason uses with the data_cache_api
parameter. "[Cache::Cache]" is the default for backward compatibility
reasons, but we recommend "CHI" for anyone doing serious caching. The
APIs are very similar for Mason users, so that most of the information
below applies to both; any differences are noted.
Basic Usage
The "$m->cache" method returns a cache object representing the cache for
this component. Here's the typical usage of "$m->cache":
my $result = $m->cache->get('key');
if (!defined($result)) {
... compute $result ...
$m->cache->set('key', $result);
}
"$m->cache->get" attempts to retrieve this component's cache value. If
the value is available it is placed in $result. If the value is not
available, $result is computed and stored in the cache by
"$m->cache->set".
Multiple Keys/Values
A cache can store multiple key/value pairs. A value can be anything
serializable by "Storable", from a simple scalar to an arbitrary complex
list or hash reference:
$m->cache->set(name => $string);
$m->cache->set(friends => \@list);
$m->cache->set(map => \%hash);
You can fetch all the keys in a cache with
my @idents = $m->cache->get_keys;
It should be noted that Mason reserves all keys beginning with "__mason"
for its own use.
Expiration
You can pass an optional third argument to "$m->cache->set" indicating
when the item should expire:
$m->cache->set('name1', $string1, '5 min'); # Expire in 5 minutes
$m->cache->set('name2', $string2, '3h'); # Expire in 3 hours
To change the expiration time for a piece of data, call "set" again with
the new expiration. To expire an item immediately, use
"$m->cache->remove".
You can also specify an expiration condition when you fetch the item,
using the *expire_if* option:
my $result = $m->cache->get('key',
expire_if=>sub { $_[0]->get_created_at < (stat($file))[9] });
*expire_if* takes an anonymous subroutine, which is called with the
cache object as its only parameter. If the subroutine returns a true
value, the item is expired. In the example above, we expire the item
whenever a certain file changes.
Finally, you can expire a cache item from an external script; see
Accessing a Cache Externally below.
Avoiding Concurrent Recomputation
The code shown in "Basic Usage" above,
my $result = $m->cache->get('key');
if (!defined($result)) {
... compute $result ...
$m->cache->set('key', $result);
}
can suffer from a kind of race condition for caches that are accessed
frequently and take a long time to recompute.
Suppose that a particular cache value is accessed five times a second
and takes three seconds to recompute. When the cache expires, the first
process comes in, sees that it is expired, and starts to recompute the
value. The second process comes in and does the same thing. This
sequence continues until the first process finishes and stores the new
value. On average, the value will be recomputed and written to the cache
15 times!
One solution is the *busy_lock* flag:
my $result = $m->cache->get('key', busy_lock=>'30 sec');
In this case, when the value cannot be retrieved, "get()" sets the
expiration time of the value 30 seconds in the future before returning
"undef". This tells the first process to compute the new value while
causing subsequent processes to use the old value for 30 seconds.
Should the 30 seconds expire before the first process is done, a second
process will start computing the new value while setting the expiration
time yet another 30 seconds in the future, and so on.
The disadvantage of this solution is that multiple writes to the cache
will be performed for each "set()".
Another solution, available only if you are using "CHI", is
"expires_variance" which will create a variable time window during which
expiration may occur. See the "CHI" documentation for details.
Caching All Output
Occasionally you will need to cache the complete output of a component.
For this purpose, Mason offers the "$m->cache_self" method. This method
causes Mason to check to see if this component has already been run and
its output cached. If this is the case, this output is simply sent as
output. Otherwise, the component run normally and its output and return
value cached.
It is typically used right at the top of an "<%init>" section:
<%init>
return if $m->cache_self(key => 'fookey', expires_in => '3 hours',
... ...);
... ...
A full list of parameters and examples are available in the cache_self
section of the Request manual.
Cache Object
"$m->cache->get_object" returns a "[Cache::Object]" or "[CHI::CacheObject]"
associated with a particular key. You can use this to retrieve useful
meta-data:
my $co = $m->cache->get_object('name1');
$co->get_created_at(); # when was object stored in cache
$co->get_expires_at(); # when does object expire
Choosing a Cache Subclass - with [Cache::Cache]
The "[Cache::Cache]" API is implemented by a variety of backend
subclasses. For example, "FileCache" implements the interface with a set
of directories and files, "MemoryCache" implements the interface in
process memory, and "SharedMemoryCache" implements the interface in
shared memory.
By default "$m->cache" uses "FileCache", but you can override this with
the *cache_class* keyword. The value must be the name of a
"[Cache::Cache]" subclass; the prefix "Cache::" need not be included. For
example:
my $result = $m->cache(cache_class => 'MemoryCache')->get('key');
$m->cache(cache_class => 'MemoryCache')->set(key => $result);
You can even specify different subclasses for different keys in the same
component. Just make sure the correct value is passed to all calls to
"$m->cache"; Mason does not remember which subclass you have used for a
given component or key.
The administrator can set the default cache subclass used by all
components with the data_cache_defaults parameter.
Choosing a Cache Subclass - with CHI
The "CHI" API is implemented by a variety of drivers, for example
"[CHI::Driver::File]", "[CHI::Driver::FastMmap]", and
"[CHI::Driver::Memcached]".
"[CHI::Driver::File]" is the default, but you can override this with the
*driver* keyword. The value must be the name of a "[CHI::Driver]"
subclass; the prefix "[CHI::Driver]::" need not be included. For example:
my $cache = $m->cache(driver => 'Memcached', servers => [ ... ]);
my $result = $cache->get('key');
$cache->set(key => $result);
You can even specify different subclasses for different keys in the same
component. Just make sure the correct value is passed to all calls to
"$m->cache"; Mason does not remember which subclass you have used for a
given component or key.
The administrator can set the default cache subclass used by all
components with the data_cache_defaults parameter.
Accessing a Cache Externally
To access a component's cache from outside the component (e.g. in an
external Perl script), you'll need have the following information:
* the namespace associated with the component. For "[Cache::Cache]", the
function "[HTML::Mason::Utils::data_cache_namespace]", given a
component id (usually just the component path), returns the
namespace. For "CHI", the component id/path itself is the namespace.
* the cache_root, for file-based caches only. Defaults to the "cache"
subdirectory under the Mason data directory.
Given this information you can get a handle on the component's cache.
For example, the following code removes a cache item for component
/foo/bar, assuming the data directory is /usr/local/www/mason and you
are using the default file backend:
use [HTML::Mason::Utils] qw(data_cache_namespace);
# With [Cache::Cache]
my $cache = new [Cache::FileCache]
( { namespace => data_cache_namespace("/foo/bar"),
cache_root => "/usr/local/www/mason/cache" } );
# With CHI
my $cache = CHI->new
( driver => 'File',
namespace => "/foo/bar",
cache_root => "/usr/local/www/mason/cache" );
# Remove one key
$cache->remove('key1');
# Remove all keys
$cache->clear;
Mason 1.0x Cache API
For users upgrading from 1.0x and earlier, any existing $m->cache code
will be incompatible with the new API. However, if you wish to continue
using the 1.0x cache API for a while, you (or your administrator) can
set data_cache_api to '1.0'. All of the $m->cache options with the
exception of "tie_class" should be supported.
The "access_data_cache" function is no longer available; this will need
to be converted to use "[Cache::Cache]" directly, as described in the
previous section.
## WEB-SPECIFIC FEATURES
Sending HTTP Headers
Mason automatically sends HTTP headers via "$r->send_http_header" but it
will not send headers if they've already been sent manually.
To determine the exact header behavior on your system, you need to know
whether your server's default is to have autoflush on or off. Your
administrator should have this information. If your administrator
doesn't know then it is probably off, the default.
With autoflush off the header situation is extremely simple: Mason waits
until the very end of the request to send headers. Any component can
modify or augment the headers.
With autoflush on the header situation is more complex. Mason will send
headers just before sending the first output. This means that if you
want to affect the headers with autoflush on, you must do so before any
component sends any output. Generally this takes place in an "<%init>"
section.
For example, the following top-level component calls another component
to see whether the user has a cookie; if not, it inserts a new cookie
into the header.
<%init>
my $cookie = $m->comp('/shared/get_user_cookie');
if (!$cookie) {
$cookie = new [CGI::Cookie] (...);
$r->header_out('Set-cookie' => $cookie);
}
...
With autoflush off this code will always work. Turn autoflush on and
this code will only work as long as /shared/get_user_cookie doesn't
output anything (given its functional nature, it shouldn't).
The administrator can turn off automatic header sending via the
auto_send_headers parameter. You can also turn it off on individual
pages with
$m->[auto_send_headers(0)];
Returning HTTP Status
The value returned from the top-most component becomes the status code
of the request. If no value is explicitly returned, it defaults to OK
(0).
Simply returning an error status (such as 404) from the top-most
component has two problems in practice. First, the decision to return an
error status often resides further down in the component stack. Second,
you may have generated some content by the time this decision is made.
(Both of these are more likely to be true when using autohandlers.)
Thus the safer way to generate an error status is
$m->clear_buffer;
$m->abort($status);
"$m->abort" bypasses the component stack and ensures that $status is
returned from the top-most component. It works by throwing an exception.
If you wrapped this code (directly or indirectly) in an eval, you must
take care to rethrow the exception, or the status will not make it out:
eval { $m->comp('...') };
if (my $err = $@) {
if ($m->aborted) {
die $err;
} else {
# deal with non-abort exceptions
}
}
Filters and $m->abort
A filter section will still be called after a component aborts with
"$m->abort". You can always check "$m->aborted" in your "<%filter>"
block if you don't want to run the filter after an abort.
<%filter>
unless ( $m->aborted ) {
$_ .= ' filter stuff';
}
External Redirects
Because it is so commonly needed, Mason 1.1x and on provides an external
redirect method:
$m->redirect($url); # Redirects with 302 status
This method uses the clear_buffer/abort technique mentioned above, so
the same warnings apply regarding evals.
Also, if you generate any output *after* calling "$m->redirect", then
this output will be sent, and will break the redirect. For example:
% eval { $m->comp('redirect', ...) };
% die $@ if $@;
The blank line between the two Perl lines is new output generated after
the redirect. Either remove it or call "$m->clear_buffer" immediately
before calling "die()".
Internal Redirects
There are two ways to perform redirects that are invisible to the
client.
First, you can use a Mason subrequest (see "Subrequests"). This only
works if you are redirecting to another Mason page.
Second, you can use Apache's internal_redirect method, which works
whether or not the new URL will be handled by Mason. Use it this way:
$r->internal_redirect($url);
$m->[auto_send_headers(0)];
$m->clear_buffer;
$m->abort;
The last three lines prevent the original request from accidentally
generating extra headers or content.
## USING THE PERL DEBUGGER
You can use the perl debugger in conjunction with a live mod_perl/Mason
server with the help of [Apache::DB], available from CPAN. Refer to the
[Apache::DB] documentation for details.
The only tricky thing about debugging Mason pages is that components are
implemented by anonymous subroutines, which are not easily
breakpoint'able. To remedy this, Mason calls the dummy subroutine
"debug_hook" at the beginning of each component. You can breakpoint this
subroutine like so:
b [HTML::Mason::Request::debug_hook]
debug_hook is called with two parameters: the current Request object and
the full component path. Thus you can breakpoint specific components
using a conditional on $_[1]:
b [HTML::Mason::Request::debug_hook] $_[1] =~ /component name/
You can avoid all that typing by adding the following to your ~/.perldb
file:
# Perl debugger aliases for Mason
$[DB::alias]{mb} = 's/^mb\b/b [HTML::Mason::Request::debug_hook]/';
which reduces the previous examples to just:
mb
mb $_[1] =~ /component name/
Mason normally inserts '#line' directives into compiled components so
that line numbers are reported relative to the source file. Depending on
your task, this can be a help or a hindrance when using the debugger.
The administrator can turn off '#line' directives with the
use_source_line_numbers parameter.
## LOGGING
Mason uses "[Log::Any]" to log various events, such as the start and end
of each request and each component call. You can also log to "[Log::Any]"
from a component with the "$m->log" method. e.g.
$m->log->error("Something bad happened!");
$m->log->debugf("Arguments for '%s' were '%s'", $func, \%args)
if $m->log->is_debug;
See "[Log::Any::Adapter]" for how to direct these logs to an output of
your choice.
## OBJECT-ORIENTED TECHNIQUES
Earlier you learned how to assign a common template to an entire
hierarchy of pages using *autohandlers*. The basic template looks like:
header HTML
% $m->call_next;
footer HTML
However, sometimes you'll want a more flexible template that adjusts to
the requested page. You might want to allow each page or subsection to
specify a title, background color, or logo image while leaving the rest
of the template intact. You might want some pages or subsections to use
a different template, or to ignore templates entirely.
These issues can be addressed with the object-oriented style primitives
introduced in Mason 0.85.
Note: we use the term object-oriented loosely. Mason borrows concepts
like inheritance, methods, and attributes from object methodology but
implements them in a shallow way to solve a particular set of problems.
Future redesigns may incorporate a deeper object architecture if the
current prototype proves successful.
Determining inheritance
Every component may have a single *parent*. The default parent is a
component named "autohandler" in the closest parent directory. This rule
applies to autohandlers too: an autohandler may not have itself as a
parent but may have an autohandler further up the tree as its parent.
You can use the "inherit" flag to override a component's parent:
<%flags>
inherit => '/foo/bar'
If you specify undef as the parent, then the component inherits from no
one. This is how to suppress templates.
Currently there is no way to specify a parent dynamically at run-time,
or to specify multiple parents.
Content wrapping
At page execution time, Mason builds a chain of components from the
called component, its parent, its parent's parent, and so on. Execution
begins with the top-most component; calling "$m->call_next" passes
control to the next component in the chain. This is the familiar
autohandler "wrapping" behavior, generalized for any number of
arbitrarily named templates.
Accessing methods and attributes
A template can access methods and/or attributes of the requested page.
First, use "$m->request_comp" to get a handle on the appropriate
component:
my $self = $m->request_comp;
$self now refers to the component corresponding to the requested page
(the component at the end of the chain).
To access a method for the page, use "call_method":
$self->call_method('header');
This looks for a method named 'header' in the page component. If no such
method exists, the chain of parents is searched upwards, until
ultimately a "method not found" error occurs. Use 'method_exists' to
avoid this error for questionable method calls:
if ($self->method_exists('header')) { ...
The component returned by the "$m->request_comp" method never changes
during request execution. In contrast, the component returned by
"$m->base_comp" may change several times during request execution.
When execution starts, the base component is the same as the requested
component. Whenever a component call is executed, the base component may
become the component that was called. The base component will change for
all component calls except in the following cases:
* A component is called via its component object rather than its path,
for example:
<& $m->fetch_comp('/some/comp'), foo => 1 &>
* A subcomponent (defined with "<%def>") is called.
* A method is called via the use of "SELF:", "PARENT:", or "REQUEST:".
These are covered in more detail below.
In all other cases, the base component is the called component or the
called component's owner component if that called component is a method.
As hinted at above, Mason provides a shortcut syntax for method calls.
If a component call path starts with "SELF:", then Mason will start
looking for the method (the portion of the call after "SELF:"), in the
base component.
<& SELF:header &>
$m->comp('SELF:header')
If the call path starts with "PARENT:", then Mason will start looking in
the current component's parent for the named method.
<& PARENT:header &>
$m->comp('PARENT:header')
In the context of a component path, PARENT is shorthand for
"$m->current_comp->parent".
If the call path begins with "REQUEST:", then Mason looks for the method
in the requested component. REQUEST is shorthand for "$m->request_comp".
The rules for attributes are similar. To access an attribute for the
page, use "attr":
my $color = $self->attr('color')
This looks for an attribute named 'color' in the $self component. If no
such attribute exists, the chain of parents is searched upwards, until
ultimately an "attribute not found" error occurs. Use "attr_exists" or
"attr_if_exist" to avoid this error for questionable attributes:
if ($self->attr_exists('color')) { ...
my $color = $self->attr_if_exists('color'); # if it doesn't exist $color is undef
Sharing data
A component's main body and its methods occupy separate lexical scopes.
Variables declared, say, in the "<%init>" section of the main component
cannot be seen from methods.
To share variables, declare them either in the "<%once>" or "<%shared>"
section. Both sections have an all-inclusive scope. The "<%once>"
section runs once when the component loads; its variables are persistent
for the lifetime of the component. The "<%shared>" section runs once per
request (when needed), just before any code in the component runs; its
variables last only til the end of the request.
In the following example, various sections of code require information
about the logged-in user. We use a "<%shared>" section to fetch these in
a single request.
<%attr>
title=>sub { "Account for $full_name" }
<%method lefttoc>
<% $full_name %>
(Log out)
...
Welcome, <% $fname %>. Here are your options:
<%shared>
my $dbh = [DBI::connect] ...;
my $user = $r->connection->user;
my $sth = $dbh->prepare("select lname,fname, from users where user_id = ?");
$sth->execute($user);
my ($lname, $fname) = $sth->fetchrow_array;
my $full_name = "$first $last";
"<%shared>" presents a good alternative to "<%init>" when data is needed
across multiple scopes. Outside these situations, "<%init>" is preferred
for its slightly greater speed and predictable execution model.
Example
Let's say we have three components:
/autohandler
/products/autohandler
/products/index.html
and that a request comes in for /products/index.html.
/autohandler contains a general template for the site, referring to a
number of standard methods and attributes for each page:
<& SELF:title &>
<& SELF:header &>
% $m->call_next;
<& SELF:footer &>
<%init>
my $self = $m->base_comp;
...
<%attr>
body_style => 'standard'
<%method title>
McGuffey Inc.
<%method header>
<& SELF:title &>
<%method footer>
Notice how we provide defaults for each method and attribute, even if
blank.
/products/autohandler overrides some attributes and methods for the
/products section of the site.
<%attr>
body_style => 'plain'
<%method title>
McGuffey Inc.: Products
% $m->call_next;
Note that this component, though it only defines attributes and methods,
must call "$m->call_next" if it wants the rest of the chain to run.
/products/index.html might override a few attributes, but mainly
provides a primary section for the body.
## COMMON TRAPS
Do not call $r->content or "new CGI"
Mason calls "$r->content" itself to read request input, emptying the
input buffer and leaving a trap for the unwary: subsequent calls to
"$r->content" hang the server. This is a mod_perl "feature" that may
be fixed in an upcoming release.
For the same reason you should not create a CGI object like
my $query = new CGI;
when handling a POST; the CGI module will try to reread request
input and hang. Instead, create an empty object:
my $query = new CGI ("");
such an object can still be used for all of CGI's useful HTML output
functions. Or, if you really want to use CGI's input functions,
initialize the object from %ARGS:
my $query = new CGI (\%ARGS);
## MASON AND SOURCE FILTERS
Modules which work as source filters, such as "Switch.pm", will only
work when you are using object files. This is because of how source
filters are implemented, and cannot be changed by the Mason authors.