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

Chapter 4: APIs- P2

Subrequests
Subrequests are request objects that inherit all their settable properties from
their parent. The main difference between calling a component with a
subrequest versus using a regular component call is that subrequests will
invoke the autohandler and dhandler mechanisms, whereas a regular
component call will execute only the called component. Subrequests are
covered in a more detail in Chapter 5
.
•
make_subrequest(comp => component, args => [ ... ], ...)
This method creates a new subrequest object, which you can then
execute via its exec() method. This gives you a chance to override
the parent object's properties by passing in arguments to this method.
•
subexec(comp, args)
This combines the make_subrequest() method and the
subrequest's exec() method in one step. Any argument list given to
subexec() will become the argument list for the called component.
This doesn't give you a chance to set properties of the request,
however. For that, you'll need to use the full two-step approach of
calling make_subrequest() and then exec() on the returned
object.
•
is_subrequest
This method returns a boolean value indicating whether the given
object is a subrequest.
•
parent_request
Calling this method returns the parent request object for a subrequest.

If called on the top-level request object, it just returns undef.
Methods Available Only When Using ApacheHandler
When you are using Mason under mod_perl with the
HTML::Mason::ApacheHandler class, which is covered in Chapter 7
,
the Request object will contain several additional methods.
•
ah
This method returns the current
HTML::Mason::ApacheHandler object for this request.
•
apache_req
This method returns the current Apache object for the request. This
object is also available in all components as the variable $r.
If you chose to use Apache::Request to handle incoming
parameters by setting args_method to mod_perl, this object will
be an Apache::Request object; otherwise, it will be an Apache
object.
Incoming parameter handling is covered in Chapter 7
.
Methods Available When Using ApacheHandler or CGIHandler
Two additional request methods are available when using the
HTML::Mason::ApacheHandler or HTML::Mason::CGIHandler
classes. The latter class is covered in Chapter 9
.
•
cgi_object
This method is always available when using
HTML::Mason::CGIHandler .
If you are using HTML::Mason::ApacheHandler, this is

available only if you chose to use the CGI.pm module to handle
incoming request parameters.
This method will return the CGI.pm object that was used to handle
incoming parameters.
•
redirect(url)
Given a URL, this generates a proper HTTP redirect, which is then
sent immediately to the client. This will not work if any output has
been previously sent, which may be the case if flush_buffer()
has been called or if the request is in autoflush mode.
Getting in Close with Buffers
Underneath the hood of the request object, output is handled via buffer
objects, which by default are of the HTML::Mason::Buffer class.
The request object maintains a buffer stack. Output goes to the top buffer on
the stack, which can then manipulate it and pass it on to the next buffer in
the stack, which can in turn do the same, and so on.
Buffers are also used to implement features like the request's scomp()
method.
So why would you want to play with buffers? Chances are you won't want to
simply add more plain old HTML::Mason::Buffer objects to the stack.
That wouldn't achieve much.
But if you were to create a custom buffer subclass, you might want to
selectively stick one onto the stack. For example, if you made a buffer that
traced the source of all output it received, you might want to put it on the
stack only for certain parts of your site during debugging. Just be sure to
remove any buffers you add, or Mason may get confused and your output
may never get sent.
The other buffer-related methods are potentially useful for introspection and
debugging:
•

top_buffer
Returns the current top-level buffer object for the request. This is the
buffer to which output is currently being sent.
•
buffer_stack
Returns all the buffers on the stack, starting from the top buffer and
ending with the bottom buffer, which is the one at the bottom of the
stack.
•
push_buffer_stack(Buffer object)
Pushes a new buffer onto the top of the stack. Mason pushes new
buffers onto the stack when calling new components.
•
pop_buffer_stack
Pops the top buffer off the stack and returns it. Mason pops a buffer
each time a component finishes executing.
Component Object API
Objects that you will deal with in this class actually fall into three categories.
The majority will be objects of the
HTML::Mason::Component::FileBased class, which is used for
components generated from component source files. The next most common
will be HTML::Mason::Component::Subcomponent objects, which
represent subcomponents and methods. Finally, anonymous components
created via the HTML::Mason::Interp->make_component()
method (covered in Chapter 5
and Chapter 6) will simply be of the
HTML::Mason::Component class.
For the most part, these objects all share the same interface.
Component objects are returned from a number of Request object methods
as well as the interpreter object's make_component() method.

These first methods are the ones you most likely want to use:
•
attr(name)
Looks for the specified attribute in the component and its parents,
returning the first value found. If the attribute is not found, this
method throws an exception. Attributes are declared in <%attr>
blocks, as covered in "<%flags> and <%attr> blocks" in Chapter 2
.
•
attr_if_exists(name)
Works just like the attr() method except that it simply returns
undef if the specified attribute does not exist.
Of course, this makes it impossible to distinguish between an attribute
with undef as its value and an attribute that is not found. To make