new()
CONSTRUCTOR
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
. Outside of a component, you can use the class
method instance
.
The methods Request->comp, Request->comp_exists, and Request->fetch_comp take a component path argument. Component paths are like URL paths, and always use a forward slash (/) as the separator, regardless of what your operating system uses.
new()
CONSTRUCTOR$m->cache
API to use. '1.1', the default, indicates the newer
API documented in this manual.
'1.0' indicates the old API documented in 1.0x and earlier. This
compatibility layer is provided as a convenience for users upgrading
from older versions of Mason, but will not be supported indefinitely.
$m->cache
command. For example, to use the MemoryCache
implementation
by default,
data_cache_defaults => {cache_class => 'MemoryCache'}
These settings are overriden by options given to particular
$m->cache
calls.
The default format under Apache and CGI is either line or html depending on whether the error mode is fatal or output, respectively. The default for standalone mode is text.
The formats correspond to HTML::Mason::Exception
methods named
as_format. You can define your own format by creating an
appropriately named method; for example, to define an ``xml'' format,
create a method HTML::Mason::Exception::as_xml
patterned after one of
the built-in methods.
The default under Apache and CGI is output, causing the error to be displayed in the browser. The default for standalone mode is fatal.
my $fh = new IO::File ">mason.out"; ... out_method => sub { $fh->print($_[0]) }
By default, out_method prints to standard output. Under
Apache, standard output is
redirected to $r->print
.
Interp::exec
; in a web environment, this ultimately
becomes the HTTP status code.
abort
is implemented by throwing an HTML::Mason::Exception::Abort
object and can thus be caught by eval(). The aborted
method is a
shortcut for determining whether a caught error was generated by
abort
.
$err
was generated by abort
. If no $err
was passed, use $@
.
In this code, we catch and process fatal errors while letting abort
exceptions pass through:
eval { code_that_may_fail_or_abort() }; if ($@) { die $@ if $m->aborted;
# handle fatal errors...
$@
can lose its value quickly, so if you are planning to call
$m->aborted more than a few lines after the eval, you should save $@
to a temporary variable.
$m->request_comp
. However, whenever a component
call is made, the base component changes to the called component,
unless the component call was made uses a component object for its
first argument, or the call starts with SELF: or PARENT:.
$m->cache
returns a new cache object with a namespace specific to
this component.
cache_class specifies the class of cache object to create. It
defaults to FileCache
in most cases, or MemoryCache
if the
interpreter has no data directory, and must be a backend subclass of
Cache::Cache
. The prefix ``Cache::'' need not be included. See the
Cache::Cache
package for a full list of backend subclasses.
I<cache_options> may include any valid options to the new() method of the cache class. e.g. for C<FileCache>, valid options include default_expires_in and cache_depth.
See the data caching section of the developer's manual for a caching tutorial and examples. See the HTML::Mason::Cache::BaseCache documentation for a method reference.
Note: users upgrading from 1.0x and earlier can continue to use the
old $m->cache
API by setting data_cache_api to '1.0'. This
support will be removed at a later date.
$m->cache_self
caches the entire output and return result of a
component.
cache_self
either returns undef, or a list containing the
return value of the component followed by '1'. You should return
immediately upon getting the latter result, as this indicates
that you are inside the second invocation of the component.
cache_self
takes any of parameters to $m->cache
(e.g. cache_depth), any of the optional parameters to
$cache->get
(expire_if, busy_lock), and two additional
options:
$cache->set
. e.g. '10 sec',
'5 min', '2 hours'.
key: An identifier used to uniquely identify the cache results - it
is passed as the first argument to $cache->get
and
$cache->set
. The default key is '__mason_cache_self__'.
To cache the component's output:
<%init> return if $m->cache_self(expire_in => '10 sec'[, key => 'fookey']); ... <rest of init> ... </%init>
To cache the component's scalar return value:
<%init> my ($result, $cached) = $m->cache_self(expire_in => '5 min'[, key => 'fookey']);
return $result if $cached; ... <rest of init> ... </%init>
To cache the component's list return value:
<%init> my (@retval) = $m->cache_self(expire_in => '3 hours'[, key => 'fookey']);
return @retval if pop @retval; ... <rest of init> ... </%init>
We call pop
on @retval
to remove the mandatory '1' at the end of
the list.
Note: users upgrading from 1.0x and earlier can continue to use the
old $m->cache_self
API by setting data_cache_api to '1.0'.
This support will be removed at a later date.
$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->caller(1)
, i.e. the component that called the
currently executing component.
$m->comp
in terms of return value and
scalar/list context. See the autohandlers section of the developer's manual for examples.
clear_buffer is, of course, 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
.
As of 1.10, component calls can accept an initial hash reference of
modifiers. The only currently supported modifier is store
, which
stores the component's output in a scalar reference. For example:
my $buf; my $return = $m->comp( { store => \$buf }, '/some/comp', type => 'big' );
This mostly duplicates the behavior of scomp, but can be useful in rare cases where you need to capture both a component's output and return value.
This modifier can be used with the <& &> tag as well, for example:
<& { store => \$buf }, '/some/comp', size => 'medium' &>
Returns undef if there is no content.
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.
A request can only be executed once; e.g. it is an error to call this recursively on the same request.
$r->rflush
to flush
the Apache buffer. Flushing the initial bytes of output can make your
servers appear more responsive.
Attempts to flush the buffers are ignored within the context of a call
to $m->scomp
or when output is being stored in a scalar
reference, as with the { store =
\$out } > component call
modifier.
Additionally, if a component has a <%filter>
block, that
component is buffered until its entire output is generated. This
means that inside that component and any components that it calls,
the buffer cannot be flushed.
HTML::Mason:::Request
currently in
use. If called when no Mason request is active it will return
undef
.
If called inside a subrequest, it returns the subrequest object.
The ``comp'' parameter is required, while all other parameters are optional.
See the subrequests section of the developer's manual for more information about subrequests.
$m->print
.
$m->print
is useful
if you need to output something in the middle of a Perl block.
In 1.1 and on, print
and $r->print
are remapped to $m->print
,
so they may be used interchangeably. Before 1.1, one should only use
$m->print
.
$m->call_next
chain.
These additional methods are available when running Mason with mod_perl and the ApacheHandler.
$r
.
$r->send_http_header
manually.
See the sending HTTP headers section of the developer's manual for more details about the automatic header feature.
This additional method is available when running Mason with the CGIHandler module.
$r
inside components.
See the CGIHandler docs for more details.
This method is available when Mason is running under either the ApacheHandler or CGIHandler modules.
$m->clear_buffer
to clear out any previous output, and <
$m-
abort >> to abort the request. By default, the status code used
is 302, but this can be overridden by the user.
Since this is implemented using $m->abort
, it will be trapped
by an eval {}
block. If you are using an eval {}
block in
your code to trap errors, you need to make sure to rethrow these
exceptions, like this:
eval { ... };
die $@ if $m->aborted;
# handle other exceptions
Jonathan Swartz <swartz@pobox.com>, Dave Rolsky <autarch@urth.org>, Ken Williams <ken@mathforum.org>