1 package Catalyst::View::Component::SubInclude;
5 use Catalyst::Utils ();
7 use MooseX::Types::Moose qw/Str HashRef/;
8 use namespace::clean -except => 'meta';
10 with 'Catalyst::Component::ContextClosure';
14 Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views
22 our $VERSION = '0.10';
23 $VERSION = eval $VERSION;
27 package MyApp::View::TT;
30 extends 'Catalyst::View::TT';
31 with 'Catalyst::View::Component::SubInclude';
33 __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
35 Then, somewhere in your templates:
37 [% subinclude('/my/widget') %]
38 [% subinclude_using('SubRequest', '/page/footer') %]
42 C<Catalyst::View::Component::SubInclude> allows you to include content in your
43 templates (or, more generally, somewhere in your view's C<render> processing)
44 which comes from another action in your application. It's implemented as a
45 L<Moose::Role|Moose::Role>, so using L<Moose|Moose> in your view is required.
47 Simply put, it's a way to include the output of a Catalyst sub-request somewhere
50 It's built in an extensible way so that you're free to use sub-requests,
51 Varnish ESI (L<http://www.catalystframework.org/calendar/2008/17>) or any other
52 sub-include plugin you might want to implement.
54 =head1 STASH FUNCTIONS
56 This component does its magic by exporting a C<subinclude> coderef entry to the
57 stash. This way, it's easily accessible by the templates (which is the most
60 =head2 C<subinclude( $path, @args )>
62 This will render and return the body of the included resource (as specified by
63 C<$path>) using the default subinclude plugin.
65 =head2 C<subinclude_using( $plugin, $path, @args )>
67 This will render and return the body of the included resource (as specified by
68 C<$path>) using the specified subinclude plugin.
70 The C<subinclude> function above is implemented basically as a shortcut which
71 calls this function using the default plugin as the first parameter.
73 =head1 SUBINCLUDE PLUGINS
75 The module comes with two subinclude plugins:
76 L<SubRequest|Catalyst::Plugin::View::Component::SubRequest>,
77 L<Visit|Catalyst::Plugin::View::Component::Visit> and
78 L<ESI|Catalyst::Plugin::View::Component::ESI>.
80 By default, the C<SubRequest> plugin will be used. This can be changed in the
81 view's configuration options (either in the config file or in the view module
84 Configuration file example:
90 =head2 C<set_subinclude_plugin( $plugin )>
92 This method changes the current active subinclude plugin in runtime. It expects
93 the plugin suffix (e.g. C<ESI> or C<SubRequest>) or a fully-qualified class
94 name in the C<Catalyst::View::Component::SubInclude> namespace.
96 =head2 Writing plugins
98 If writing your own plugin, keep in kind plugins are required to implement a
99 class method C<generate_subinclude> with the following signature:
101 sub generate_subinclude {
102 my ($class, $c, @args) = @_;
105 The default plugin is stored in the C<subinclude_plugin> which can be changed
106 in runtime. It expects a fully qualified class name.
110 has 'subinclude_plugin' => (
118 default => sub { {} },
121 around 'new' => sub {
125 my $self = $class->$next( @_ );
127 my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest';
128 $self->set_subinclude_plugin( $subinclude_plugin );
133 before 'render' => sub {
134 my ($self, $c, @args) = @_;
136 $c->stash->{subinclude} = $self->make_context_closure(sub { $self->_subinclude( @_ ) }, $c);
137 $c->stash->{subinclude_using} = $self->make_context_closure(sub { $self->_subinclude_using( @_ ) }, $c);
140 sub set_subinclude_plugin {
141 my ($self, $plugin) = @_;
143 my $subinclude_class = blessed $self->_subinclude_plugin_class_instance( $plugin );
144 $self->subinclude_plugin( $subinclude_class );
148 my ($self, $c, @args) = @_;
149 $self->_subinclude_using( $c, $self->subinclude_plugin, @args );
152 sub _subinclude_using {
153 my ($self, $c, $plugin, @args) = @_;
154 $plugin = $self->_subinclude_plugin_class_instance($plugin);
155 $plugin->generate_subinclude( $c, @args );
158 has _subinclude_plugin_class_instance_cache => (
161 default => sub { {} },
164 sub _subinclude_plugin_class_instance {
165 my ($self, $plugin) = @_;
167 my $cache = $self->_subinclude_plugin_class_instance_cache;
168 return $cache->{$plugin} if exists $cache->{$plugin};
170 my $plugin_config = Catalyst::Utils::merge_hashes(
171 $self->subinclude->{ALL}||{},
172 $self->subinclude->{$plugin}||{}
174 my $short_class = $plugin_config->{'class'} ?
175 delete $plugin_config->{'class'}
177 my $class = $short_class =~ /::/ ?
179 : __PACKAGE__ . '::' . $short_class;
181 Class::MOP::load_class($class);
183 return $cache->{$class} = $class->new($plugin_config);
188 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>,
189 L<Moose::Role|Moose::Role>, L<Moose|Moose>,
190 L<http://www.catalystframework.org/calendar/2008/17>
194 Please report any bugs or feature requests to
195 C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at
196 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>.
197 I will be notified, and then you'll automatically be notified of progress on
198 your bug as I make changes.
202 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
206 Tomas Doran (t0m) C<< <bobtfish@bobtfish.net >>.
208 Vladimir Timofeev, C<< <vovkasm at gmail.com> >>.
210 Wallace Reis (wreis) C<< <wreis@cpan.org> >>.
214 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
216 =head1 COPYRIGHT & LICENSE
218 Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above contributors.
220 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
222 Copyright (C) 2009 Ionzero LLC.
224 This program is free software; you can redistribute it and/or modify it
225 under the same terms as Perl itself.