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.11';
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 several subinclude plugins:
76 L<SubRequest|Catalyst::View::Component::SubInclude::SubRequest>,
77 L<HTTP|Catalyst::View::Component::SubInclude::HTTP>,
78 L<SSI|Catalyst::View::Component::SubInclude::SSI>,
79 L<Visit|Catalyst::View::Component::SubInclude::Visit> and
80 L<ESI|Catalyst::View::Component::SubInclude::ESI>.
82 By default, the C<SubRequest> plugin will be used. This can be changed in the
83 view's configuration options (either in the config file or in the view module
87 subinclude_plugin => 'ESI',
94 http_method => 'POST',
97 '/foo/' => 'http://www.foo.com/',
103 You can change each plugins' configuration through the keys in the 'subinclude'
104 config key (example above)
106 =head2 C<set_subinclude_plugin( $plugin )>
108 This method changes the current active subinclude plugin in runtime. It expects
109 the plugin suffix (e.g. C<ESI> or C<SubRequest>) or a fully-qualified class
110 name in the C<Catalyst::View::Component::SubInclude> namespace.
112 =head2 Writing plugins
114 If writing your own plugin, keep in kind plugins are required to implement a
115 class method C<generate_subinclude> with the following signature:
117 sub generate_subinclude {
118 my ($class, $c, @args) = @_;
121 The default plugin is stored in the C<subinclude_plugin> which can be changed
122 in runtime. It expects a fully qualified class name.
126 has 'subinclude_plugin' => (
134 default => sub { {} },
137 around 'new' => sub {
141 my $self = $class->$next( @_ );
143 my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest';
144 $self->set_subinclude_plugin( $subinclude_plugin );
149 before 'render' => sub {
150 my ($self, $c, @args) = @_;
152 $c->stash->{subinclude} = $self->make_context_closure(sub { $self->_subinclude( @_ ) }, $c);
153 $c->stash->{subinclude_using} = $self->make_context_closure(sub { $self->_subinclude_using( @_ ) }, $c);
156 sub set_subinclude_plugin {
157 my ($self, $plugin) = @_;
159 my $subinclude_class = blessed $self->_subinclude_plugin_class_instance( $plugin );
160 $self->subinclude_plugin( $subinclude_class );
164 my ($self, $c, @args) = @_;
165 $self->_subinclude_using( $c, $self->subinclude_plugin, @args );
168 sub _subinclude_using {
169 my ($self, $c, $plugin, @args) = @_;
170 $plugin = $self->_subinclude_plugin_class_instance($plugin);
171 $plugin->generate_subinclude( $c, @args );
174 has _subinclude_plugin_class_instance_cache => (
177 default => sub { {} },
180 sub _subinclude_plugin_class_instance {
181 my ($self, $plugin) = @_;
183 my $cache = $self->_subinclude_plugin_class_instance_cache;
184 return $cache->{$plugin} if exists $cache->{$plugin};
186 my $plugin_config = Catalyst::Utils::merge_hashes(
187 $self->subinclude->{ALL}||{},
188 $self->subinclude->{$plugin}||{}
190 my $short_class = $plugin_config->{'class'} ?
191 delete $plugin_config->{'class'}
193 my $class = $short_class =~ /::/ ?
195 : __PACKAGE__ . '::' . $short_class;
197 Class::MOP::load_class($class);
199 return $cache->{$class} = $class->new($plugin_config);
204 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>,
205 L<Moose::Role|Moose::Role>, L<Moose|Moose>,
206 L<http://www.catalystframework.org/calendar/2008/17>
210 Please report any bugs or feature requests to
211 C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at
212 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>.
213 I will be notified, and then you'll automatically be notified of progress on
214 your bug as I make changes.
218 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
222 Tomas Doran (t0m) C<< <bobtfish@bobtfish.net >>.
224 Vladimir Timofeev, C<< <vovkasm at gmail.com> >>.
226 Wallace Reis (wreis) C<< <wreis@cpan.org> >>.
230 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
232 =head1 COPYRIGHT & LICENSE
234 Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above contributors.
236 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
238 Copyright (C) 2009 Ionzero LLC.
240 This program is free software; you can redistribute it and/or modify it
241 under the same terms as Perl itself.