.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mason::Component 3pm"
.TH Mason::Component 3pm "2014-02-01" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mason::Component \- Mason Component base class
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Every Mason component corresponds to a unique class that inherits, directly or
indirectly, from this base class.
.PP
A new instance of the component class is created whenever a component is called
\&\- whether via a top level request, \f(CW\*(C`<& &>\*(C'\fR tags, or an << \f(CW$m\fR\->comp >>
call. A component instance is only valid for the Mason request in which it was
created.
.PP
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.
.SH "STRUCTURAL METHODS"
.IX Header "STRUCTURAL METHODS"
This is the standard call chain for the page component (the initial component
of a request).
.PP
.Vb 1
\& handle \-> render \-> wrap \-> main
.Ve
.PP
In many cases only \f(CW\*(C`main\*(C'\fR will actually do anything.
.IP "handle" 4
.IX Item "handle"
This is the top-most method called on the page component. Its job is to decide
how to handle the request, e.g.
.RS 4
.IP "\(bu" 4
throw an error (e.g. permission denied)
.IP "\(bu" 4
take some action and redirect (e.g. if handling a form in a web environment)
.IP "\(bu" 4
defer to another component via \f(CW\*(C`$m\->go\*(C'\fR
.IP "\(bu" 4
render the page
.RE
.RS 4
.Sp
It should not output any content itself. By default, it simply calls
render.
.RE
.IP "render" 4
.IX Item "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.
.IP "wrap" 4
.IX Item "wrap"
This method is invoked from render on the page component. By
convention, \f(CW\*(C`wrap\*(C'\fR 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.
.Sp
.Vb 6
\& <%augment wrap>
\& Subtitle section
\&
\& <% inner() %>
\&
\&
.Ve
.Sp
By default, \f(CW\*(C`wrap\*(C'\fR simply calls \f(CW\*(C`inner()\*(C'\fR to go to the next subclass, and
then main at the bottom subclass.
.Sp
To override a component's parent wrapper, a component can define its own
\&\f(CW\*(C`wrap\*(C'\fR using \f(CW\*(C`method\*(C'\fR instead of \f(CW\*(C`augment\*(C'\fR:
.Sp
.Vb 4
\& <%method wrap>
\& Parent wrapper will be ignored
\& <% inner() %>
\&
.Ve
.Sp
To do no wrapping at all, call the component class method \*(L"no_wrap\*(R":
.Sp
.Vb 3
\& <%class>
\& CLASS\->no_wrap;
\&
.Ve
.IP "main" 4
.IX Item "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 \f(CW\*(C`<%method>\*(C'\fR or \f(CW\*(C`<%class>\*(C'\fR tag.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "no_wrap" 4
.IX Item "no_wrap"
A convenience method that redefines render to call main
instead of wrap, thus skipping any content wrapper inherited from
parent.
.Sp
.Vb 3
\& <%class>
\& CLASS\->no_wrap;
\&
.Ve
.IP "allow_path_info" 4
.IX Item "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.
.Sp
.Vb 3
\& <%class>
\& method allow_path_info { 1 }
\&
.Ve
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.IP "args" 4
.IX Item "args"
Returns the hashref of arguments passed to this component's constructor, e.g.
the arguments passed in a component call.
.IP "cmeta" 4
.IX Item "cmeta"
Returns the Mason::Component::ClassMeta object associated with this
component class, containing information such as the component's path and source
file.
.Sp
.Vb 1
\& my $path = $self\->cmeta\->path;
.Ve
.IP "m" 4
.IX Item "m"
Returns the current request. This is also available via \f(CW$m\fR inside Mason
components.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mason
.SH "AUTHOR"
.IX Header "AUTHOR"
Jonathan Swartz
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Jonathan Swartz.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.