.\" 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::Manual::Components 3pm" .TH Mason::Manual::Components 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::Manual::Components \- The building blocks of Mason .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fIcomponent\fR \- a file with a mix of Perl and \s-1HTML \-\s0 is Mason's basic building block. Pages are usually formed by combining the output from multiple components. An article page for a online magazine, for example, might call separate components for the company masthead, ad banner, left table of contents, and article body. .PP .Vb 10 \& +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& |Masthead | Banner Ad | \& +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | | | \& |+\-\-\-\-\-\-\-+|Text of Article ..| \& || || | \& ||Related||Text of Article ..| \& ||Stories|| | \& || ||Text of Article ..| \& |+\-\-\-\-\-\-\-+| | \& | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | | Footer | \& +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP The top level component decides the overall page layout. Individual cells are then filled by the output of subordinate components. Pages might be built up from as few as one, to as many as hundreds of components, with each component contributing a chunk of \s-1HTML.\s0 .PP Splitting up a page into multiple components gives you roughly the same benefits as splitting up an application into multiple classes: encapsulation, reusability, development concurrency, separation of concerns, etc. .PP Mason actually compiles components down to Perl/Moose classes, which means that many of the tools you use to develop regular classes \- profilers, debuggers, and the like \- can be used with Mason components with slight tweaking. .SH "COMPONENT FILES" .IX Header "COMPONENT FILES" .SS "The component root and component paths" .IX Subsection "The component root and component paths" When you use Mason, you specify a component root that all component files live under. Thereafter, any component will be referred to by its virtual \fIpath\fR relative to the root, rather than its full filename. .PP For example, if the component root is '/opt/web/comps', then the component path \&'/foo/bar.mc' refers to the file '/opt/web/comps/foo/bar.mc'. .PP It is also possible to specify multiple component roots, ala Perl's \f(CW@INC\fR, in which case a component path might refer to one of several files. .SS "Component file extensions" .IX Subsection "Component file extensions" By default Mason facilitates and enforces standard file extensions for components. .IP ".mc \- top-level component" 4 .IX Item ".mc - top-level component" A top-level component can serve as the page component in a request. .IP ".mi \- internal component" 4 .IX Item ".mi - internal component" An internal component can only be accessed from other components. .IP ".mp \- pure-perl component" 4 .IX Item ".mp - pure-perl component" A pure-perl component contains only code; it is parsed as if its entire content was within a \f(CW%class\fR block. You do not need to (and are not allowed to) include Mason tags in this component, and it will not produce any output if called. This is just a way of defining a class that other components can easily interact with and extend. Some applications include: controller logic, web form handlers, and autobase components. .PP These extensions are configurable via \*(L"pure_perl_extensions\*(R" in Mason::Interp and \&\*(L"top_level_extensions\*(R" in Mason::Interp. .SH "CALLING COMPONENTS" .IX Header "CALLING COMPONENTS" The initial component in a request, called the page component, is called from run, which in turn may be called from a \s-1PSGI\s0 handler or an web framework view depending on your setup. See Mason::Manual::RequestDispatch for more information about how the page component is chosen. .PP A component can call another component with the <& &> tag: .PP .Vb 1 \& <& /path/to/comp.mi, name=>value, ... &> .Ve .PP or via the comp or scomp methods: .PP .Vb 4 \& <%init> \& $m\->comp(\*(Aq/some/component.mi\*(Aq, foo => 5); \& my $output = $m\->scomp(\*(Aq/some/other/component.mi\*(Aq); \& %init> .Ve .PP From the implementation perspective, calling a component means creating a new instance of the component's class with the specified parameters, and then calling method \f(CW\*(C`handle\*(C'\fR (for the page component) or \f(CW\*(C`main\*(C'\fR (for an internal component) on the instance. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" You can declare attributes in components and pass them when calling components. .SS "Declaring attributes" .IX Subsection "Declaring attributes" Use Moose 'has' syntax to declare attributes within a \f(CW\*(C`<%class>\*(C'\fR section: .PP .Vb 5 \& <%class> \& has \*(Aqfoo\*(Aq; \& has \*(Aqbar\*(Aq => (required => 1); \& has \*(Aqbaz\*(Aq => (isa => \*(AqInt\*(Aq, default => 17); \& %class> .Ve .SS "Attributes are read-write by default" .IX Subsection "Attributes are read-write by default" Mason::Component::Moose imports MooseX::HasDefaults::RW into all components, which makes attributes read-write unless stated otherwise. This is not considered best practice for general \s-1OO\s0 programming, but component instances are short-lived and not usually accessed outside of their class so we feel the convenience is warranted. .SS "Accessing attributes" .IX Subsection "Accessing attributes" A declared attribute 'foo' can be accessed inside the component via the Perl6\-ish syntax .PP .Vb 1 \& $.foo .Ve .PP which is transformed by DollarDot to .PP .Vb 1 \& $self\->foo .Ve .PP In the rest of this documentation we will use \f(CW$.\fR notation, but feel free to substitute \f(CW\*(C`$self\->\*(C'\fR conceptually and/or in reality. .PP To set the attribute, you must use: .PP .Vb 1 \& $.foo(5); .Ve .PP unless you're using LvalueAttributes, in which case you can say .PP .Vb 1 \& $.foo = 5; .Ve .PP \&\f(CW\*(C`$.args\*(C'\fR will return a hashref of all of the parameters passed to the component when it was created/called, regardless of whether they correspond to declared attributes. .SH "METHODS" .IX Header "METHODS" The base component class, Mason::Component, has but a few built-in methods: handle, render, wrap, main, m, and cmeta. .PP The \f(CW\*(C`main\*(C'\fR method contains the mix of \s-1HTML\s0 and Perl in the main part of the component. .PP You can add other methods that output \s-1HTML\s0 via the \f(CW\*(C`<$method>\*(C'\fR section; these methods automatically have access to \f(CW$self\fR and \f(CW$m\fR. .PP .Vb 6 \& <%method leftcol> \&
<% $foo %> | \& ... \&