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

Request Class and Object API The request object in Mason represents the context of the current request process.. The second class method, HTML::Mason::Request->instance , returns the cu

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

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

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

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:

This method returns a boolean value indicating whether or not

abort() has been called previously during the current request

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

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

If a relative path is given, Mason will prepend the path with the

current component's directory if the component is file-based or the system's root directory otherwise

This returns the Interp object associated with the current request

Chapter 6 documents this object's API

• count

This method returns this request's number, which is unique for a given request and interpreter

Introspection

The Mason request object provides numerous methods allowing

introspection of the details of the current request Some of these methods

return one or more component objects, while others return information about the arguments passed to components

These methods are useful if you are using autohandlers (particularly more than one) and you want to get some information about the components in a request

Using some of these methods requires an understanding of autohandlers and the wrapping chain, a topic that was covered in Chapter 3

• base_comp

This method returns the base component for a request Initially, the base component is the component that was called for a request This may differ from the current component when you are in an

autohandler

The base component is the first component looked at when a

component method is called in the form:

<& SELF:method &>

Methods are discussed in Chapter 5

The base component is changed when you call another component during the context of that component's execution:

$m->comp( '/some/other/comp' );

In this case, the base component will now be the component

/some/other/comp This will be reset to the original base component

after the call is finished

If you pass a component object to a component call, Mason assumes that you know what you are doing and doesn't change the base

component

If your brain now feels like oatmeal after reading this, simply rest assured that the goal of all this is to make Mason just do the right thing and surprise you as little as possible

But why would you use the base_comp() method, you ask? The primary reason for doing this is to get access to a component's

attributes and methods

Let's say that I call a component called /people/faye_wong/bio.html and it is wrapped by both /people/faye_wong/autohandler and

/people/autohandler While in one of the autohandlers, I may wish to access the attributes of the component that was called

The easiest way to do this is via the base_comp() method, like so:

my $name = $m->base_comp->attr('name');

The attr() method starts looking for an attribute in the component

on which it is called, then ascends the inheritance hierarchy from there We want to start at the last component in the hierarchy the " child component" in order to give it a chance to override any

attributes defined in its parents

• callers(stack level)

This method is analogous to the Perl caller() function It returns one or more component objects in the current component stack When called without an argument, it simply returns the entire array of

components in the stack up to, and including, the current component The first element of the array will be the current component and the last will be the first component in the stack

If this method is called with an integer argument, then that number is used as an index number into the stack Just as with Perl arrays,

negative integers start at the end of the stack and count backward

my @comps = $m->callers # all components

$m->callers(0) # current component

$m->callers(1) # component that called us

$m->callers(-1) # first component executed

• caller

This method is equivalent to $m->callers(1)

• caller_args( stack level )

This method returns the arguments passed to the component on a

given part of the stack Unlike the callers() method, this method requires an integer argument to specify a stack index When called in

a list context, this method returns a list In a scalar context, it returns a hash reference

If the arguments to the given component were not specified as

key/value pairs (see "%ARGS Versus @_" in Chapter 2), you will

need to assign the returned value to an array in order to avoid an error

# arguments passed to current component

This method returns a component object representing the requested

component For example, if your wrapper chain looks like this:

Note that this is very similar to base_comp() The difference

between them is that request_comp() will always refer to

/tasks/show_task.html for the entire duration of the request, whereas base_comp() may change when other components are called

Buffer-Related Methods

The following methods all deal with Mason's

buffer objects A typical request starts off with a single base buffer For each component that is called in the component stack, another buffer will be

added to the stack In addition, filtering and other special Mason features will add and remove additional buffers

The buffer objects have their own API, detailed later in this chapter, but you will rarely need to use this unless you have a need to implement a subclass

of Mason's default buffer class, HTML::Mason::Buffer

The request API offers several methods for dealing with the buffer stack as a whole:

• autoflush(boolean)

This method can be used to turn autoflushing on and off When

autoflushing is on, output is sent as soon as it is generated Otherwise,

it is buffered until all components have run

By default, autoflushing is off

Remember that if you turn autoflush on, the first piece of output

generated by a component will end up being sent immediately In a web context, this will prevent you from aborting execution later (to issue a redirect, for example)

Also, while autoflushing may give the impression of a snappier

response because the first output arrives quicker, it is usually a bit slower overall than buffering all the output and sending it at once

• flush_buffer

This method flushes any output that the top buffer on the stack

contains, sending it to the next buffer below it in the stack Depending

on what other buffers are below it, the flushing may continue through the entire stack, meaning output will be sent, or it may stop part of the way through because some buffers are set to ignore flushes

If autoflush is on, this method is meaningless as no output is ever buffered

Attempts to flush the buffers are ignored within the context of a call to scomp() or when output is being stored in a scalar reference, as with the { store => \$out } component call modifier for the

comp() method

This method can be used to send output to the client more quickly in a web context: