Commit | Line | Data |
30726632 |
1 | package Catalyst::View::Component::SubInclude; |
2 | use Moose::Role; |
3 | |
4 | use Carp qw/croak/; |
f91a7d21 |
5 | use namespace::clean -except => 'meta'; |
30726632 |
6 | |
d547aa95 |
7 | with 'Catalyst::Component::ContextClosure'; |
8 | |
ada1ae3c |
9 | =head1 NAME |
10 | |
11 | Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views |
12 | |
13 | =head1 VERSION |
14 | |
9399de67 |
15 | Version 0.07 |
ada1ae3c |
16 | |
17 | =cut |
18 | |
9399de67 |
19 | our $VERSION = '0.07'; |
ada1ae3c |
20 | |
21 | =head1 SYNOPSIS |
22 | |
23 | package MyApp::View::TT; |
24 | use Moose; |
25 | |
26 | extends 'Catalyst::View::TT'; |
27 | with 'Catalyst::View::Component::SubInclude'; |
28 | |
29 | __PACKAGE__->config( subinclude_plugin => 'SubRequest' ); |
30 | |
31 | Then, somewhere in your templates: |
32 | |
33 | [% subinclude('/my/widget') %] |
be2a019a |
34 | [% subinclude_using('SubRequest', '/page/footer') %] |
ada1ae3c |
35 | |
36 | =head1 DESCRIPTION |
37 | |
38 | C<Catalyst::View::Component::SubInclude> allows you to include content in your |
39 | templates (or, more generally, somewhere in your view's C<render> processing) |
40 | which comes from another action in your application. It's implemented as a |
4e327756 |
41 | L<Moose::Role|Moose::Role>, so using L<Moose|Moose> in your view is required. |
ada1ae3c |
42 | |
43 | Simply put, it's a way to include the output of a Catalyst sub-request somewhere |
44 | in your page. |
45 | |
46 | It's built in an extensible way so that you're free to use sub-requests, Varnish |
47 | ESI (L<http://www.catalystframework.org/calendar/2008/17>) or any other |
48 | sub-include plugin you might want to implement. An LWP plugin seems useful and |
49 | might be developed in the future. |
50 | |
be2a019a |
51 | =head1 STASH FUNCTIONS |
ada1ae3c |
52 | |
53 | This component does its magic by exporting a C<subinclude> coderef entry to the |
54 | stash. This way, it's easily accessible by the templates (which is the most |
55 | common use-case). |
56 | |
57 | =head2 C<subinclude( $path, @args )> |
58 | |
4e327756 |
59 | This will render and return the body of the included resource (as specified by |
be2a019a |
60 | C<$path>) using the default subinclude plugin. |
61 | |
62 | =head2 C<subinclude_using( $plugin, $path, @args )> |
63 | |
64 | This will render and return the body of the included resource (as specified by |
65 | C<$path>) using the specified subinclude plugin. |
66 | |
67 | The C<subinclude> function above is implemented basically as a shortcut which |
68 | calls this function using the default plugin as the first parameter. |
ada1ae3c |
69 | |
70 | =head1 SUBINCLUDE PLUGINS |
71 | |
72 | The module comes with two subinclude plugins: |
e88af283 |
73 | L<SubRequest|Catalyst::Plugin::View::Component::SubRequest>, |
74 | L<Visit|Catalyst::Plugin::View::Component::Visit> and |
ada1ae3c |
75 | L<ESI|Catalyst::Plugin::View::Component::ESI>. |
76 | |
be2a019a |
77 | By default, the C<SubRequest> plugin will be used. This can be changed in the |
ada1ae3c |
78 | view's configuration options (either in the config file or in the view module |
79 | itself). |
80 | |
81 | Configuration file example: |
82 | |
83 | <View::TT> |
84 | subinclude_plugin ESI |
85 | </View::TT> |
86 | |
be2a019a |
87 | =head2 C<set_subinclude_plugin( $plugin )> |
88 | |
89 | This method changes the current active subinclude plugin in runtime. It expects |
90 | the plugin suffix (e.g. C<ESI> or C<SubRequest>) or a fully-qualified class |
91 | name in the C<Catalyst::View::Component::SubInclude> namespace. |
92 | |
93 | =head2 Writing plugins |
94 | |
11a93ea1 |
95 | If writing your own plugin, keep in kind plugins are required to implement a |
96 | class method C<generate_subinclude> with the following signature: |
97 | |
98 | sub generate_subinclude { |
99 | my ($class, $c, @args) = @_; |
100 | } |
101 | |
be2a019a |
102 | The default plugin is stored in the C<subinclude_plugin> which can be changed |
103 | in runtime. It expects a fully qualified class name. |
104 | |
ada1ae3c |
105 | =cut |
106 | |
30726632 |
107 | has 'subinclude_plugin' => ( |
108 | is => 'rw', |
7c937ccc |
109 | isa => 'Str' |
be2a019a |
110 | ); |
30726632 |
111 | |
112 | around 'new' => sub { |
113 | my $next = shift; |
114 | my $class = shift; |
115 | |
116 | my $self = $class->$next( @_ ); |
117 | |
118 | my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest'; |
be2a019a |
119 | $self->set_subinclude_plugin( $subinclude_plugin ); |
30726632 |
120 | |
121 | $self; |
122 | }; |
123 | |
1869d781 |
124 | before 'render' => sub { |
30726632 |
125 | my ($self, $c, @args) = @_; |
ab0b6bbd |
126 | |
d547aa95 |
127 | $c->stash->{subinclude} = $self->make_context_closure(sub { $self->_subinclude( @_ ) }, $c); |
128 | $c->stash->{subinclude_using} = $self->make_context_closure(sub { $self->_subinclude_using( @_ ) }, $c); |
30726632 |
129 | }; |
130 | |
be2a019a |
131 | sub set_subinclude_plugin { |
132 | my ($self, $plugin) = @_; |
133 | |
134 | my $subinclude_class = $self->_subinclude_plugin_class_name( $plugin ); |
135 | $self->subinclude_plugin( $subinclude_class ); |
136 | } |
137 | |
138 | sub _subinclude { |
139 | my ($self, $c, @args) = @_; |
140 | $self->_subinclude_using( $c, $self->subinclude_plugin, @args ); |
141 | } |
142 | |
143 | sub _subinclude_using { |
144 | my ($self, $c, $plugin, @args) = @_; |
145 | $plugin = $self->_subinclude_plugin_class_name($plugin); |
146 | $plugin->generate_subinclude( $c, @args ); |
147 | } |
148 | |
149 | sub _subinclude_plugin_class_name { |
150 | my ($self, $plugin) = @_; |
151 | |
152 | # check if name is already fully qualified |
153 | my $pkg = __PACKAGE__; |
154 | return $plugin if $plugin =~ /^$pkg/; |
155 | |
156 | my $class_name = __PACKAGE__ . '::' . $plugin; |
157 | |
158 | eval "require $class_name"; |
159 | croak "Error requiring $class_name: $@" if $@; |
160 | |
161 | $class_name; |
162 | } |
163 | |
ada1ae3c |
164 | =head1 SEE ALSO |
165 | |
4e327756 |
166 | L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>, |
167 | L<Moose::Role|Moose::Role>, L<Moose|Moose>, |
ada1ae3c |
168 | L<http://www.catalystframework.org/calendar/2008/17> |
169 | |
170 | =head1 BUGS |
171 | |
172 | Please report any bugs or feature requests to |
173 | C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at |
174 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>. |
175 | I will be notified, and then you'll automatically be notified of progress on |
176 | your bug as I make changes. |
177 | |
178 | =head1 AUTHOR |
179 | |
180 | Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >> |
181 | |
182 | =head1 SPONSORSHIP |
183 | |
184 | Development sponsored by Ionzero LLC L<http://www.ionzero.com/>. |
185 | |
186 | =head1 COPYRIGHT & LICENSE |
187 | |
188 | Copyright (C) 2009 Nilson Santos Figueiredo Junior. |
189 | |
190 | Copyright (C) 2009 Ionzero LLC. |
191 | |
192 | This program is free software; you can redistribute it and/or modify it |
193 | under the same terms as Perl itself. |
194 | |
195 | =cut |
196 | |
30726632 |
197 | 1; |