Commit | Line | Data |
b2285828 |
1 | NAME |
2 | Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst |
3 | views |
4 | |
5 | VERSION |
dcdc4ec8 |
6 | Version 0.09 |
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 |
dcdc4ec8 |
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. |
b2285828 |
38 | |
340929a7 |
39 | STASH FUNCTIONS |
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). |
43 | |
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. |
47 | |
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. |
51 | |
52 | The "subinclude" function above is implemented basically as a shortcut |
53 | which calls this function using the default plugin as the first |
54 | parameter. |
55 | |
56 | SUBINCLUDE PLUGINS |
57 | The module comes with two subinclude plugins: SubRequest, Visit and ESI. |
58 | |
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 |
61 | view module itself). |
62 | |
63 | Configuration file example: |
64 | |
65 | <View::TT> |
66 | subinclude_plugin ESI |
67 | </View::TT> |
68 | |
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. |
74 | |
75 | Writing plugins |
76 | If writing your own plugin, keep in kind plugins are required to |
77 | implement a class method "generate_subinclude" with the following |
78 | signature: |
79 | |
80 | sub generate_subinclude { |
81 | my ($class, $c, @args) = @_; |
82 | } |
83 | |
84 | The default plugin is stored in the "subinclude_plugin" which can be |
85 | changed in runtime. It expects a fully qualified class name. |
86 | |
b2285828 |
87 | SEE ALSO |
88 | Catalyst::Plugin::SubRequest, Moose::Role, Moose, |
89 | <http://www.catalystframework.org/calendar/2008/17> |
90 | |
340929a7 |
91 | BUGS |
92 | Please report any bugs or feature requests to |
93 | "bug-catalyst-view-component-subinclude at rt.cpan.org", or through the |
94 | web interface at |
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. |
98 | |
b2285828 |
99 | AUTHOR |
100 | Nilson Santos Figueiredo Junior, "<nilsonsfj at cpan.org>" |
101 | |
340929a7 |
102 | CONTRIBUTORS |
103 | Tomas Doran (t0m) "<bobtfish@bobtfish.net". |
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 | |