| <% $h->{foo} %> | <% $h->{bar} %> | <% $h->{baz} %> | % }
<% $body %> <& footer &> <%init> my $arg = $m->dhandler_arg; # get rest of path my ($section,$story) = split("/",$arg); # split out pieces my $sth = $DBH->prepare ("SELECT headline,body FROM news WHERE section='$section' AND story='$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 `Admin' in this node. A component or dhandler that does not want to handle a particular request may defer control to the next dhandler by calling `$m->decline'. The administrator can customize the file name used for dhandlers, or turn off dhandlers entirely, with the `Interp' in this node Interp 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:
<% $body %>
<%init>
# Fetch article from database
my $dbh = DBI::connect ...;
my $sth = $dbh->prepare("select * from articles where id = $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.
Technically a <%cleanup> block is equivalent to a <%perl> block at the
end of the component. Since a component corresponds a subroutine block,
and since Perl is so darned good at cleaning up stuff at the end of blocks,
<%cleanup> sections are rarely needed.
<%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.
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 from this section.
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 the following trick to
initialize such variables in the <%init> section:
<%once>
my $dbh; # declare but don't assign
...
<%init>
if ($m->current_comp->first_time) {
$dbh = DBI::connect ...
}
...
<%shared>
---------
As with `<%once>', variables declared in this section can be seen in all
of a component's code: the main component, subcomponents, and methods.
However, the code runs once per request (whenever the component is used)
and its variables last only til the end of the request.
Useful for initializing variables needed in, say, the main body and one
more subcomponents or methods. See `Devel' in this node for an example of
usage.
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. `<%init>' offers more a predictable execution time.
Any component with a `<%shared>' section incurs an extra performance
penalty, because (as currently implemented) 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 as well.
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 `[A-Za-z0-9._-]'. 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. The author prefers 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:
tags,
since browsers ignore white space for the most part. An example:
foo
%if ($b == 2) {
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 ($b == 2) {
bar\
%}
baz
which prints
foobarbaz
The backslash has no special meaning outside this context. In
particular, you cannot use it to escape a newline before a plain text line.
DATA CACHING
============
Mason's `$m->cache' and `$m->cache_self' methods let components save
and retrieve the results of computation for improved performance.
Anything may be cached, from a block of HTML to a complex data structure.
Each component gets a private data cache. Except under special
circumstances, one component does not access another component's cache.
Each cached value may be set to expire under certain conditions or at a
certain time.
To use data caching, your Mason installation must be configured with a
good DBM package like Berkeley DB (DB_File) or GDBM. See **Note
HTML/Mason/Admin: HTML/Mason/Admin,* for more information.
Basic Usage
-----------
Here's the typical usage of `$m->cache':
my $result = $m->cache(action=>'retrieve');
if (!defined($result)) {
... compute $result> ...
$m->cache(action=>'store', value=>$result);
}
The first `$m->cache' call 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 the second
`$m->cache' call.
The default action for `$m->cache' is 'retrieve', so the first line can
be written as
my $result = $m->cache;
Multiple Keys/Values
--------------------
A cache file can store multiple keys and values. A value can be a
scalar, list reference, or hash reference:
$m->cache(action=>'store',key=>'name',value=>$name);
$m->cache(action=>'store',key=>'friends',value=>\@lst);
$m->cache(action=>'store',key=>'map',value=>\%hsh);
The key defaults to 'main' when unspecified, as in the first example
above.
Mason uses the *MLDBM* package to store and retrieve from its cache
files, meaning that Mason can cache arbitrarily deep data structures
composed of lists, hashes, and simple scalars.
Expiration
----------
Typical cache items have a useful lifetime after which they must
expire. Mason supports three types of expiration:
By Time
(e.g. the item expires in an hour, or at midnight). To expire an item
by time, pass one of these options to the 'store' action.
*expire_at*: takes an absolute expiration time, in Perl time() format
(number of seconds since the epoch)
*expire_in*: takes a relative expiration time of the form
"", where is a positive number and is one of
seconds, minutes, hours, days, weeks, months, years, or any reasonable
abbreviation thereof (m=month, min=minute). E.g. "10min", "1hour".
*expire_next*: takes a string, either 'hour' or 'day'. It indicates
an expiration time at the top of the next hour or day.
Examples:
$m->cache(action=>'store', expire_in=>'2 hours');
$m->cache(action=>'store', expire_next=>'hour');
By Condition
(e.g. the item expires if a certain file or database table changes).
To expire an item based on events rather than current time, pass the
'expire_if' option to the 'retrieve' action.
*expire_if*: calls a given anonymous subroutine and expires if the
subroutine returns a non-zero value. The subroutine is called with one
parameter, the time when the cache value was last written.
Example:
# expire the cache if 'myfile' is newer
$m->cache(action => 'retrieve',
expire_if => sub { (stat 'myfile')[9] > shift });
By Explicit Action
(e.g. a shell command or web interface is responsible for explicitly
expiring the item) To expire an item from a Perl script, for any
component, use *access_data_cache*. It takes the same arguments as
`$m->cache' plus one additional argument, cache_file. See the
administration manual for details on where cache files are stored and
how they are named.
use HTML::Mason::Utils 'access_data_cache';
access_data_cache (cache_file=>'/usr/local/mason/cache/foo+2fbar',
action=>'expire' [, key=>'fookey']);
The 'expire' action can also take multiple keys (as a list reference);
this can be used in conjunction with the 'keys' action to expire all
keys matching a particular pattern.
use HTML::Mason::Utils 'access_data_cache';
my @keys = access_data_cache (cache_file=>'/usr/local/mason/cache/foo+2fbar',
action=>'keys');
access_data_cache (cache_file=>'/usr/local/mason/cache/foo+2fbar',
action=>'expire', key=>[grep(/^sales/,@keys)]);
Busy Locks
----------
The code shown in "Basic Usage" above,
my $result = $m->cache(action=>'retrieve');
if (!defined($result)) {
... compute $result ...
$m->cache(action=>'store', value=>$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!
The solution here is to have the first process notify the others that
it has started recomputing. This can be accomplished with the busy_lock
flag:
my $result = $m->cache(action=>'retrieve',busy_lock=>'10sec',...);
With this flag, the first process sets a lock in the cache that
effectively says "I'm busy recomputing his value, don't bother."
Subsequent processes see the lock and return the old value. The lock is
good for 10 seconds (in this case) and is ignored after that. Thus the
time value you pass to busy_lock indicates how long you're willing to
allow this component to use an expired cache value.
Would some of your caches benefit from busy locks? One way to find out
is to turn on cache logging in the Mason system logs. If you see large
clusters of writes to the same cache in a short time span, then you might
want to use busy locks when writing to that cache.
Keeping In Memory
-----------------
The keep_in_memory flag indicates that the cache value should be kept
in memory after it is stored or retrieved. Since every child process will
store its own copy, this flag should be used only for small, frequently
retrieved cache values. If used, this flag should be passed to both the
store and retrieve commands.
Caching All Output
------------------
Occasionally you will need to cache the complete output of a component.
One way to accomplish this is to replace the component with a placeholder
that simply calls the component, then caches and prints the result. For
example, if the component were named "foo", we might rename it to
"foo_main" and put this component in its place:
<% $foo_out %>
<%init>
my $foo_out;
if (!defined ($foo_out = $m->cache)) {
$m->comp('foo_main', STORE=>\$foo_out);
$m->cache(action=>'store',
expire_in=>'3 hours', value=>$foo_out);
}
This works, but is cumbersome. Mason offers a better shortcut: the
`$m->cache_self' command that lets a component cache it's own output and
eliminates the need for a dummy component. It is typically used right at
the top of a `<%init%>' section:
<%init>
return if $m->cache_self(expire_in=>'3 hours'[, key=>'fookey']);
... ...
`$m->cache_self' is built on top of `$m->cache', so it inherits all the
expiration options described earlier. `$m->cache_self' can also cache a
component's return value; see the reference for details.
Guarantees (or lack thereof)
----------------------------
Mason will make a best effort to cache data until it expires, but will
not guarantee it. The data cache is not a permanent reliable store in
itself; you should not place in the cache critical data (e.g. user session
information) that cannot be regenerated from another source such as a
database. You should write your code as if the cache might disappear at
any time. In particular,
o If the 'store' action cannot get a write lock on the cache, it simply
fails quietly.
o If the 'retrieve' action cannot get a shared lock on the cache, it
simply fails quietly. (This is much more rare.)
o Your Mason administrator will be required to remove cache files
periodically when they get too large; this can happen any time.
On the other hand, expiration in its various forms is guaranteed,
because Mason does not want you to rely on bad data to generate your
content. If you use the 'expire' action and Mason cannot get a write lock,
it will repeat the attempt several times and finally die with an error.
SENDING HTTP HEADERS
====================
Mason automatically sends HTTP headers via $r->send_http_header. It
tries to delay sending headers till the last possible moment, to give
components a chance to affect headers (using $r->header_out,
$r->content_type, etc.) It won't 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 out_mode is 'batch' (meaning all output is buffered
until the end) or 'stream' (all output is sent immediately). Your
administrator should have this information. If your administrator doesn't
know then it is probably 'batch', the default.
In batch mode 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.
In stream mode the header situation is more complex. Mason will send
headers just before sending the first non-whitespace output. Any initial
whitespace output is buffered up until after headers are sent. This means
that if you want to affect the headers in stream mode, you must do so
before any component sends non-whitespace 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->headers_out->add('Set-cookie' => $cookie);
}
...
In batch mode this code will always work. In stream mode this code
will work as long as *get_user_cookie* doesn't output anything besides
whitespace (and given its functional nature, it shouldn't).
The administrator can turn off automatic header sending via the
`ApacheHandler' in this node ApacheHandler parameter.
Note to pre-0.8 users: the mc_suppress_http_header command is no longer
needed. For backwards compatibility, mc_suppress_http_header is still
defined but does nothing.
(Rationale: By the nature of HTTP headers mc_suppress_http_header was
only useful up until the first bytes of content were sent. Since Mason now
waits that long to send headers anyway, there is never any justification
for suppressing headers.)
USING THE PERL DEBUGGER
=======================
The Perl debugger is an indispensable tool for identifying and fixing
bugs in Perl programs. Unfortunately, in a mod_perl environment one is
normally unable to use the debugger since programs are run from a browser.
Mason removes this limitation by optionally creating a *debug file* for
each page request, allowing the request to be replayed from the command
line or Perl debugger.
Note: in early 1999 a new module, Apache::DB, was released that makes
it substantially easier to use the Perl debugger directly in conjunction
with a real Apache server. Since this mechanism is still new, we continue
to support Mason debug files, and there may be reasons to prefer Mason's
method (e.g. no need to start another Apache server). However we
acknowledge that Apache::DB may eventually eliminate the need for debug
files. For now we encourage you to try both methods and see which one
works best.
Using debug files
-----------------
Here is a typical sequence for debugging a Mason page:
1. Find the debug file: When Mason is running in debug mode, requests
generate "debug files", cycling through filenames "1" through "20".
To find a request's debug file, simply do a "View Source" in your
browser after the request and look for a comment like this at the
very top:
2. Run the debug file: Debug files basically contain two things: a copy
of the entire HTTP request (serialized with Data::Dumper), and all
the plumbing needed to route that request through Mason. In other
words, if you simply run the debug file like this:
perl /usr/local/mason/debug/anon/3
you should see the HTTP headers and content that the component would
normally send to the browser.
3. Debug the debug file: Now you merely add a -d option to run the debug
file in Perl's debugger - at which point you have to deal the problem
of anonymous subroutines.
Mason compiles components down to anonymous subroutines which are not
easily breakpoint'able (Perl prefers line numbers or named
subroutines). Therefore, immediately before each component call,
Mason calls a nonce subroutine called `debug_hook' just so you can
breakpoint it like this:
b HTML::Mason::Request::debug_hook
debug_hook is called with the component name as the second parameter
so that you can also 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/
The use of debug files opens lots of other debugging options. For
instance, you can read a debug file into the Emacs editor, with its nifty
interface to Perl's debugger. This allows you to set break points
visually or (in trace mode) watch a cursor bounce through your code in
single-step or continue mode.
Specifying when to create debug files
-------------------------------------
Details about configuring debug mode can be found in **Note
HTML/Mason/Admin: HTML/Mason/Admin,*. In particular, the administrator
must decide which of three debugging modes to activate:
never (no debug files)
always (create debug files for each request)
error (only generate a debug file when an error occurs)
How debug files work
--------------------
To create a debug file, Mason calls almost every one of the mod_perl
API methods (`$r->xxx'), trapping its result in a hash. That hash is then
serialized by Data::Dumper and output into a new debug file along with
some surrounding code.
When the debug file is executed, a new object is created of the class
"HTML::Mason::FakeApache", passing the saved hash as initialization. The
FakeApache object acts as a fake $r, responding to each method by getting
or setting data in its hash. For most purposes it is indistinguishable
from the original $r except that print methods go to standard output. The
debug file then executes your `handler()' function with the simulated $r.
When debug files don't work
---------------------------
The vast majority of mod_perl API methods are simple get/set functions
(e.g. `$r->uri', `$r->content_type') which are easy to simulate. Many
pages only make use of these methods and can be successfully simulated in
debug mode.
However, a few methods perform tasks requiring the presence of a true
Apache server. These cannot be properly simulated. Some, such as
log_error and `send_cgi_header', are generally tangential to the debugging
effort; for these Mason simply returns without doing anything and hopes
for the best. Others, such as `internal_redirect' and `lookup_uri',
perform such integral functions that they cannot be ignored, and for these
FakeApache aborts with an error. This category includes any method call
expected to return an Apache::Table object.
In addition, FakeApache is playing something of a catch-up game: every
time a new mod_perl release comes out with new API methods, those methods
will not be recognized by FakeApache until it is updated in the next Mason
release.
The combination of these problems and the existence of the new
Apache::DB package may eventually lead us to stop further work on
FakeApache/debug files. For now, though, we'll continue to support them
as best we can.
USING THE PERL PROFILER
=======================
Debug files, mentioned in the previous section, can be used in
conjunction with Devel::DProf to profile a web request.
To use profiling, pass the -p flag to the debug file:
% ./3 -p
This executes the debug file under Devel::DProf and, for convenience,
runs dprofpp. If you wish you can rerun dprofpp with your choice of
options.
Because components are implemented as anonymous subroutines, any time
spent in components would normally be reported under an unreadable label
like CODE(0xb6cbc). To remedy this, the -p flag automatically adjusts the
tmon.out file so that components are reported by their component paths.
Much of the time spent in a typical debug file is initialization, such
as loading Mason and other Perl modules. The effects of initialization
can swamp profile results and obscure the time actually spent in
components. One remedy is to run multiple iterations of the request inside
the debug file, thus reducing the influence of initialization time. Pass
the number of desired iterations via the -r flag:
% ./3 -p -r20
Currently there are no special provisions for other profiling modules
such as Devel::SmallProf. You can try simply:
% perl -d:SmallProf ./3 -r20
However, this crashes on our Unix system - apparently some bad
interaction between Mason and SmallProf - so it is unsupported for now.
THE PREVIEWER
=============
Mason comes with a web-based debugging utility that lets you test your
components by throwing fake requests at them. Adjustable parameters
include: UserAgent, Time, HTTP Referer, O/S and so on. For example,
imagine a component whose color scheme is supposed to change each morning,
noon, and night. Using the Previewer, it would be simple to set the
perceived time forward 1,5 or 8 hours to test the component at various
times of day.
The Previewer also provides a debug trace of a page, showing all
components being called and indicating the portion of HTML each component
is responsible for. For pages constructed from more than a few components,
these traces are quite useful for finding the component that is outputting
a particular piece of HTML.
Your administrator will give you the main Previewer URL, and a set of
preview ports that you will use to view your site under various
conditions. For the purpose of this discussion we'll assume the Previewer
is up and working, that the Previewer URL is
http://www.yoursite.com/preview, and the preview ports are 3001 to 3005.
Take a look at the main Previewer page. The top part contains the most
frequently used options, such as time and display mode. The middle part
contains a table of your saved configurations; if this is your first time
using the Previewer, it will be empty. The bottom part contains less
frequently used options, such as setting the user agent and referer.
Try clicking "Save". This will save the displayed settings under the
chosen preview port, say 3001, and redraw the page. Under "Saved Port
Settings", you should see a single row showing this configuration. Your
configurations are saved permanently in a file. If a username/password is
required to access the Previewer, then each user has his/her own
configuration file.
The "View" button should display your site's home page. If not, then
the Previewer may not be set up correctly; contact your administrator or
see the Administrator's Guide.
Go back to the main Previewer page, change the display mode from "HTML"
to "debug", change the preview port to 3002, and click "Save" again. You
should now see a second saved configuration.
Click "View". This time instead of seeing the home page as HTML,
you'll get a debug trace with several sections. The first section shows a
numbered hierarchy of components used to generate this page. The second
section is the HTML source, with each line annotated on the left with the
number of the component that generated it. Try clicking on the numbers in
the first section; this brings you to the place in the second section
where that component first appears. If there's a particular piece of HTML
you want to change on a page, searching in the annotated source will let
you quickly determine which component is responsible.
The final section of the debug page shows input and output HTTP
headers. Note that some of these are simulated due to your Previewer
settings. For example, if you specified a particular user agent in your
Previewer configuration, then the User-Agent header is simulated;
otherwise it reflects your actual browser.
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->base_comp' to get a handle on the appropriate component:
my $self = $m->base_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');
or alternatively a path of the form 'SELF:method':
<& SELF:header &>
$m->comp('SELF:header')
In the context of a component path, SELF is shorthand for
`$m->base_comp'.
Each of the above 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')) { ...
To defer to the method of your parent, use parent:
$m->current_comp->parent->call_method('header')
or alternatively a path of the form 'PARENT:method':
<& PARENT:header &>
$m->comp('PARENT:header')
In the context of a component path, PARENT is shorthand for
`$m->current_comp->parent'.
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' to
avoid this error for questionable attributes:
if ($self->attr_exists('color')) { ...
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 = '$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>
bgcolor=>'white'
<%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>
bgcolor=>'beige'
<%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 use print or $r->print
Most Mason servers operate in "batch" mode, which means that output
is stored in a Mason buffer until the end of the request. Output sent
via print and $r->print, however, skips the Mason buffer and goes
directly to the client. This will result in output being printed out
of order. Always use `$m->out' instead of print/$r->print; it does the
right thing with regards to Mason buffering.
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);
AUTHOR
======
Jonathan Swartz, swartz@pobox.com
SEE ALSO
========
*Note HTML/Mason: HTML/Mason,, *Note HTML/Mason/Request:
HTML/Mason/Request,