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