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 that distinction, use the attr() method and wrap it in an eval {} block, or use this method in conjunction with the attr_exists() method. • attr_exists(name) Returns true if the specified attribute exists in the component or its parents. • call_method(name, arguments) Calls the specified method with the given arguments. If the method is not present in the component or any of its parents, an exception is thrown. • scall_method(name, arguments) This is analogous to the scomp() method for the Request object. This method calls the named method with the given arguments and returns the output as a string. If the method is not present in the component or any of its parents, an exception is thrown. • method_exists(name) Returns true if the specified method exists in the component or its parents. Much of the component API is interesting only for introspection, though we're sure creative developers can think of ways to work strange magic with this API. • comp_id Returns a unique ID for this component. This ID may be in the form of a component path, though this is not guaranteed. • load_time Returns the Unix epoch time when this object was created. • declared_args Returns a hash reference containing an entry for each argument declared in the component's <%args> section. These keys include the variable prefix, so they are strings like $foo or %bar. Each key's value is itself a hash reference, which contains a single key, default , the value of which is the string given as the argument's default value, or undef if no default was given. For example, the following <%args> section: <%args> $foo @bar => (1, 2, 3) %baz => ( ) # an empty hash $undefined => undef </%args> would cause the following to be returned from the declared_args() method: { '$foo' => { default => undef }, '@bar' => { default => ' (1, 2, 3)' }, '%baz' => { default => ' ( ) # an empty hash' }, '$undefined' => { default => ' undef' } } Note the difference between an argument with no default value and an argument with a default value of undef. Also, as you can see, the default value for each argument is returned as a string, not a data structure. This is because Mason does not actually parse these values as Perl does, but rather simply drops them into the code it generates in one piece. • dir_path Returns the component's notion of the current directory, relative to the component root. For file-based components, this is the full component path minus the filename. For subcomponents and methods, this will be the same as its parent component. For anonymous components, this will be undef. This path is like a URL path and always uses forward slashes (/) as separators. To get the filesystem path and filename for file-based components, see the source_dir() and source_file() methods. • flag(name) Returns the value of the specified flag. Flags are declared in <%flags> blocks, as covered in "<%flags> and <%attr> blocks" in Chapter 2 . • is_subcomp Returns true if the specified component is a subcomponent or a method. • is_file_based Returns true if the given component is file-based. • name Returns the name of the component. For file-based components, this is the component filename without any path information. For subcomponents and methods, it is the name given in the <%def> or <%method> tag. For anonymous components, this method returns the same value as comp_id(). • owner For subcomponents and methods, returns the component in which the component was defined. • parent Returns the parent component object, if one exists. The way a parent component is determined was discussed in Chapter 3 . • path Returns the component path for file-based components. This path starts from the component root, not the filesystem root. In other words, this is an absolute path that could be used to call this component from another component. For a subcomponent object, this returns a string containing its parent object's path and its own name, separated by a c olon (:). As with dir_path(), the path returned here is a URL-style path and uses the forward slash (/) as its separator. • subcomps With no arguments, returns a hash reference containing all the subcomponents defined in the component. The keys of this hash reference are component names, while the values are the component objects themselves. If an argument is given, it returns the subcomponent of that particular name, or undef if there is no such subcomponent. • methods Operates exactly like the subcomps() method but for methods instead of subcomponents. • title Returns a printable string identifying this component. It is intended to uniquely identify a component within a given interpreter although this is not 100% guaranteed. For file-based components, this is the component's path. If you have multiple component roots, this path will also be supplemented by a string indicating which component root the component was found in. For subcomponents, this is its owner's title plus its own name, as returned by the name() method. For anonymous components, this is the same as comp_id(). [...]... object file is the file that contains the code Mason generates from the component's source file Buffers Playing with buffers is not for the everyday user but may be useful to you during debugging Buffer objects have only a few methods: • output For buffers that store output in a scalar, this method returns the output they have stored so far If the buffer is a filtering buffer, the output will be filtered... Returns the full absolute path to the file that contains the original component source This is given in the native dialect of the filesystem, so its directory separators will be / on Unix, : on Mac OS, and who knows what on VMS • source_dir Returns the full path to the source component's directory on the filesystem As with source_file(), the path is given in the native dialect of the filesystem • object_file... output on to its parents, if it has any Buffers can be set to ignore flushes, in which case this method does nothing • receive(output, ) This method is used to pass output to the buffer It takes an array of scalars, each of which is considered a piece of output • clear This method clears any stored output that the buffer may contain Footnotes 1 You may or may not choose to call this an application server . 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. methods are available when using the HTML: :Mason: :ApacheHandler or HTML: :Mason: :CGIHandler classes. The latter class is covered in Chapter 9 . • cgi_object