- Added additional_template_paths stash param patch from zby
[catagits/Catalyst-View-TT.git] / lib / Catalyst / View / TT.pm
CommitLineData
8077080c 1package Catalyst::View::TT;
2
3use strict;
7d8aa5ec 4use base qw/Catalyst::View/;
8077080c 5use Template;
6use Template::Timer;
7use NEXT;
8
07571b2f 9our $VERSION = '0.20';
8077080c 10
11__PACKAGE__->mk_accessors('template');
e2bbd784 12__PACKAGE__->mk_accessors('include_path');
8077080c 13
14=head1 NAME
15
16Catalyst::View::TT - Template View Class
17
18=head1 SYNOPSIS
19
8cd017a8 20# use the helper to create View
722fede4 21 myapp_create.pl view TT TT
8077080c 22
8cd017a8 23# configure in lib/MyApp.pm
24
8cd017a8 25 MyApp->config({
26 name => 'MyApp',
7d8aa5ec 27 root => MyApp->path_to('root');,
7d607671 28 'V::TT' => {
8cd017a8 29 # any TT configurations items go here
30 INCLUDE_PATH => [
93f25382 31 MyApp->path_to( 'root', 'src' ),
32 MyApp->path_to( 'root', 'lib' ),
8cd017a8 33 ],
07571b2f 34 PRE_PROCESS => 'config/main',
35 WRAPPER => 'site/wrapper',
36 TEMPLATE_EXTENSION => '.tt',
8cd017a8 37
38 # two optional config items
39 CATALYST_VAR => 'Catalyst',
40 TIMER => 1,
41 },
42 });
43
44# render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
45
46 sub message : Global {
94b3529a 47 my ( $self, $c ) = @_;
48 $c->stash->{template} = 'message.tt2';
49 $c->stash->{message} = 'Hello World!';
8cd017a8 50 $c->forward('MyApp::V::TT');
51 }
8077080c 52
8cd017a8 53# access variables from template
54
55 The message is: [% message %].
56
57 # example when CATALYST_VAR is set to 'Catalyst'
58 Context is [% Catalyst %]
59 The base is [% Catalyst.req.base %]
60 The name is [% Catalyst.config.name %]
61
62 # example when CATALYST_VAR isn't set
63 Context is [% c %]
64 The base is [% base %]
65 The name is [% name %]
66
67=head1 DESCRIPTION
68
69This is the Catalyst view class for the L<Template Toolkit|Template>.
70Your application should defined a view class which is a subclass of
71this module. The easiest way to achieve this is using the
72F<myapp_create.pl> script (where F<myapp> should be replaced with
73whatever your application is called). This script is created as part
74of the Catalyst setup.
75
76 $ script/myapp_create.pl view TT TT
77
78This creates a MyApp::V::TT.pm module in the F<lib> directory (again,
79replacing C<MyApp> with the name of your application) which looks
80something like this:
81
82 package FooBar::V::TT;
83
84 use strict;
85 use base 'Catalyst::View::TT';
8077080c 86
87 __PACKAGE__->config->{DEBUG} = 'all';
88
8cd017a8 89Now you can modify your action handlers in the main application and/or
90controllers to forward to your view class. You might choose to do this
91in the end() method, for example, to automatically forward all actions
92to the TT view class.
722fede4 93
8cd017a8 94 # In MyApp or MyApp::Controller::SomeController
8077080c 95
8cd017a8 96 sub end : Private {
94b3529a 97 my( $self, $c ) = @_;
8cd017a8 98 $c->forward('MyApp::V::TT');
99 }
8077080c 100
8cd017a8 101=head2 CONFIGURATION
4687ac0d 102
8cd017a8 103There are a three different ways to configure your view class. The
104first way is to call the C<config()> method in the view subclass. This
105happens when the module is first loaded.
8077080c 106
8cd017a8 107 package MyApp::V::TT;
108
109 use strict;
110 use base 'Catalyst::View::TT';
722fede4 111
8cd017a8 112 MyApp::V::TT->config({
7d8aa5ec 113 INCLUDE_PATH => [
114 MyApp->path_to( 'root', 'templates', 'lib' ),
115 MyApp->path_to( 'root', 'templates', 'src' ),
116 ],
8cd017a8 117 PRE_PROCESS => 'config/main',
118 WRAPPER => 'site/wrapper',
119 });
120
121The second way is to define a C<new()> method in your view subclass.
122This performs the configuration when the view object is created,
123shortly after being loaded. Remember to delegate to the base class
124C<new()> method (via C<$self-E<gt>NEXT::new()> in the example below) after
125performing any configuration.
126
127 sub new {
128 my $self = shift;
129 $self->config({
7d8aa5ec 130 INCLUDE_PATH => [
131 MyApp->path_to( 'root', 'templates', 'lib' ),
132 MyApp->path_to( 'root', 'templates', 'src' ),
133 ],
8cd017a8 134 PRE_PROCESS => 'config/main',
135 WRAPPER => 'site/wrapper',
136 });
137 return $self->NEXT::new(@_);
138 }
139
94b3529a 140The final, and perhaps most direct way, is to define a class
8cd017a8 141item in your main application configuration, again by calling the
94b3529a 142uniquitous C<config()> method. The items in the class hash are
8cd017a8 143added to those already defined by the above two methods. This happens
144in the base class new() method (which is one reason why you must
145remember to call it via C<NEXT> if you redefine the C<new()> method in a
146subclass).
147
148 package MyApp;
149
150 use strict;
151 use Catalyst;
152
8cd017a8 153 MyApp->config({
154 name => 'MyApp',
7d8aa5ec 155 root => MyApp->path_to('root'),
7d607671 156 'V::TT' => {
7d8aa5ec 157 INCLUDE_PATH => [
158 MyApp->path_to( 'root', 'templates', 'lib' ),
159 MyApp->path_to( 'root', 'templates', 'src' ),
160 ],
8cd017a8 161 PRE_PROCESS => 'config/main',
162 WRAPPER => 'site/wrapper',
163 },
164 });
165
166Note that any configuration items defined by one of the earlier
167methods will be overwritten by items of the same name provided by the
168latter methods.
169
e2bbd784 170=head2 DYNAMIC INCLUDE_PATH
171
172It is sometimes needed to dynamically add additional paths to the
173INCLUDE_PATH variable of the template object. This can be done by setting
174'additional_include_paths' on stash to a referrence to an array with
175additional paths:
176
177 $c->stash->{additional_template_paths} = [$c->config->{root} . '/test_include_path'];
178
8cd017a8 179=head2 RENDERING VIEWS
180
181The view plugin renders the template specified in the C<template>
182item in the stash.
183
184 sub message : Global {
94b3529a 185 my ( $self, $c ) = @_;
186 $c->stash->{template} = 'message.tt2';
8cd017a8 187 $c->forward('MyApp::V::TT');
188 }
722fede4 189
94b3529a 190If a class item isn't defined, then it instead uses the
8cd017a8 191current match, as returned by C<$c-E<gt>match>. In the above
192example, this would be C<message>.
193
194The items defined in the stash are passed to the Template Toolkit for
195use as template variables.
196
197sub message : Global {
198 sub default : Private {
94b3529a 199 my ( $self, $c ) = @_;
200 $c->stash->{template} = 'message.tt2';
201 $c->stash->{message} = 'Hello World!';
8cd017a8 202 $c->forward('MyApp::V::TT');
203 }
7b592fc7 204
8cd017a8 205A number of other template variables are also added:
8077080c 206
8cd017a8 207 c A reference to the context object, $c
208 base The URL base, from $c->req->base()
209 name The application name, from $c->config->{ name }
210
211These can be accessed from the template in the usual way:
212
213<message.tt2>:
214
215 The message is: [% message %]
216 The base is [% base %]
217 The name is [% name %]
218
8cd017a8 219
220The output generated by the template is stored in
221C<$c-E<gt>response-E<gt>output>.
222
223=head2 TEMPLATE PROFILING
224
caa61517 225=head2 METHODS
8077080c 226
2774dc77 227=over 4
228
229=item new
230
231The constructor for the TT view. Sets up the template provider,
232and reads the application config.
233
8077080c 234=cut
235
e2bbd784 236sub coerce_paths {
237 my ( $paths, $dlim ) = shift;
238 return () if ( ! $paths );
239 return @{$paths} if ( ref $paths eq 'ARRAY');
240 if ( ! ref $paths ){
241 # tweak delim to ignore C:/
242 unless (defined $dlim) {
243 $dlim = ($^O eq 'MSWin32') ? ':(?!\\/)' : ':';
244 }
245 return split(/$dlim/, $paths);
246 }
247}
9300af5b 248
9300af5b 249
e2bbd784 250sub new {
251 my ( $class, $c, $arguments ) = @_;
252 my $delim = $class->config->{DELIMITER} || $arguments->{DELIMITER};
253 my @include_path = coerce_paths($arguments->{INCLUDE_PATH}, $delim);
254 if(!@include_path){
255 @include_path = coerce_paths($class->config->{INCLUDE_PATH}, $delim);
256 }
257 if(!@include_path){
258 my $root = $c->config->{root};
259 my $base = Path::Class::dir($root, 'base');
260 @include_path = ( "$root", "$base" );
261 }
94b3529a 262 my $config = {
7d8aa5ec 263 EVAL_PERL => 0,
4729c102 264 TEMPLATE_EXTENSION => '',
9300af5b 265 %{ $class->config },
e2bbd784 266 %{$arguments},
267 INCLUDE_PATH => \@include_path,
94b3529a 268 };
62728755 269
8cd017a8 270 # if we're debugging and/or the TIMER option is set, then we install
271 # Template::Timer as a custom CONTEXT object, but only if we haven't
272 # already got a custom CONTEXT defined
273
dccfa0ff 274 if ( $config->{TIMER} ) {
94b3529a 275 if ( $config->{CONTEXT} ) {
8cd017a8 276 $c->log->error(
277 'Cannot use Template::Timer - a TT CONFIG is already defined');
278 }
279 else {
94b3529a 280 $config->{CONTEXT} = Template::Timer->new(%$config);
8cd017a8 281 }
282 }
283
94b3529a 284 if ( $c->debug && $config->{DUMP_CONFIG} ) {
8cd017a8 285 use Data::Dumper;
94b3529a 286 $c->log->debug( "TT Config: ", Dumper($config) );
62728755 287 }
288
e3a53d5b 289 my $self = $class->NEXT::new(
8cd017a8 290 $c,
291 {
94b3529a 292 template => Template->new($config) || do {
8cd017a8 293 my $error = Template->error();
294 $c->log->error($error);
295 $c->error($error);
296 return undef;
48d69085 297 },
be7c1afa 298 %{$config},
48d69085 299 },
8cd017a8 300 );
e2bbd784 301 $self->include_path(\@include_path);
e3a53d5b 302 $self->config($config);
303
304 return $self;
8077080c 305}
306
2774dc77 307=item process
8077080c 308
722fede4 309Renders the template specified in C<$c-E<gt>stash-E<gt>{template}> or
310C<$c-E<gt>request-E<gt>match>. Template variables are set up from the
311contents of C<$c-E<gt>stash>, augmented with C<base> set to
312C<$c-E<gt>req-E<gt>base>, C<c> to C<$c> and C<name> to
8cd017a8 313C<$c-E<gt>config-E<gt>{name}>. Alternately, the C<CATALYST_VAR>
314configuration item can be defined to specify the name of a template
315variable through which the context reference (C<$c>) can be accessed.
316In this case, the C<c>, C<base> and C<name> variables are omitted.
317Output is stored in C<$c-E<gt>response-E<gt>output>.
8077080c 318
319=cut
320
321sub process {
322 my ( $self, $c ) = @_;
23042c3c 323
7d8aa5ec 324 my $template = $c->stash->{template}
325 || $c->request->match . $self->config->{TEMPLATE_EXTENSION};
23042c3c 326
327 unless ($template) {
8077080c 328 $c->log->debug('No template specified for rendering') if $c->debug;
329 return 0;
330 }
23042c3c 331
332 $c->log->debug(qq/Rendering template "$template"/) if $c->debug;
23042c3c 333
8cd017a8 334 my $output;
335 my $cvar = $self->config->{CATALYST_VAR};
336 my $vars = {
337 defined $cvar
338 ? ( $cvar => $c )
339 : (
340 c => $c,
341 base => $c->req->base,
342 name => $c->config->{name}
343 ),
344 %{ $c->stash() }
345 };
e2bbd784 346
347 my @tmp_path = @{$self->include_path};
348 unshift @{$self->include_path}, @{$c->stash->{additional_template_paths}} if ref $c->stash->{additional_template_paths};
8cd017a8 349 unless ( $self->template->process( $template, $vars, \$output ) ) {
8077080c 350 my $error = $self->template->error;
351 $error = qq/Couldn't render template "$error"/;
352 $c->log->error($error);
becb7ac2 353 $c->error($error);
23042c3c 354 return 0;
355 }
e2bbd784 356 @{$self->include_path} = @tmp_path if ref $c->stash->{additional_template_paths};
357
23042c3c 358 unless ( $c->response->content_type ) {
359 $c->response->content_type('text/html; charset=utf-8');
8077080c 360 }
23042c3c 361
362 $c->response->body($output);
363
8077080c 364 return 1;
365}
366
2774dc77 367=item config
8077080c 368
8cd017a8 369This method allows your view subclass to pass additional settings to
4729c102 370the TT configuration hash, or to set the options as below:
371
372=over 2
373
374=item C<CATALYST_VAR>
375
376Allows you to change the name of the Catalyst context object. If set, it will also
377remove the base and name aliases, so you will have access them through <context>.
378
379For example:
380
381 MyApp->config({
382 name => 'MyApp',
7d8aa5ec 383 root => MyApp->path_to('root'),
4729c102 384 'V::TT' => {
385 CATALYST_VAR => 'Catalyst',
386 },
387 });
388
389F<message.tt2>:
390
391 The base is [% Catalyst.req.base %]
392 The name is [% Catalyst.config.name %]
393
394=item C<TIMER>
395
396If you have configured Catalyst for debug output, and turned on the TIMER setting,
397C<Catalyst::View::TT> will enable profiling of template processing
398(using L<Template::Timer>). This will embed HTML comments in the
399output from your templates, such as:
400
401 <!-- TIMER START: process mainmenu/mainmenu.ttml -->
402 <!-- TIMER START: include mainmenu/cssindex.tt -->
403 <!-- TIMER START: process mainmenu/cssindex.tt -->
404 <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
405 <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
406
407 ....
408
409 <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
410
411
be7c1afa 412=item C<TEMPLATE_EXTENSION>
4729c102 413
747f2b6d 414a sufix to add when looking for templates bases on the C<match> method in L<Catalyst::Request>.
4729c102 415
416For example:
417
418 package MyApp::C::Test;
419 sub test : Local { .. }
420
421Would by default look for a template in <root>/test/test. If you set TEMPLATE_EXTENSION to '.tt', it will look for
422<root>/test/test.tt.
423
424=back
8077080c 425
2774dc77 426=back
8077080c 427
8cd017a8 428=head2 HELPERS
429
430The L<Catalyst::Helper::View::TT> and
431L<Catalyst::Helper::View::TTSite> helper modules are provided to create
432your view module. There are invoked by the F<myapp_create.pl> script:
433
434 $ script/myapp_create.pl view TT TT
435
436 $ script/myapp_create.pl view TT TTSite
437
438The L<Catalyst::Helper::View::TT> module creates a basic TT view
439module. The L<Catalyst::Helper::View::TTSite> module goes a little
440further. It also creates a default set of templates to get you
441started. It also configures the view module to locate the templates
442automatically.
443
8077080c 444=head1 SEE ALSO
445
8cd017a8 446L<Catalyst>, L<Catalyst::Helper::View::TT>,
447L<Catalyst::Helper::View::TTSite>, L<Template::Manual>
8077080c 448
c0eb0527 449=head1 AUTHORS
8077080c 450
451Sebastian Riedel, C<sri@cpan.org>
c0eb0527 452
d938377b 453Marcus Ramberg, C<mramberg@cpan.org>
c0eb0527 454
722fede4 455Jesse Sheidlower, C<jester@panix.com>
c0eb0527 456
8cd017a8 457Andy Wardley, C<abw@cpan.org>
8077080c 458
459=head1 COPYRIGHT
460
2774dc77 461This program is free software, you can redistribute it and/or modify it
462under the same terms as Perl itself.
8077080c 463
464=cut
465
4661;