1 package Catalyst::View::TT;
4 use base qw/Catalyst::Base/;
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
24 our $ROOT = '/home/dent/catalyst/MyApp';
30 # any TT configurations items go here
32 "$ROOT/templates/src",
35 PRE_PROCESS => 'config/main',
36 WRAPPER => 'site/wrapper',
38 # two optional config items
39 CATALYST_VAR => 'Catalyst',
44 # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
46 sub message : Global {
47 my ( $self, $c ) = @_;
48 $c->stash->{template} = 'message.tt2';
49 $c->stash->{message} = 'Hello World!';
50 $c->forward('MyApp::V::TT');
53 # access variables from template
55 The message is: [% message %].
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 %]
62 # example when CATALYST_VAR isn't set
64 The base is [% base %]
65 The name is [% name %]
69 This is the Catalyst view class for the L<Template Toolkit|Template>.
70 Your application should defined a view class which is a subclass of
71 this module. The easiest way to achieve this is using the
72 F<myapp_create.pl> script (where F<myapp> should be replaced with
73 whatever your application is called). This script is created as part
74 of the Catalyst setup.
76 $ script/myapp_create.pl view TT TT
78 This creates a MyApp::V::TT.pm module in the F<lib> directory (again,
79 replacing C<MyApp> with the name of your application) which looks
82 package FooBar::V::TT;
85 use base 'Catalyst::View::TT';
87 __PACKAGE__->config->{DEBUG} = 'all';
89 Now you can modify your action handlers in the main application and/or
90 controllers to forward to your view class. You might choose to do this
91 in the end() method, for example, to automatically forward all actions
94 # In MyApp or MyApp::Controller::SomeController
98 $c->forward('MyApp::V::TT');
103 There are a three different ways to configure your view class. The
104 first way is to call the C<config()> method in the view subclass. This
105 happens when the module is first loaded.
107 package MyApp::V::TT;
110 use base 'Catalyst::View::TT';
112 our $ROOT = '/home/dent/catalyst/MyApp';
114 MyApp::V::TT->config({
115 INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
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.
129 INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
130 PRE_PROCESS => 'config/main',
131 WRAPPER => 'site/wrapper',
133 return $self->NEXT::new(@_);
136 The final, and perhaps most direct way, is to define a class
137 item in your main application configuration, again by calling the
138 uniquitous C<config()> method. The items in the class hash are
139 added to those already defined by the above two methods. This happens
140 in the base class new() method (which is one reason why you must
141 remember to call it via C<NEXT> if you redefine the C<new()> method in a
149 our $ROOT = '/home/dent/catalyst/MyApp';
155 INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
156 PRE_PROCESS => 'config/main',
157 WRAPPER => 'site/wrapper',
161 Note that any configuration items defined by one of the earlier
162 methods will be overwritten by items of the same name provided by the
165 =head2 RENDERING VIEWS
167 The view plugin renders the template specified in the C<template>
170 sub message : Global {
171 my ( $self, $c ) = @_;
172 $c->stash->{template} = 'message.tt2';
173 $c->forward('MyApp::V::TT');
176 If a class item isn't defined, then it instead uses the
177 current match, as returned by C<$c-E<gt>match>. In the above
178 example, this would be C<message>.
180 The items defined in the stash are passed to the Template Toolkit for
181 use as template variables.
183 sub message : Global {
184 sub default : Private {
185 my ( $self, $c ) = @_;
186 $c->stash->{template} = 'message.tt2';
187 $c->stash->{message} = 'Hello World!';
188 $c->forward('MyApp::V::TT');
191 A number of other template variables are also added:
193 c A reference to the context object, $c
194 base The URL base, from $c->req->base()
195 name The application name, from $c->config->{ name }
197 These can be accessed from the template in the usual way:
201 The message is: [% message %]
202 The base is [% base %]
203 The name is [% name %]
206 The output generated by the template is stored in
207 C<$c-E<gt>response-E<gt>output>.
209 =head2 TEMPLATE PROFILING
217 The constructor for the TT view. Sets up the template provider,
218 and reads the application config.
223 my ( $class, $c, $arguments ) = @_;
225 my $root = $c->config->{root};
229 TEMPLATE_EXTENSION => '',
230 INCLUDE_PATH => [ $root, "$root/base" ],
235 # if we're debugging and/or the TIMER option is set, then we install
236 # Template::Timer as a custom CONTEXT object, but only if we haven't
237 # already got a custom CONTEXT defined
239 if ( $config->{TIMER} ) {
240 if ( $config->{CONTEXT} ) {
242 'Cannot use Template::Timer - a TT CONFIG is already defined');
245 $config->{CONTEXT} = Template::Timer->new(%$config);
249 if ( $c->debug && $config->{DUMP_CONFIG} ) {
251 $c->log->debug( "TT Config: ", Dumper($config) );
254 return $class->NEXT::new(
257 template => Template->new($config) || do {
258 my $error = Template->error();
259 $c->log->error($error);
269 Renders the template specified in C<$c-E<gt>stash-E<gt>{template}> or
270 C<$c-E<gt>request-E<gt>match>. Template variables are set up from the
271 contents of C<$c-E<gt>stash>, augmented with C<base> set to
272 C<$c-E<gt>req-E<gt>base>, C<c> to C<$c> and C<name> to
273 C<$c-E<gt>config-E<gt>{name}>. Alternately, the C<CATALYST_VAR>
274 configuration item can be defined to specify the name of a template
275 variable through which the context reference (C<$c>) can be accessed.
276 In this case, the C<c>, C<base> and C<name> variables are omitted.
277 Output is stored in C<$c-E<gt>response-E<gt>output>.
282 my ( $self, $c ) = @_;
284 my $template = $c->stash->{template} || $c->request->match . $self->config->{TEMPLATE_EXTENSION};
287 $c->log->debug('No template specified for rendering') if $c->debug;
291 $c->log->debug(qq/Rendering template "$template"/) if $c->debug;
294 my $cvar = $self->config->{CATALYST_VAR};
300 base => $c->req->base,
301 name => $c->config->{name}
306 unless ( $self->template->process( $template, $vars, \$output ) ) {
307 my $error = $self->template->error;
308 $error = qq/Couldn't render template "$error"/;
309 $c->log->error($error);
314 unless ( $c->response->content_type ) {
315 $c->response->content_type('text/html; charset=utf-8');
318 $c->response->body($output);
325 This method allows your view subclass to pass additional settings to
326 the TT configuration hash, or to set the options as below:
330 =item C<CATALYST_VAR>
332 Allows you to change the name of the Catalyst context object. If set, it will also
333 remove the base and name aliases, so you will have access them through <context>.
341 CATALYST_VAR => 'Catalyst',
347 The base is [% Catalyst.req.base %]
348 The name is [% Catalyst.config.name %]
352 If you have configured Catalyst for debug output, and turned on the TIMER setting,
353 C<Catalyst::View::TT> will enable profiling of template processing
354 (using L<Template::Timer>). This will embed HTML comments in the
355 output from your templates, such as:
357 <!-- TIMER START: process mainmenu/mainmenu.ttml -->
358 <!-- TIMER START: include mainmenu/cssindex.tt -->
359 <!-- TIMER START: process mainmenu/cssindex.tt -->
360 <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
361 <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
365 <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
368 =item C<TEMPLATE_EXTENSION>
370 an extension to add when looking for templates bases on the C<match> method in L<Catalyst::Request>.
374 package MyApp::C::Test;
375 sub test : Local { .. }
377 Would by default look for a template in <root>/test/test. If you set TEMPLATE_EXTENSION to '.tt', it will look for
386 The L<Catalyst::Helper::View::TT> and
387 L<Catalyst::Helper::View::TTSite> helper modules are provided to create
388 your view module. There are invoked by the F<myapp_create.pl> script:
390 $ script/myapp_create.pl view TT TT
392 $ script/myapp_create.pl view TT TTSite
394 The L<Catalyst::Helper::View::TT> module creates a basic TT view
395 module. The L<Catalyst::Helper::View::TTSite> module goes a little
396 further. It also creates a default set of templates to get you
397 started. It also configures the view module to locate the templates
402 L<Catalyst>, L<Catalyst::Helper::View::TT>,
403 L<Catalyst::Helper::View::TTSite>, L<Template::Manual>
407 Sebastian Riedel, C<sri@cpan.org>
409 Marcus Ramberg, C<mramberg@cpan.org>
411 Jesse Sheidlower, C<jester@panix.com>
413 Andy Wardley, C<abw@cpan.org>
417 This program is free software, you can redistribute it and/or modify it
418 under the same terms as Perl itself.