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',
37 TEMPLATE_SUFFIX => '.tt',
39 # two optional config items
40 CATALYST_VAR => 'Catalyst',
45 # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
47 sub message : Global {
48 my ( $self, $c ) = @_;
49 $c->stash->{template} = 'message.tt2';
50 $c->stash->{message} = 'Hello World!';
51 $c->forward('MyApp::V::TT');
54 # access variables from template
56 The message is: [% message %].
58 # example when CATALYST_VAR is set to 'Catalyst'
59 Context is [% Catalyst %]
60 The base is [% Catalyst.req.base %]
61 The name is [% Catalyst.config.name %]
63 # example when CATALYST_VAR isn't set
65 The base is [% base %]
66 The name is [% name %]
70 This is the Catalyst view class for the L<Template Toolkit|Template>.
71 Your application should defined a view class which is a subclass of
72 this module. The easiest way to achieve this is using the
73 F<myapp_create.pl> script (where F<myapp> should be replaced with
74 whatever your application is called). This script is created as part
75 of the Catalyst setup.
77 $ script/myapp_create.pl view TT TT
79 This creates a MyApp::V::TT.pm module in the F<lib> directory (again,
80 replacing C<MyApp> with the name of your application) which looks
83 package FooBar::V::TT;
86 use base 'Catalyst::View::TT';
88 __PACKAGE__->config->{DEBUG} = 'all';
90 Now you can modify your action handlers in the main application and/or
91 controllers to forward to your view class. You might choose to do this
92 in the end() method, for example, to automatically forward all actions
95 # In MyApp or MyApp::Controller::SomeController
99 $c->forward('MyApp::V::TT');
104 There are a three different ways to configure your view class. The
105 first way is to call the C<config()> method in the view subclass. This
106 happens when the module is first loaded.
108 package MyApp::V::TT;
111 use base 'Catalyst::View::TT';
113 our $ROOT = '/home/dent/catalyst/MyApp';
115 MyApp::V::TT->config({
116 INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
117 PRE_PROCESS => 'config/main',
118 WRAPPER => 'site/wrapper',
121 The second way is to define a C<new()> method in your view subclass.
122 This performs the configuration when the view object is created,
123 shortly after being loaded. Remember to delegate to the base class
124 C<new()> method (via C<$self-E<gt>NEXT::new()> in the example below) after
125 performing any configuration.
130 INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
131 PRE_PROCESS => 'config/main',
132 WRAPPER => 'site/wrapper',
134 return $self->NEXT::new(@_);
137 The final, and perhaps most direct way, is to define a class
138 item in your main application configuration, again by calling the
139 uniquitous C<config()> method. The items in the class hash are
140 added to those already defined by the above two methods. This happens
141 in the base class new() method (which is one reason why you must
142 remember to call it via C<NEXT> if you redefine the C<new()> method in a
150 our $ROOT = '/home/dent/catalyst/MyApp';
156 INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
157 PRE_PROCESS => 'config/main',
158 WRAPPER => 'site/wrapper',
162 Note that any configuration items defined by one of the earlier
163 methods will be overwritten by items of the same name provided by the
166 =head2 RENDERING VIEWS
168 The view plugin renders the template specified in the C<template>
171 sub message : Global {
172 my ( $self, $c ) = @_;
173 $c->stash->{template} = 'message.tt2';
174 $c->forward('MyApp::V::TT');
177 If a class item isn't defined, then it instead uses the
178 current match, as returned by C<$c-E<gt>match>. In the above
179 example, this would be C<message>.
181 The items defined in the stash are passed to the Template Toolkit for
182 use as template variables.
184 sub message : Global {
185 sub default : Private {
186 my ( $self, $c ) = @_;
187 $c->stash->{template} = 'message.tt2';
188 $c->stash->{message} = 'Hello World!';
189 $c->forward('MyApp::V::TT');
192 A number of other template variables are also added:
194 c A reference to the context object, $c
195 base The URL base, from $c->req->base()
196 name The application name, from $c->config->{ name }
198 These can be accessed from the template in the usual way:
202 The message is: [% message %]
203 The base is [% base %]
204 The name is [% name %]
207 The output generated by the template is stored in
208 C<$c-E<gt>response-E<gt>output>.
210 =head2 TEMPLATE PROFILING
218 The constructor for the TT view. Sets up the template provider,
219 and reads the application config.
224 my ( $class, $c, $arguments ) = @_;
226 my $root = $c->config->{root};
230 TEMPLATE_EXTENSION => '',
231 INCLUDE_PATH => [ $root, "$root/base" ],
236 # if we're debugging and/or the TIMER option is set, then we install
237 # Template::Timer as a custom CONTEXT object, but only if we haven't
238 # already got a custom CONTEXT defined
240 if ( $config->{TIMER} ) {
241 if ( $config->{CONTEXT} ) {
243 'Cannot use Template::Timer - a TT CONFIG is already defined');
246 $config->{CONTEXT} = Template::Timer->new(%$config);
250 if ( $c->debug && $config->{DUMP_CONFIG} ) {
252 $c->log->debug( "TT Config: ", Dumper($config) );
255 return $class->NEXT::new(
258 template => Template->new($config) || do {
259 my $error = Template->error();
260 $c->log->error($error);
270 Renders the template specified in C<$c-E<gt>stash-E<gt>{template}> or
271 C<$c-E<gt>request-E<gt>match>. Template variables are set up from the
272 contents of C<$c-E<gt>stash>, augmented with C<base> set to
273 C<$c-E<gt>req-E<gt>base>, C<c> to C<$c> and C<name> to
274 C<$c-E<gt>config-E<gt>{name}>. Alternately, the C<CATALYST_VAR>
275 configuration item can be defined to specify the name of a template
276 variable through which the context reference (C<$c>) can be accessed.
277 In this case, the C<c>, C<base> and C<name> variables are omitted.
278 Output is stored in C<$c-E<gt>response-E<gt>output>.
283 my ( $self, $c ) = @_;
285 my $template = $c->stash->{template} || $c->request->match . $self->config->{TEMPLATE_EXTENSION};
288 $c->log->debug('No template specified for rendering') if $c->debug;
292 $c->log->debug(qq/Rendering template "$template"/) if $c->debug;
295 my $cvar = $self->config->{CATALYST_VAR};
301 base => $c->req->base,
302 name => $c->config->{name}
307 unless ( $self->template->process( $template, $vars, \$output ) ) {
308 my $error = $self->template->error;
309 $error = qq/Couldn't render template "$error"/;
310 $c->log->error($error);
315 unless ( $c->response->content_type ) {
316 $c->response->content_type('text/html; charset=utf-8');
319 $c->response->body($output);
326 This method allows your view subclass to pass additional settings to
327 the TT configuration hash, or to set the options as below:
331 =item C<CATALYST_VAR>
333 Allows you to change the name of the Catalyst context object. If set, it will also
334 remove the base and name aliases, so you will have access them through <context>.
342 CATALYST_VAR => 'Catalyst',
348 The base is [% Catalyst.req.base %]
349 The name is [% Catalyst.config.name %]
353 If you have configured Catalyst for debug output, and turned on the TIMER setting,
354 C<Catalyst::View::TT> will enable profiling of template processing
355 (using L<Template::Timer>). This will embed HTML comments in the
356 output from your templates, such as:
358 <!-- TIMER START: process mainmenu/mainmenu.ttml -->
359 <!-- TIMER START: include mainmenu/cssindex.tt -->
360 <!-- TIMER START: process mainmenu/cssindex.tt -->
361 <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
362 <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
366 <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
369 =item C<TEMPLATE_SUFFIX>
371 a sufix to add when looking for templates bases on the C<match> method in L<Catalyst::Request>.
375 package MyApp::C::Test;
376 sub test : Local { .. }
378 Would by default look for a template in <root>/test/test. If you set TEMPLATE_EXTENSION to '.tt', it will look for
387 The L<Catalyst::Helper::View::TT> and
388 L<Catalyst::Helper::View::TTSite> helper modules are provided to create
389 your view module. There are invoked by the F<myapp_create.pl> script:
391 $ script/myapp_create.pl view TT TT
393 $ script/myapp_create.pl view TT TTSite
395 The L<Catalyst::Helper::View::TT> module creates a basic TT view
396 module. The L<Catalyst::Helper::View::TTSite> module goes a little
397 further. It also creates a default set of templates to get you
398 started. It also configures the view module to locate the templates
403 L<Catalyst>, L<Catalyst::Helper::View::TT>,
404 L<Catalyst::Helper::View::TTSite>, L<Template::Manual>
408 Sebastian Riedel, C<sri@cpan.org>
410 Marcus Ramberg, C<mramberg@cpan.org>
412 Jesse Sheidlower, C<jester@panix.com>
414 Andy Wardley, C<abw@cpan.org>
418 This program is free software, you can redistribute it and/or modify it
419 under the same terms as Perl itself.