Commit | Line | Data |
b2285828 |
1 | NAME |
2 | Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst |
3 | views |
4 | |
5 | VERSION |
30751dc9 |
6 | Version 0.10 |
340929a7 |
7 | |
8 | SYNOPSIS |
9 | package MyApp::View::TT; |
10 | use Moose; |
11 | |
12 | extends 'Catalyst::View::TT'; |
13 | with 'Catalyst::View::Component::SubInclude'; |
14 | |
15 | __PACKAGE__->config( subinclude_plugin => 'SubRequest' ); |
16 | |
17 | Then, somewhere in your templates: |
18 | |
19 | [% subinclude('/my/widget') %] |
20 | [% subinclude_using('SubRequest', '/page/footer') %] |
b2285828 |
21 | |
22 | DESCRIPTION |
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. |
27 | |
28 | Simply put, it's a way to include the output of a Catalyst sub-request |
29 | somewhere in your page. |
30 | |
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 |
1152381d |
33 | other sub-include plugin you might want to implement. |
b2285828 |
34 | |
340929a7 |
35 | STASH FUNCTIONS |
36 | This component does its magic by exporting a "subinclude" coderef entry |
37 | to the stash. This way, it's easily accessible by the templates (which |
38 | is the most common use-case). |
39 | |
40 | "subinclude( $path, @args )" |
41 | This will render and return the body of the included resource (as |
42 | specified by $path) using the default subinclude plugin. |
43 | |
44 | "subinclude_using( $plugin, $path, @args )" |
45 | This will render and return the body of the included resource (as |
46 | specified by $path) using the specified subinclude plugin. |
47 | |
48 | The "subinclude" function above is implemented basically as a shortcut |
49 | which calls this function using the default plugin as the first |
50 | parameter. |
51 | |
52 | SUBINCLUDE PLUGINS |
53 | The module comes with two subinclude plugins: SubRequest, Visit and ESI. |
54 | |
55 | By default, the "SubRequest" plugin will be used. This can be changed in |
56 | the view's configuration options (either in the config file or in the |
57 | view module itself). |
58 | |
59 | Configuration file example: |
60 | |
61 | <View::TT> |
62 | subinclude_plugin ESI |
63 | </View::TT> |
64 | |
65 | "set_subinclude_plugin( $plugin )" |
66 | This method changes the current active subinclude plugin in runtime. It |
67 | expects the plugin suffix (e.g. "ESI" or "SubRequest") or a |
68 | fully-qualified class name in the |
69 | "Catalyst::View::Component::SubInclude" namespace. |
70 | |
71 | Writing plugins |
72 | If writing your own plugin, keep in kind plugins are required to |
73 | implement a class method "generate_subinclude" with the following |
74 | signature: |
75 | |
76 | sub generate_subinclude { |
77 | my ($class, $c, @args) = @_; |
78 | } |
79 | |
80 | The default plugin is stored in the "subinclude_plugin" which can be |
81 | changed in runtime. It expects a fully qualified class name. |
82 | |
b2285828 |
83 | SEE ALSO |
84 | Catalyst::Plugin::SubRequest, Moose::Role, Moose, |
85 | <http://www.catalystframework.org/calendar/2008/17> |
86 | |
340929a7 |
87 | BUGS |
88 | Please report any bugs or feature requests to |
89 | "bug-catalyst-view-component-subinclude at rt.cpan.org", or through the |
90 | web interface at |
91 | <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component- |
92 | SubInclude>. I will be notified, and then you'll automatically be |
93 | notified of progress on your bug as I make changes. |
94 | |
b2285828 |
95 | AUTHOR |
96 | Nilson Santos Figueiredo Junior, "<nilsonsfj at cpan.org>" |
97 | |
340929a7 |
98 | CONTRIBUTORS |
99 | Tomas Doran (t0m) "<bobtfish@bobtfish.net". |
100 | |
4b86766c |
101 | Vladimir Timofeev, "<vovkasm at gmail.com>". |
102 | |
103 | Wallace Reis (wreis) "<wreis@cpan.org>". |
104 | |
b2285828 |
105 | SPONSORSHIP |
106 | Development sponsored by Ionzero LLC <http://www.ionzero.com/>. |
107 | |
108 | COPYRIGHT & LICENSE |
340929a7 |
109 | Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above |
110 | contributors. |
111 | |
b2285828 |
112 | Copyright (C) 2009 Nilson Santos Figueiredo Junior. |
113 | |
114 | Copyright (C) 2009 Ionzero LLC. |
115 | |
116 | This program is free software; you can redistribute it and/or modify it |
117 | under the same terms as Perl itself. |
340929a7 |
118 | |