|
HTML::Mason::Request - Mason Request Class |
HTML::Mason::Request - Mason Request Class
$m->abort (...)
$m->comp (...)
etc.
The Request API is your gateway to all Mason features not provided by
syntactic tags. Mason creates a new Request object for every web
request. Inside a component you
access the current request object via the global $m.
The methods comp in the Request manpage, comp_exists in the Request manpage, fetch_comp in the Request manpage, and process_comp_path in the Request manpage take a component path as argument.
Interp::exec; in a web environment, this ultimately
becomes the HTTP status code.
abort() is implemented via die() and can thus be caught by eval().
Under the current implementation, any pending <%filter> sections will
not be applied to the output after an abort. This is a known bug but
there is no easy workaround.
The methods aborted and aborted_value return a boolean
indicating whether the current request was aborted and the argument
with which it was aborted, respectively. These would be used,
for example, after an eval() returned with a non-empty $@.
abort.
abort when the request was
aborted. Returns undef if the request was not aborted or was aborted
without an argument.
base_comp is dynamically set to that
component until call_method exits. See Object-Oriented Techniques in the Devel manpage for examples of usage.
$m->cache lets you store and retrieve the results
of computation for improved performance. Each component has its own
data cache for storing one or more key/value pairs. The cache is
implemented as a DBM database. See the data caching in the Devel manpage
section of the Component Developer's Guide for examples
and caching strategies.
The argument to action is one of:
o retrieve: returns the cache value if successful, or undef
if there was no value or if it has expired.
o store: stores a new cache value under the given key. Default key is 'main'. Returns the value being stored if successful.
o expire: expires a given cache value or values. key may be a single key or a list reference. Default key is 'main'.
o keys: returns a list of all the keys in the cache.
value defines what to store. It can be a scalar or a reference to an arbitrary data structure. The allowable size depends on your DBM implementation.
keep_in_memory indicates whether to save the value in memory once it is retrieved. Default is 0, meaning that the value will be retrieved from the cache file each time. If 1, each child server that retrieves this value will save its own copy, which can result in substantial memory usage for larger values. Use sparingly.
The various expiration options are:
o expire_at: takes an absolute expiration time, in Perl time() format
(number of seconds since the epoch)
o expire_in: takes a relative expiration time of the form ``<num><unit>'', where <num> is a positive number and <unit> is one of seconds, minutes, hours, days, or weeks, or any abbreviation thereof. E.g. ``10min'', ``30m'', ``1hour''.
o expire_next: takes a string, either 'hour' or 'day'. It indicates an expiration time at the top of the next hour or day.
o 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.
$m->cache to cache the entire output and/or the return value of
the current component. It is typically used right at the top of an
<%init%> section.
To cache the component's output:
<%init>
return if $m->cache_self(expire_in=>'3 hours'[, key=>'fookey']);
... <rest of init> ...
</%init>
To cache the component's return value:
<%init>
my ($retval,$cached) = $m->cache_self
(expire_in=>'3 hours'[, key=>'fookey']);
return $retval if $cached;
... <rest of init> ...
</%init>
This only works with scalar and reference return values.
$m->cache_self handles both the retrieve and store, so you can pass
both kinds of options to it. See $m->cache for an explanation of
options.
$m->cache_self uses a bit of magic to accomplish everything in one
line. You can use it without understanding it, but if you're
curious, here's how it works:
o A component foo calls $m->cache_self for the first time.
o $m->cache_self sees that the cache is empty and calls foo again
recursively, with a STORE option to capture its content into a buffer.
o foo again calls $m->cache_self which immediately returns 0 this time.
o foo goes about its business and generates content into the $m->cache_self buffer.
o When control is returned to $m->cache_self, it stores the content and
return value in the cache and also outputs the content normally.
Finally $m->cache_self returns the list (retval,1) which in turn
causes foo to return immediately.
$m->caller_args(0) # arguments passed to current component
$m->caller_args(1) # arguments passed to component that called us
$m->caller_args(-1) # arguments passed to first component executed
When called in scalar context, a hash reference is returned. When called in list context, a list of arguments (which may be assigned to a hash) is returned.
my @comps = $m->callers # all components
$m->callers(0) # current component
$m->callers(1) # component that called us
$m->callers(-1) # first component executed
$m->comp in terms of return value and
scalar/list context. See the autohandlers in the Devel manpage section of the
Component Developer's Guide for examples.
clear_buffer only works in batch output mode, and is thwarted by
flush_buffer.
Components work exactly like Perl subroutines in terms of return
values and context. A component can return any type of value, which is
then returned from the $m->comp call.
The <& &> tag provides a convenient shortcut for $m->comp.
Interp::exec path when the dhandler directory is
removed. Otherwise returns undef.
dhandler_arg may be called from any component in the request, not just
the dhandler.
$m->file to resolve relative
filenames.
$m->out is useful
if you need to output something in the middle of a Perl block.
$m->out should be used instead of print or $r->print,
since $m->out may be redirected or buffered depending on the
current state of the interpreter.
$m->comp, but returns the component output as a string
instead of printing it. (Think sprintf versus printf.) The
component's return value is discarded.
time()
format (number of seconds since the epoch).
By using $m->time rather than calling time() directly, you enable
the option of previewer or port-based time/date simulations. e.g.
a port that looks one day into the future.
$m->call_next chain.
These additional methods are available when running Mason with mod_perl and the ApacheHandler.
args_method parameter. If you are using the
'mod_perl' args method, then calling this method is a fatal error.
See the the HTML::Mason::ApacheHandler manpage documentation for more details.
Jonathan Swartz, swartz@pobox.com
the HTML::Mason::Component manpage the HTML::Mason::ApacheHandler manpage
|
HTML::Mason::Request - Mason Request Class |