1 package Catalyst::View::Component::SubInclude;
5 use namespace::clean qw/croak/;
6 use Scalar::Util qw/weaken/;
10 Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views
18 our $VERSION = '0.07';
22 package MyApp::View::TT;
25 extends 'Catalyst::View::TT';
26 with 'Catalyst::View::Component::SubInclude';
28 __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
30 Then, somewhere in your templates:
32 [% subinclude('/my/widget') %]
33 [% subinclude_using('SubRequest', '/page/footer') %]
37 C<Catalyst::View::Component::SubInclude> allows you to include content in your
38 templates (or, more generally, somewhere in your view's C<render> processing)
39 which comes from another action in your application. It's implemented as a
40 L<Moose::Role|Moose::Role>, so using L<Moose|Moose> in your view is required.
42 Simply put, it's a way to include the output of a Catalyst sub-request somewhere
45 It's built in an extensible way so that you're free to use sub-requests, Varnish
46 ESI (L<http://www.catalystframework.org/calendar/2008/17>) or any other
47 sub-include plugin you might want to implement. An LWP plugin seems useful and
48 might be developed in the future.
50 =head1 STASH FUNCTIONS
52 This component does its magic by exporting a C<subinclude> coderef entry to the
53 stash. This way, it's easily accessible by the templates (which is the most
56 =head2 C<subinclude( $path, @args )>
58 This will render and return the body of the included resource (as specified by
59 C<$path>) using the default subinclude plugin.
61 =head2 C<subinclude_using( $plugin, $path, @args )>
63 This will render and return the body of the included resource (as specified by
64 C<$path>) using the specified subinclude plugin.
66 The C<subinclude> function above is implemented basically as a shortcut which
67 calls this function using the default plugin as the first parameter.
69 =head1 SUBINCLUDE PLUGINS
71 The module comes with two subinclude plugins:
72 L<SubRequest|Catalyst::Plugin::View::Component::SubRequest>,
73 L<Visit|Catalyst::Plugin::View::Component::Visit> and
74 L<ESI|Catalyst::Plugin::View::Component::ESI>.
76 By default, the C<SubRequest> plugin will be used. This can be changed in the
77 view's configuration options (either in the config file or in the view module
80 Configuration file example:
86 =head2 C<set_subinclude_plugin( $plugin )>
88 This method changes the current active subinclude plugin in runtime. It expects
89 the plugin suffix (e.g. C<ESI> or C<SubRequest>) or a fully-qualified class
90 name in the C<Catalyst::View::Component::SubInclude> namespace.
92 =head2 Writing plugins
94 If writing your own plugin, keep in kind plugins are required to implement a
95 class method C<generate_subinclude> with the following signature:
97 sub generate_subinclude {
98 my ($class, $c, @args) = @_;
101 The default plugin is stored in the C<subinclude_plugin> which can be changed
102 in runtime. It expects a fully qualified class name.
106 has 'subinclude_plugin' => (
111 around 'new' => sub {
115 my $self = $class->$next( @_ );
117 my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest';
118 $self->set_subinclude_plugin( $subinclude_plugin );
123 around 'render' => sub {
125 my ($self, $c, @args) = @_;
129 $c->stash->{subinclude} = sub { $self->_subinclude( $c, @_ ) };
130 $c->stash->{subinclude_using} = sub { $self->_subinclude_using( $c, @_ ) };
132 $self->$next( $c, @args );
135 sub set_subinclude_plugin {
136 my ($self, $plugin) = @_;
138 my $subinclude_class = $self->_subinclude_plugin_class_name( $plugin );
139 $self->subinclude_plugin( $subinclude_class );
143 my ($self, $c, @args) = @_;
144 $self->_subinclude_using( $c, $self->subinclude_plugin, @args );
147 sub _subinclude_using {
148 my ($self, $c, $plugin, @args) = @_;
149 $plugin = $self->_subinclude_plugin_class_name($plugin);
150 $plugin->generate_subinclude( $c, @args );
153 sub _subinclude_plugin_class_name {
154 my ($self, $plugin) = @_;
156 # check if name is already fully qualified
157 my $pkg = __PACKAGE__;
158 return $plugin if $plugin =~ /^$pkg/;
160 my $class_name = __PACKAGE__ . '::' . $plugin;
162 eval "require $class_name";
163 croak "Error requiring $class_name: $@" if $@;
170 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>,
171 L<Moose::Role|Moose::Role>, L<Moose|Moose>,
172 L<http://www.catalystframework.org/calendar/2008/17>
176 Please report any bugs or feature requests to
177 C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at
178 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>.
179 I will be notified, and then you'll automatically be notified of progress on
180 your bug as I make changes.
184 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
188 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
190 =head1 COPYRIGHT & LICENSE
192 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
194 Copyright (C) 2009 Ionzero LLC.
196 This program is free software; you can redistribute it and/or modify it
197 under the same terms as Perl itself.