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.09';
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. An LWP plugin seems useful and
53 might be developed in the future. If you need to address a resource by it's
54 public path (i.e. the path part trailing C<http://example.com/myapp> then you
55 will need to use L<Catalyst::Plugin::SubRequest> directly, and not this
58 =head1 STASH FUNCTIONS
60 This component does its magic by exporting a C<subinclude> coderef entry to the
61 stash. This way, it's easily accessible by the templates (which is the most
64 =head2 C<subinclude( $path, @args )>
66 This will render and return the body of the included resource (as specified by
67 C<$path>) using the default subinclude plugin.
69 =head2 C<subinclude_using( $plugin, $path, @args )>
71 This will render and return the body of the included resource (as specified by
72 C<$path>) using the specified subinclude plugin.
74 The C<subinclude> function above is implemented basically as a shortcut which
75 calls this function using the default plugin as the first parameter.
77 =head1 SUBINCLUDE PLUGINS
79 The module comes with two subinclude plugins:
80 L<SubRequest|Catalyst::Plugin::View::Component::SubRequest>,
81 L<Visit|Catalyst::Plugin::View::Component::Visit> and
82 L<ESI|Catalyst::Plugin::View::Component::ESI>.
84 By default, the C<SubRequest> plugin will be used. This can be changed in the
85 view's configuration options (either in the config file or in the view module
88 Configuration file example:
94 =head2 C<set_subinclude_plugin( $plugin )>
96 This method changes the current active subinclude plugin in runtime. It expects
97 the plugin suffix (e.g. C<ESI> or C<SubRequest>) or a fully-qualified class
98 name in the C<Catalyst::View::Component::SubInclude> namespace.
100 =head2 Writing plugins
102 If writing your own plugin, keep in kind plugins are required to implement a
103 class method C<generate_subinclude> with the following signature:
105 sub generate_subinclude {
106 my ($class, $c, @args) = @_;
109 The default plugin is stored in the C<subinclude_plugin> which can be changed
110 in runtime. It expects a fully qualified class name.
114 has 'subinclude_plugin' => (
122 default => sub { {} },
125 around 'new' => sub {
129 my $self = $class->$next( @_ );
131 my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest';
132 $self->set_subinclude_plugin( $subinclude_plugin );
137 before 'render' => sub {
138 my ($self, $c, @args) = @_;
140 $c->stash->{subinclude} = $self->make_context_closure(sub { $self->_subinclude( @_ ) }, $c);
141 $c->stash->{subinclude_using} = $self->make_context_closure(sub { $self->_subinclude_using( @_ ) }, $c);
144 sub set_subinclude_plugin {
145 my ($self, $plugin) = @_;
147 my $subinclude_class = blessed $self->_subinclude_plugin_class_instance( $plugin );
148 $self->subinclude_plugin( $subinclude_class );
152 my ($self, $c, @args) = @_;
153 $self->_subinclude_using( $c, $self->subinclude_plugin, @args );
156 sub _subinclude_using {
157 my ($self, $c, $plugin, @args) = @_;
158 $plugin = $self->_subinclude_plugin_class_instance($plugin);
159 $plugin->generate_subinclude( $c, @args );
162 has _subinclude_plugin_class_instance_cache => (
165 default => sub { {} },
168 sub _subinclude_plugin_class_instance {
169 my ($self, $plugin) = @_;
171 my $class = $plugin =~ /::/ ? $plugin : __PACKAGE__ . '::' . $plugin;
173 my $cache = $self->_subinclude_plugin_class_instance_cache;
174 return $cache->{$plugin} if exists $cache->{$plugin};
176 my $plugin_config = Catalyst::Utils::merge_hashes(
177 $self->subinclude->{ALL}||{},
178 $self->subinclude->{$plugin}||{}
181 Class::MOP::load_class($class);
183 return $cache->{$plugin} = $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 >>.
210 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
212 =head1 COPYRIGHT & LICENSE
214 Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above contributors.
216 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
218 Copyright (C) 2009 Ionzero LLC.
220 This program is free software; you can redistribute it and/or modify it
221 under the same terms as Perl itself.