File Coverage

blib/lib/Mason/Component.pm
Criterion Covered Total %
statement 53 53 100.0
branch 2 2 100.0
condition n/a
subroutine 22 22 100.0
pod n/a
total 77 77 100.0


line stmt bran cond sub pod time code
1             package Mason::Component;
2             $Mason::Component::VERSION = '2.24';
3 19     19   11244 use Moose; # no Mason::Moose - don't want StrictConstructor
  19         34  
  19         145  
4 19     19   107292 use MooseX::HasDefaults::RO;
  19         42  
  19         197  
5 19     19   78337 use Method::Signatures::Simple;
  19         39  
  19         210  
6 19     19   8976 use Log::Any;
  19         31  
  19         232  
7 19     19   959 use Scalar::Util qw(weaken);
  19         28  
  19         2116  
8              
9             with 'Mason::Filters::Standard';
10              
11             # Passed attributes
12             #
13             has 'args' => ( init_arg => undef, lazy_build => 1 );
14             has 'm' => ( required => 1, weak_ref => 1 );
15              
16             __PACKAGE__->meta->make_immutable();
17              
18 19     19   7318 method BUILD ($params) {
  192     192   356  
  192         396  
  192         271  
19              
20             # Make a copy of params and re-weaken m
21             #
22 192         462 $self->{_orig_params} = $params;
23 192         6231 weaken $self->{_orig_params}->{m};
24             }
25              
26 19     19   6494 method cmeta () {
  1428     1428   1940  
  1428         1360  
27 1428 100       12259 return $self->can('_class_cmeta') ? $self->_class_cmeta : undef;
28             }
29              
30 19     19   5637 method _build_args () {
  15     15   21  
  15         15  
31 15         19 my $orig_params = $self->{_orig_params};
32             return {
33 12         236 map { ( $_, $orig_params->{$_} ) }
  27         193  
34 15         53 grep { $_ ne 'm' } keys(%$orig_params)
35             };
36             }
37              
38             # Default handle - call render
39             #
40 19     19   6305 method handle () {
  157     157   278  
  157         213  
41 157         1130 $self->render(@_);
42             }
43              
44             # Default render - call wrap
45             #
46 19     19   5612 method render () {
  156     156   325  
  156         269  
47 156         795 $self->wrap(@_);
48             }
49              
50             # Top wrap
51             #
52 19     19   5554 method wrap () {
  153     153   1618  
  153         214  
53 153         792 inner();
54             }
55              
56             # By default, do not allow path_info
57             #
58 19     19   5976 method allow_path_info () {
  6     6   26  
  6         15  
59 6         58 return 0;
60             }
61              
62             # Shorcut for skipping wrap
63             #
64 19     19   5717 method no_wrap ($class:) {
  1     1   3  
  1         1  
65 1     1   6 $class->meta->add_method( 'render' => sub { $_[0]->main(@_) } );
  1         6  
66             }
67              
68             1;
69              
70             __END__
71              
72             =pod
73              
74             =head1 NAME
75              
76             Mason::Component - Mason Component base class
77              
78             =head1 DESCRIPTION
79              
80             Every Mason component corresponds to a unique class that inherits, directly or
81             indirectly, from this base class.
82              
83             A new instance of the component class is created whenever a component is called
84             - whether via a top level request, C<< <& &> >> tags, or an << $m->comp >>
85             call. A component instance is only valid for the Mason request in which it was
86             created.
87              
88             We leave this class as devoid of built-in methods as possible, allowing you to
89             create methods in your own components without worrying about name clashes.
90              
91             =head1 STRUCTURAL METHODS
92              
93             This is the standard call chain for the page component (the initial component
94             of a request).
95              
96             handle -> render -> wrap -> main
97              
98             In many cases only C<main> will actually do anything.
99              
100             =over
101              
102             =item handle
103              
104             This is the top-most method called on the page component. Its job is to decide
105             how to handle the request, e.g.
106              
107             =over
108              
109             =item *
110              
111             throw an error (e.g. permission denied)
112              
113             =item *
114              
115             take some action and redirect (e.g. if handling a form in a web environment)
116              
117             =item *
118              
119             defer to another component via C<< $m->go >>
120              
121             =item *
122              
123             render the page
124              
125             =back
126              
127             It should not output any content itself. By default, it simply calls
128             L<render|/render>.
129              
130             =item render
131              
132             This method is invoked from L<handle|/handle> on the page component. Its job is
133             to output the full content of the page. By default, it simply calls
134             L<wrap|/wrap>.
135              
136             =item wrap
137              
138             This method is invoked from L<render|/render> on the page component. By
139             convention, C<wrap> is an L<augmented|Moose::Manual::MethodModifiers/INNER AND
140             AUGMENT> method, with each superclass calling the next subclass. This is
141             useful for cascading templates in which the top-most superclass generates the
142             surrounding content.
143              
144             <%augment wrap>
145             <h3>Subtitle section</h3>
146             <div class="main">
147             <% inner() %>
148             </div>
149             </%augment>
150              
151             By default, C<wrap> simply calls C<< inner() >> to go to the next subclass, and
152             then L<main|/main> at the bottom subclass.
153              
154             To override a component's parent wrapper, a component can define its own
155             C<wrap> using C<method> instead of C<augment>:
156              
157             <%method wrap>
158             <h3>Parent wrapper will be ignored</h3>
159             <% inner() %>
160             </%method>
161              
162             To do no wrapping at all, call the component class method L</no_wrap>:
163              
164             <%class>
165             CLASS->no_wrap;
166             </%class>
167              
168             =item main
169              
170             This method is invoked when a non-page component is called, and from the
171             default L<wrap|/wrap> method as well. It consists of the code and output in the
172             main part of the component that is not inside a C<< <%method> >> or C<<
173             <%class> >> tag.
174              
175             =back
176              
177             =head1 CLASS METHODS
178              
179             =over
180              
181             =item no_wrap
182              
183             A convenience method that redefines L<render|/render> to call L<main|/main>
184             instead of L<wrap|/wrap>, thus skipping any content wrapper inherited from
185             parent.
186              
187             <%class>
188             CLASS->no_wrap;
189             </%class>
190              
191             =item allow_path_info
192              
193             This method is called when the request path has a path_info portion, to
194             determine whether the path_info is allowed. Default is false. See
195             L<Mason::Manual::RequestDispatch|Mason::Manual::RequestDispatch/Partial Paths>.
196              
197             <%class>
198             method allow_path_info { 1 }
199             </%class>
200              
201             =back
202              
203             =head1 OTHER METHODS
204              
205             =over
206              
207             =item args
208              
209             Returns the hashref of arguments passed to this component's constructor, e.g.
210             the arguments passed in a L<component call|/CALLING COMPONENTS>.
211              
212             =item cmeta
213              
214             Returns the L<Mason::Component::ClassMeta> object associated with this
215             component class, containing information such as the component's path and source
216             file.
217              
218             my $path = $self->cmeta->path;
219              
220             =item m
221              
222             Returns the current request. This is also available via C<< $m >> inside Mason
223             components.
224              
225             =back
226              
227             =head1 SEE ALSO
228              
229             L<Mason|Mason>
230              
231             =head1 AUTHOR
232              
233             Jonathan Swartz <swartz@pobox.com>
234              
235             =head1 COPYRIGHT AND LICENSE
236              
237             This software is copyright (c) 2012 by Jonathan Swartz.
238              
239             This is free software; you can redistribute it and/or modify it under
240             the same terms as the Perl 5 programming language system itself.
241              
242             =cut