2 Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst
9 package MyApp::View::TT;
12 extends 'Catalyst::View::TT';
13 with 'Catalyst::View::Component::SubInclude';
15 __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
17 Then, somewhere in your templates:
19 [% subinclude('/my/widget') %]
20 [% subinclude_using('SubRequest', '/page/footer') %]
23 "Catalyst::View::Component::SubInclude" allows you to include content in
24 your templates (or, more generally, somewhere in your view's "render"
25 processing) which comes from another action in your application. It's
26 implemented as a Moose::Role, so using Moose in your view is required.
28 Simply put, it's a way to include the output of a Catalyst sub-request
29 somewhere in your page.
31 It's built in an extensible way so that you're free to use sub-requests,
32 Varnish ESI (<http://www.catalystframework.org/calendar/2008/17>) or any
33 other sub-include plugin you might want to implement. An LWP plugin
34 seems useful and might be developed in the future. If you need to
35 address a resource by it's public path (i.e. the path part trailing
36 "http://example.com/myapp" then you will need to use
37 Catalyst::Plugin::SubRequest directly, and not this component.
40 This component does its magic by exporting a "subinclude" coderef entry
41 to the stash. This way, it's easily accessible by the templates (which
42 is the most common use-case).
44 "subinclude( $path, @args )"
45 This will render and return the body of the included resource (as
46 specified by $path) using the default subinclude plugin.
48 "subinclude_using( $plugin, $path, @args )"
49 This will render and return the body of the included resource (as
50 specified by $path) using the specified subinclude plugin.
52 The "subinclude" function above is implemented basically as a shortcut
53 which calls this function using the default plugin as the first
57 The module comes with two subinclude plugins: SubRequest, Visit and ESI.
59 By default, the "SubRequest" plugin will be used. This can be changed in
60 the view's configuration options (either in the config file or in the
63 Configuration file example:
69 "set_subinclude_plugin( $plugin )"
70 This method changes the current active subinclude plugin in runtime. It
71 expects the plugin suffix (e.g. "ESI" or "SubRequest") or a
72 fully-qualified class name in the
73 "Catalyst::View::Component::SubInclude" namespace.
76 If writing your own plugin, keep in kind plugins are required to
77 implement a class method "generate_subinclude" with the following
80 sub generate_subinclude {
81 my ($class, $c, @args) = @_;
84 The default plugin is stored in the "subinclude_plugin" which can be
85 changed in runtime. It expects a fully qualified class name.
88 Catalyst::Plugin::SubRequest, Moose::Role, Moose,
89 <http://www.catalystframework.org/calendar/2008/17>
92 Please report any bugs or feature requests to
93 "bug-catalyst-view-component-subinclude at rt.cpan.org", or through the
95 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-
96 SubInclude>. I will be notified, and then you'll automatically be
97 notified of progress on your bug as I make changes.
100 Nilson Santos Figueiredo Junior, "<nilsonsfj at cpan.org>"
103 Tomas Doran (t0m) "<bobtfish@bobtfish.net".
105 Vladimir Timofeev, "<vovkasm at gmail.com>".
107 Wallace Reis (wreis) "<wreis@cpan.org>".
110 Development sponsored by Ionzero LLC <http://www.ionzero.com/>.
113 Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above
116 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
118 Copyright (C) 2009 Ionzero LLC.
120 This program is free software; you can redistribute it and/or modify it
121 under the same terms as Perl itself.