1 package Catalyst::View::TT;
4 use base qw/Catalyst::View/;
11 __PACKAGE__->mk_accessors('template');
15 Catalyst::View::TT - Template View Class
19 # use the helper to create View
20 myapp_create.pl view TT TT
22 # configure in lib/MyApp.pm
26 root => MyApp->path_to('root');,
28 # any TT configurations items go here
30 MyApp->path_to( 'root', 'src' ),
31 MyApp->path_to( 'root', 'lib' ),
33 PRE_PROCESS => 'config/main',
34 WRAPPER => 'site/wrapper',
35 TEMPLATE_EXTENSION => '.tt',
37 # two optional config items
38 CATALYST_VAR => 'Catalyst',
43 # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
45 sub message : Global {
46 my ( $self, $c ) = @_;
47 $c->stash->{template} = 'message.tt2';
48 $c->stash->{message} = 'Hello World!';
49 $c->forward('MyApp::V::TT');
52 # access variables from template
54 The message is: [% message %].
56 # example when CATALYST_VAR is set to 'Catalyst'
57 Context is [% Catalyst %]
58 The base is [% Catalyst.req.base %]
59 The name is [% Catalyst.config.name %]
61 # example when CATALYST_VAR isn't set
63 The base is [% base %]
64 The name is [% name %]
68 This is the Catalyst view class for the L<Template Toolkit|Template>.
69 Your application should defined a view class which is a subclass of
70 this module. The easiest way to achieve this is using the
71 F<myapp_create.pl> script (where F<myapp> should be replaced with
72 whatever your application is called). This script is created as part
73 of the Catalyst setup.
75 $ script/myapp_create.pl view TT TT
77 This creates a MyApp::V::TT.pm module in the F<lib> directory (again,
78 replacing C<MyApp> with the name of your application) which looks
81 package FooBar::V::TT;
84 use base 'Catalyst::View::TT';
86 __PACKAGE__->config->{DEBUG} = 'all';
88 Now you can modify your action handlers in the main application and/or
89 controllers to forward to your view class. You might choose to do this
90 in the end() method, for example, to automatically forward all actions
93 # In MyApp or MyApp::Controller::SomeController
97 $c->forward('MyApp::V::TT');
102 There are a three different ways to configure your view class. The
103 first way is to call the C<config()> method in the view subclass. This
104 happens when the module is first loaded.
106 package MyApp::V::TT;
109 use base 'Catalyst::View::TT';
111 MyApp::V::TT->config({
113 MyApp->path_to( 'root', 'templates', 'lib' ),
114 MyApp->path_to( 'root', 'templates', 'src' ),
116 PRE_PROCESS => 'config/main',
117 WRAPPER => 'site/wrapper',
120 The second way is to define a C<new()> method in your view subclass.
121 This performs the configuration when the view object is created,
122 shortly after being loaded. Remember to delegate to the base class
123 C<new()> method (via C<$self-E<gt>NEXT::new()> in the example below) after
124 performing any configuration.
130 MyApp->path_to( 'root', 'templates', 'lib' ),
131 MyApp->path_to( 'root', 'templates', 'src' ),
133 PRE_PROCESS => 'config/main',
134 WRAPPER => 'site/wrapper',
136 return $self->NEXT::new(@_);
139 The final, and perhaps most direct way, is to define a class
140 item in your main application configuration, again by calling the
141 uniquitous C<config()> method. The items in the class hash are
142 added to those already defined by the above two methods. This happens
143 in the base class new() method (which is one reason why you must
144 remember to call it via C<NEXT> if you redefine the C<new()> method in a
154 root => MyApp->path_to('root'),
157 MyApp->path_to( 'root', 'templates', 'lib' ),
158 MyApp->path_to( 'root', 'templates', 'src' ),
160 PRE_PROCESS => 'config/main',
161 WRAPPER => 'site/wrapper',
165 Note that any configuration items defined by one of the earlier
166 methods will be overwritten by items of the same name provided by the
169 =head2 RENDERING VIEWS
171 The view plugin renders the template specified in the C<template>
174 sub message : Global {
175 my ( $self, $c ) = @_;
176 $c->stash->{template} = 'message.tt2';
177 $c->forward('MyApp::V::TT');
180 If a class item isn't defined, then it instead uses the
181 current match, as returned by C<$c-E<gt>match>. In the above
182 example, this would be C<message>.
184 The items defined in the stash are passed to the Template Toolkit for
185 use as template variables.
187 sub message : Global {
188 sub default : Private {
189 my ( $self, $c ) = @_;
190 $c->stash->{template} = 'message.tt2';
191 $c->stash->{message} = 'Hello World!';
192 $c->forward('MyApp::V::TT');
195 A number of other template variables are also added:
197 c A reference to the context object, $c
198 base The URL base, from $c->req->base()
199 name The application name, from $c->config->{ name }
201 These can be accessed from the template in the usual way:
205 The message is: [% message %]
206 The base is [% base %]
207 The name is [% name %]
210 The output generated by the template is stored in
211 C<$c-E<gt>response-E<gt>output>.
213 =head2 TEMPLATE PROFILING
221 The constructor for the TT view. Sets up the template provider,
222 and reads the application config.
227 my ( $class, $c, $arguments ) = @_;
229 my $root = $c->config->{root};
233 TEMPLATE_EXTENSION => '',
234 INCLUDE_PATH => [ $root, "$root/base" ],
239 # if we're debugging and/or the TIMER option is set, then we install
240 # Template::Timer as a custom CONTEXT object, but only if we haven't
241 # already got a custom CONTEXT defined
243 if ( $config->{TIMER} ) {
244 if ( $config->{CONTEXT} ) {
246 'Cannot use Template::Timer - a TT CONFIG is already defined');
249 $config->{CONTEXT} = Template::Timer->new(%$config);
253 if ( $c->debug && $config->{DUMP_CONFIG} ) {
255 $c->log->debug( "TT Config: ", Dumper($config) );
258 my $self = $class->NEXT::new(
261 template => Template->new($config) || do {
262 my $error = Template->error();
263 $c->log->error($error);
270 $self->config($config);
277 Renders the template specified in C<$c-E<gt>stash-E<gt>{template}> or
278 C<$c-E<gt>request-E<gt>match>. Template variables are set up from the
279 contents of C<$c-E<gt>stash>, augmented with C<base> set to
280 C<$c-E<gt>req-E<gt>base>, C<c> to C<$c> and C<name> to
281 C<$c-E<gt>config-E<gt>{name}>. Alternately, the C<CATALYST_VAR>
282 configuration item can be defined to specify the name of a template
283 variable through which the context reference (C<$c>) can be accessed.
284 In this case, the C<c>, C<base> and C<name> variables are omitted.
285 Output is stored in C<$c-E<gt>response-E<gt>output>.
290 my ( $self, $c ) = @_;
292 my $template = $c->stash->{template}
293 || $c->request->match . $self->config->{TEMPLATE_EXTENSION};
296 $c->log->debug('No template specified for rendering') if $c->debug;
300 $c->log->debug(qq/Rendering template "$template"/) if $c->debug;
303 my $cvar = $self->config->{CATALYST_VAR};
309 base => $c->req->base,
310 name => $c->config->{name}
315 unless ( $self->template->process( $template, $vars, \$output ) ) {
316 my $error = $self->template->error;
317 $error = qq/Couldn't render template "$error"/;
318 $c->log->error($error);
323 unless ( $c->response->content_type ) {
324 $c->response->content_type('text/html; charset=utf-8');
327 $c->response->body($output);
334 This method allows your view subclass to pass additional settings to
335 the TT configuration hash, or to set the options as below:
339 =item C<CATALYST_VAR>
341 Allows you to change the name of the Catalyst context object. If set, it will also
342 remove the base and name aliases, so you will have access them through <context>.
348 root => MyApp->path_to('root'),
350 CATALYST_VAR => 'Catalyst',
356 The base is [% Catalyst.req.base %]
357 The name is [% Catalyst.config.name %]
361 If you have configured Catalyst for debug output, and turned on the TIMER setting,
362 C<Catalyst::View::TT> will enable profiling of template processing
363 (using L<Template::Timer>). This will embed HTML comments in the
364 output from your templates, such as:
366 <!-- TIMER START: process mainmenu/mainmenu.ttml -->
367 <!-- TIMER START: include mainmenu/cssindex.tt -->
368 <!-- TIMER START: process mainmenu/cssindex.tt -->
369 <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
370 <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
374 <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
377 =item C<TEMPLATE_EXTENSION>
379 a sufix to add when looking for templates bases on the C<match> method in L<Catalyst::Request>.
383 package MyApp::C::Test;
384 sub test : Local { .. }
386 Would by default look for a template in <root>/test/test. If you set TEMPLATE_EXTENSION to '.tt', it will look for
395 The L<Catalyst::Helper::View::TT> and
396 L<Catalyst::Helper::View::TTSite> helper modules are provided to create
397 your view module. There are invoked by the F<myapp_create.pl> script:
399 $ script/myapp_create.pl view TT TT
401 $ script/myapp_create.pl view TT TTSite
403 The L<Catalyst::Helper::View::TT> module creates a basic TT view
404 module. The L<Catalyst::Helper::View::TTSite> module goes a little
405 further. It also creates a default set of templates to get you
406 started. It also configures the view module to locate the templates
411 L<Catalyst>, L<Catalyst::Helper::View::TT>,
412 L<Catalyst::Helper::View::TTSite>, L<Template::Manual>
416 Sebastian Riedel, C<sri@cpan.org>
418 Marcus Ramberg, C<mramberg@cpan.org>
420 Jesse Sheidlower, C<jester@panix.com>
422 Andy Wardley, C<abw@cpan.org>
426 This program is free software, you can redistribute it and/or modify it
427 under the same terms as Perl itself.