Commit | Line | Data |
eb99eb06 |
1 | package Catalyst::View::Component::SubInclude; |
2 | use Moose::Role; |
3 | |
4 | use Carp qw/croak/; |
5 | use namespace::clean qw/croak/; |
6 | |
6819a8ba |
7 | =head1 NAME |
8 | |
9 | Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views |
10 | |
11 | =head1 VERSION |
12 | |
1113d995 |
13 | Version 0.04 |
6819a8ba |
14 | |
15 | =cut |
16 | |
1113d995 |
17 | our $VERSION = '0.04'; |
6819a8ba |
18 | |
19 | =head1 SYNOPSIS |
20 | |
21 | package MyApp::View::TT; |
22 | use Moose; |
23 | |
24 | extends 'Catalyst::View::TT'; |
25 | with 'Catalyst::View::Component::SubInclude'; |
26 | |
27 | __PACKAGE__->config( subinclude_plugin => 'SubRequest' ); |
28 | |
29 | Then, somewhere in your templates: |
30 | |
31 | [% subinclude('/my/widget') %] |
19ff3d04 |
32 | [% subinclude_using('SubRequest', '/page/footer') %] |
6819a8ba |
33 | |
34 | =head1 DESCRIPTION |
35 | |
36 | C<Catalyst::View::Component::SubInclude> allows you to include content in your |
37 | templates (or, more generally, somewhere in your view's C<render> processing) |
38 | which comes from another action in your application. It's implemented as a |
62ebc3f4 |
39 | L<Moose::Role|Moose::Role>, so using L<Moose|Moose> in your view is required. |
6819a8ba |
40 | |
41 | Simply put, it's a way to include the output of a Catalyst sub-request somewhere |
42 | in your page. |
43 | |
44 | It's built in an extensible way so that you're free to use sub-requests, Varnish |
45 | ESI (L<http://www.catalystframework.org/calendar/2008/17>) or any other |
46 | sub-include plugin you might want to implement. An LWP plugin seems useful and |
47 | might be developed in the future. |
48 | |
19ff3d04 |
49 | =head1 STASH FUNCTIONS |
6819a8ba |
50 | |
51 | This component does its magic by exporting a C<subinclude> coderef entry to the |
52 | stash. This way, it's easily accessible by the templates (which is the most |
53 | common use-case). |
54 | |
55 | =head2 C<subinclude( $path, @args )> |
56 | |
62ebc3f4 |
57 | This will render and return the body of the included resource (as specified by |
19ff3d04 |
58 | C<$path>) using the default subinclude plugin. |
59 | |
60 | =head2 C<subinclude_using( $plugin, $path, @args )> |
61 | |
62 | This will render and return the body of the included resource (as specified by |
63 | C<$path>) using the specified subinclude plugin. |
64 | |
65 | The C<subinclude> function above is implemented basically as a shortcut which |
66 | calls this function using the default plugin as the first parameter. |
6819a8ba |
67 | |
68 | =head1 SUBINCLUDE PLUGINS |
69 | |
70 | The module comes with two subinclude plugins: |
6cb4b001 |
71 | L<SubRequest|Catalyst::Plugin::View::Component::SubRequest>, |
72 | L<Visit|Catalyst::Plugin::View::Component::Visit> and |
6819a8ba |
73 | L<ESI|Catalyst::Plugin::View::Component::ESI>. |
74 | |
19ff3d04 |
75 | By default, the C<SubRequest> plugin will be used. This can be changed in the |
6819a8ba |
76 | view's configuration options (either in the config file or in the view module |
77 | itself). |
78 | |
79 | Configuration file example: |
80 | |
81 | <View::TT> |
82 | subinclude_plugin ESI |
83 | </View::TT> |
84 | |
19ff3d04 |
85 | =head2 C<set_subinclude_plugin( $plugin )> |
86 | |
87 | This method changes the current active subinclude plugin in runtime. It expects |
88 | the plugin suffix (e.g. C<ESI> or C<SubRequest>) or a fully-qualified class |
89 | name in the C<Catalyst::View::Component::SubInclude> namespace. |
90 | |
91 | =head2 Writing plugins |
92 | |
8dbcfa50 |
93 | If writing your own plugin, keep in kind plugins are required to implement a |
94 | class method C<generate_subinclude> with the following signature: |
95 | |
96 | sub generate_subinclude { |
97 | my ($class, $c, @args) = @_; |
98 | } |
99 | |
19ff3d04 |
100 | The default plugin is stored in the C<subinclude_plugin> which can be changed |
101 | in runtime. It expects a fully qualified class name. |
102 | |
6819a8ba |
103 | =cut |
104 | |
eb99eb06 |
105 | has 'subinclude_plugin' => ( |
106 | is => 'rw', |
107 | isa => 'ClassName' |
19ff3d04 |
108 | ); |
eb99eb06 |
109 | |
110 | around 'new' => sub { |
111 | my $next = shift; |
112 | my $class = shift; |
113 | |
114 | my $self = $class->$next( @_ ); |
115 | |
116 | my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest'; |
19ff3d04 |
117 | $self->set_subinclude_plugin( $subinclude_plugin ); |
eb99eb06 |
118 | |
119 | $self; |
120 | }; |
121 | |
122 | around 'render' => sub { |
123 | my $next = shift; |
124 | my ($self, $c, @args) = @_; |
125 | |
19ff3d04 |
126 | $c->stash->{subinclude} = sub { $self->_subinclude( $c, @_ ) }; |
127 | $c->stash->{subinclude_using} = sub { $self->_subinclude_using( $c, @_ ) }; |
eb99eb06 |
128 | |
129 | $self->$next( $c, @args ); |
130 | }; |
131 | |
19ff3d04 |
132 | sub set_subinclude_plugin { |
133 | my ($self, $plugin) = @_; |
134 | |
135 | my $subinclude_class = $self->_subinclude_plugin_class_name( $plugin ); |
136 | $self->subinclude_plugin( $subinclude_class ); |
137 | } |
138 | |
139 | sub _subinclude { |
140 | my ($self, $c, @args) = @_; |
141 | $self->_subinclude_using( $c, $self->subinclude_plugin, @args ); |
142 | } |
143 | |
144 | sub _subinclude_using { |
145 | my ($self, $c, $plugin, @args) = @_; |
146 | $plugin = $self->_subinclude_plugin_class_name($plugin); |
147 | $plugin->generate_subinclude( $c, @args ); |
148 | } |
149 | |
150 | sub _subinclude_plugin_class_name { |
151 | my ($self, $plugin) = @_; |
152 | |
153 | # check if name is already fully qualified |
154 | my $pkg = __PACKAGE__; |
155 | return $plugin if $plugin =~ /^$pkg/; |
156 | |
157 | my $class_name = __PACKAGE__ . '::' . $plugin; |
158 | |
159 | eval "require $class_name"; |
160 | croak "Error requiring $class_name: $@" if $@; |
161 | |
162 | $class_name; |
163 | } |
164 | |
6819a8ba |
165 | =head1 SEE ALSO |
166 | |
62ebc3f4 |
167 | L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>, |
168 | L<Moose::Role|Moose::Role>, L<Moose|Moose>, |
6819a8ba |
169 | L<http://www.catalystframework.org/calendar/2008/17> |
170 | |
171 | =head1 BUGS |
172 | |
173 | Please report any bugs or feature requests to |
174 | C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at |
175 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>. |
176 | I will be notified, and then you'll automatically be notified of progress on |
177 | your bug as I make changes. |
178 | |
179 | =head1 AUTHOR |
180 | |
181 | Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >> |
182 | |
183 | =head1 SPONSORSHIP |
184 | |
185 | Development sponsored by Ionzero LLC L<http://www.ionzero.com/>. |
186 | |
187 | =head1 COPYRIGHT & LICENSE |
188 | |
189 | Copyright (C) 2009 Nilson Santos Figueiredo Junior. |
190 | |
191 | Copyright (C) 2009 Ionzero LLC. |
192 | |
193 | This program is free software; you can redistribute it and/or modify it |
194 | under the same terms as Perl itself. |
195 | |
196 | =cut |
197 | |
eb99eb06 |
198 | 1; |