Commit | Line | Data |
b2285828 |
1 | NAME |
2 | Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst |
3 | views |
4 | |
5 | VERSION |
a58d7e5c |
6 | Version 0.11 |
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 | |
a58d7e5c |
59 | __PACKAGE__->config( |
60 | subinclude_plugin => 'ESI', |
61 | subinclude => { |
62 | 'SubRequest' => { |
63 | keep_stash => 1, |
64 | }, |
65 | 'HTTP::POST' => { |
66 | class => 'HTTP', |
67 | http_method => 'POST', |
68 | ua_timeout => '10', |
69 | uri_map => { |
70 | '/foo/' => 'http://www.foo.com/', |
71 | }, |
72 | }, |
73 | }, |
74 | ); |
75 | |
76 | You can change each plugins' configuration through the keys in the |
77 | 'subinclude' config key (example above) |
340929a7 |
78 | |
79 | "set_subinclude_plugin( $plugin )" |
80 | This method changes the current active subinclude plugin in runtime. It |
81 | expects the plugin suffix (e.g. "ESI" or "SubRequest") or a |
82 | fully-qualified class name in the |
83 | "Catalyst::View::Component::SubInclude" namespace. |
84 | |
85 | Writing plugins |
86 | If writing your own plugin, keep in kind plugins are required to |
87 | implement a class method "generate_subinclude" with the following |
88 | signature: |
89 | |
90 | sub generate_subinclude { |
91 | my ($class, $c, @args) = @_; |
92 | } |
93 | |
94 | The default plugin is stored in the "subinclude_plugin" which can be |
95 | changed in runtime. It expects a fully qualified class name. |
96 | |
b2285828 |
97 | SEE ALSO |
98 | Catalyst::Plugin::SubRequest, Moose::Role, Moose, |
99 | <http://www.catalystframework.org/calendar/2008/17> |
100 | |
340929a7 |
101 | BUGS |
102 | Please report any bugs or feature requests to |
103 | "bug-catalyst-view-component-subinclude at rt.cpan.org", or through the |
104 | web interface at |
105 | <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component- |
106 | SubInclude>. I will be notified, and then you'll automatically be |
107 | notified of progress on your bug as I make changes. |
108 | |
b2285828 |
109 | AUTHOR |
110 | Nilson Santos Figueiredo Junior, "<nilsonsfj at cpan.org>" |
111 | |
340929a7 |
112 | CONTRIBUTORS |
113 | Tomas Doran (t0m) "<bobtfish@bobtfish.net". |
114 | |
4b86766c |
115 | Vladimir Timofeev, "<vovkasm at gmail.com>". |
116 | |
117 | Wallace Reis (wreis) "<wreis@cpan.org>". |
118 | |
b2285828 |
119 | SPONSORSHIP |
120 | Development sponsored by Ionzero LLC <http://www.ionzero.com/>. |
121 | |
122 | COPYRIGHT & LICENSE |
340929a7 |
123 | Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above |
124 | contributors. |
125 | |
b2285828 |
126 | Copyright (C) 2009 Nilson Santos Figueiredo Junior. |
127 | |
128 | Copyright (C) 2009 Ionzero LLC. |
129 | |
130 | This program is free software; you can redistribute it and/or modify it |
131 | under the same terms as Perl itself. |
340929a7 |
132 | |