NAME¶
Mason::Component - Mason Component base class
DESCRIPTION¶
Every Mason component corresponds to a unique class that inherits, directly or
indirectly, from this base class.
A new instance of the component class is created whenever a component is called
- whether via a top level request, "<& &>" tags, or an
<< $m->comp >> call. A component instance is only valid for the
Mason request in which it was created.
We leave this class as devoid of built-in methods as possible, allowing you to
create methods in your own components without worrying about name clashes.
STRUCTURAL METHODS¶
This is the standard call chain for the page component (the initial component of
a request).
handle -> render -> wrap -> main
In many cases only "main" will actually do anything.
- handle
- This is the top-most method called on the page component. Its job is to
decide how to handle the request, e.g.
- •
- throw an error (e.g. permission denied)
- •
- take some action and redirect (e.g. if handling a form in a web
environment)
- •
- defer to another component via "$m->go"
- •
- render the page
It should not output any content itself. By default, it simply calls
render.
- render
- This method is invoked from handle on the page component. Its job is to
output the full content of the page. By default, it simply calls
wrap.
- wrap
- This method is invoked from render on the page component. By convention,
"wrap" is an augmented method, with each superclass calling the
next subclass. This is useful for cascading templates in which the
top-most superclass generates the surrounding content.
<%augment wrap>
<h3>Subtitle section</h3>
<div class="main">
<% inner() %>
</div>
</%augment>
By default, "wrap" simply calls "inner()" to go to the
next subclass, and then main at the bottom subclass.
To override a component's parent wrapper, a component can define its own
"wrap" using "method" instead of "augment":
<%method wrap>
<h3>Parent wrapper will be ignored</h3>
<% inner() %>
</%method>
To do no wrapping at all, call the component class method
"no_wrap":
<%class>
CLASS->no_wrap;
</%class>
- main
- This method is invoked when a non-page component is called, and from the
default wrap method as well. It consists of the code and output in the
main part of the component that is not inside a
"<%method>" or "<%class>" tag.
CLASS METHODS¶
- no_wrap
- A convenience method that redefines render to call main instead of wrap,
thus skipping any content wrapper inherited from parent.
<%class>
CLASS->no_wrap;
</%class>
- allow_path_info
- This method is called when the request path has a path_info portion, to
determine whether the path_info is allowed. Default is false. See
Mason::Manual::RequestDispatch.
<%class>
method allow_path_info { 1 }
</%class>
OTHER METHODS¶
- args
- Returns the hashref of arguments passed to this component's constructor,
e.g. the arguments passed in a component call.
- cmeta
- Returns the Mason::Component::ClassMeta object associated with this
component class, containing information such as the component's path and
source file.
my $path = $self->cmeta->path;
- m
- Returns the current request. This is also available via $m inside Mason
components.
SEE ALSO¶
Mason
AUTHOR¶
Jonathan Swartz <swartz@pobox.com>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2012 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.