Tài liệu Embedding Perl in HTML with Mason Chapter 4: APIs- P1 pptx

Chapter 4: APIs- P1
Mason is more than just a templating system. It provides a framework for
translating requests into output.
1
This framework has a number of
class/object APIs worth knowing about. You certainly won't need to use
most of these methods very often, but you will probably want to use at least
some of them in many of your Mason-based projects. This chapter
documents those APIs. For a more concise reference to these methods, see
Appendix B
.
Request Class and Object API
The request object in Mason represents the context of the current request
process. For example, it knows where in the component wrapping chain it is,
what arguments have been passed to various component calls, if you've been
bad or good, and so on. It also allows you to change that context in various
ways, such as by calling another component or aborting the request.
The request API provides access to some of the most frequently used Mason
features, particularly those relating to component calls, autohandlers, and
aborting in the middle of a request.
Recall, as first mentioned in Chapter 2
, that the Mason request object is
available in all components as $m.
The request class has only two class methods. The first,
HTML::Mason::Request->new() , is intended for use by other Mason
objects and is not documented for external use. If you want to make a new
request object, use the make_subrequest() method provided by the
request object, which is covered as part of the discussion of Mason's
subrequest mechanism in Chapter 5
.
The second class method, HTML::Mason::Request->instance() ,

returns the current Mason request object. This is useful if you have code
outside of a Mason component that needs to access the request object. Inside
components, you can just use $m.
The request object's methods can be grouped together into several functional
areas.
Constructor Parameters
A number of
parameters can be set when creating a new request object. You will most
often set these by passing them to the ApacheHandler's constructor or by
setting them in your httpd.conf
file. You may occasionally want to set one of
these parameters on the fly for the current request. Finally, you will create a
new request object when you want to make a subrequest, and you may want
to set these parameters then.
All of the following parameters are also available as get/set methods of the
same name:
•
autoflush
This attribute is discussed in "Buffer-Related Methods"
, later in this
chapter.
•
data_cache_defaults
This returns a hash reference containing default options for the
Request object's cache() method.
•
dhandler_name
This is the name used for dhandlers. This defaults to "dhandler."
•
error_format

This may be brief , text , line , or html . These produce an
error message with no trace, a multiline error with trace information, a
single-line error with tab-separated fields (suitable for writing to a
log), and a fancy HTML format.
Each of these methods corresponds to a method in the
HTML::Mason::Exception class, such as as_text() or
as_line(). You can create your own method in the
HTML::Mason::Exception namespace, such as
as_you_wish(), in which case you could set this parameter to
"you_wish." This method will receive a single argument, the
exception object, and is expected to return a string containing the
formatted error message.
In a mod_perl or CGI environment, this defaults to html format.
Otherwise, the default is text .
•
error_mode
This may be either fatal or output . In fatal mode, errors are
thrown as exceptions. In output mode, the exception is converted to a
text representation and sent to the same output stream as normal
content.
In a mod_perl or CGI environment, the default is output , which
means that errors go the client. In any other environment, the default
is fatal . If you set this to fatal in a web environment, errors will
end up in your web server's logs. If you wish to implement your own
exception-handling mechanism around Mason, set this to fatal and
catch the exceptions yourself.
•
max_recurse
This can be used to set the maximum stack size for component calls
and subrequests. It defaults to 32, which is likely to be more than

enough for any application. But if for some reason you need more,
you can set this to a higher number.
•
out_method
This parameter indicates where output should be sent and must be a
reference to either a scalar or a subroutine. If it is a scalar reference,
output will be appended to this scalar. If it is a subroutine reference
(often called a code reference in Perl parlance), this subroutine will be
called with a list of arguments whenever output needs to be sent,
which occurs after the output has passed through all of Mason's
buffers.
The default out_method will print its arguments to STDOUT. In a
mod_perl or CGI environment, this means that output gets sent to
the client.
Calling Other Components
Besides the component call tag (<& &>) discussed in Chapter 2
, there are
several other ways for one component to call another:
•
comp(component, arguments)
This method is exactly like the <&...&> tag discussed in Chapter 2.
It allows you to call another component, specified either by path or by
supplying a component object as the first argument. Arguments are
passed exactly as with the component call tag.
The return value of this method is the return value of the component
being called. Most components will not have an explicit return value
and will return undef. Any output generated by the called
component becomes part of the output of that particular request.
As of Mason 1.10, a hash reference can be provided as an additional
first argument to this method. The contents of this hash reference are

used to modify the way the component call is processed. Right now,
only one parameter -- store -- is accepted for this hash reference.
The value of the store key should be a reference to a scalar, into
which Mason will place the output for the component. For example:
$m->comp( { store => \$content },
'Hello.comp', to => 'World' );
The output of Hello.comp would be available in the $content
variable. This functionality is fundamentally the same as that provided
by the scomp() method except that it allows you to capture the
component's return value in addition to its output.
•
scomp(component, arguments)
This is exactly like the comp() method except that the called
component's output is returned as a string instead of being sent to the
output stream. This is analogous to the use of sprintf() instead of
printf() in C. Components called via this method go through all
of the normal steps of component execution.
If you have a component that generates output and has a return value
and you want to capture that output in a scalar, you should use the
store component call modifier.
•
content
This method is relevant only inside a component called with content, a
feature we saw briefly in Chapter 2
but will cover more completely in
Chapter 5
.
This method returns the block of content wrapped by the component
call. This will make more sense once you've read "Calling
Components with Content Blocks" in Chapter 5.

Aborting the Flow of Execution
Mason provides a way to abort the flow of execution during a request.
Several request object methods relate to doing so and examining what
happened afterward.
•
abort(optional argument)
Calling this method will immediately abort the execution of the
current request.
If an argument is given to this method, this value will be available via
the aborted_value() method after calling abort().
Since this method is implemented internally via Perl's die()
function, it may be caught by an eval block (eval {...}). In this
case, you may call the aborted() method to distinguish this
exception from one generated by something else in your code. The
value of $@ will be an exception object of the class
HTML::Mason::Exception::Abort.
In a web context, if you don't catch the abort call via an eval block,
the return value will be used as the server status code. The following
example takes advantage of that fact to deny access unless a user has
authenticated himself to Apache:
<%init>
use Apache::Constants;
$m->abort(FORBIDDEN) unless $r->connection-
>user;
</%init>
•
aborted
This method returns a boolean value indicating whether or not
abort() has been called previously during the current request.
•

aborted_value
When aborted() is true, this method returns whatever value was
passed to the abort() call.
If you are using eval blocks for exception handling in your components, it is
important to propagate exceptions generated from a call to abort(). Here
is one way do this:
eval { $m->call_next(%ARGS) };
if ($@) {
if ($m->aborted) {
# pass this up to a higher level
die $@;
} else {
# something else that's bad happened
$m->comp( 'exception_handler', exception =>
$@ );
}
}

The Wrapping Chain
These are methods related to the wrapping chain, which was discussed in
Chapter 3
.
•
call_next(arguments)
When the currently executing component is part of a wrapping chain,
this method will call the next component in the chain, passing it the
current component's arguments and any arguments specified in the
call to call_next().
If there is no next component to call, it will throw an exception.
•

fetch_next
This method returns the next component object in the wrapping chain.
This is the same component that would be run upon calling
call_next(). This object may then be passed to a component call
via the <& &> tag or the comp() method.
•
fetch_next_all
This method returns an array of all of the components in the wrapping
chain that have yet to be executed. They are returned in order based
on their position in the wrapping chain.
Dhandler-Related Methods
Certain request object methods are specifically related to dhandlers:
•
decline
This method was discussed in detail in Chapter 3
. Calling this method
indicates that the current component does not wish to handle the
request, in which case Mason will look for the next available dhandler
to handle it.
•
dhandler_arg
This method was also discussed in Chapter 3
. This method returns the
remainder of the component path after stripping off the dhandler's
directory. Given a call to /archives/2002/02/30/all
and a dhandler
component at /archives/dhandler
, dhandler_arg() returns
2002/02/30/all
.

Miscellaneous Methods
The request object also has some general-use methods:
•
file(filename)
Given a file path, Mason will look for this file and return its contents
as a string.