lib/Catalyst/View/TT.pm

   1 package Catalyst::View::TT;
   2
   3 use strict;
   4 use base qw/Catalyst::Base/;
   5 use Template;
   6 use Template::Timer;
   7 use NEXT;
   8
   9 our $VERSION = '0.13';
  10
  11 __PACKAGE__->mk_accessors('template');
  12
  13 =head1 NAME
  14
  15 Catalyst::View::TT - Template View Class
  16
  17 =head1 SYNOPSIS
  18
  19     # use the helper
  20     myapp_create.pl view TT TT
  21
  22     # lib/MyApp/View/TT.pm
  23     package MyApp::View::TT;
  24
  25     use base 'Catalyst::View::TT';
  26
  27     __PACKAGE__->config->{DEBUG} = 'all';
  28
  29     # in practice you'd probably set this from a config file;
  30     # defaults to $c->config->root
  31     __PACKAGE__->config->{INCLUDE_PATH} =
  32        '/usr/local/generic/templates:/usr/local/myapp/templates';
  33
  34     1;
  35
  36     # Meanwhile, maybe in a private C<end> action
  37     $c->forward('MyApp::View::TT');
  38
  39
  40 =head1 DESCRIPTION
  41
  42 This is the Catalyst view class for the L<Template
  43 Toolkit|Template>. Your application subclass should inherit from this
  44 class. This plugin renders the template specified in
  45 C<$c-E<gt>stash-E<gt>{template}>, or failing that,
  46 C<$c-E<gt>request-E<gt>match>. The template variables are set up from
  47 the contents of C<$c-E<gt>stash>, augmented with template variable
  48 C<base> set to Catalyst's C<$c-E<gt>req-E<gt>base>, template variable
  49 C<c> to Catalyst's C<$c>, and template variable C<name> to Catalyst's
  50 C<$c-E<gt>config-E<gt>{name}>. The output is stored in
  51 C<$c-E<gt>response-E<gt>output>.
  52
  53 If you want to override TT config settings, you can do it in your
  54 application's view class by setting
  55 C<__PACKAGE__-E<gt>config-E<gt>{OPTION}>, as shown in the Synopsis. Of
  56 interest might be C<EVAL_PERL>, which is disabled by default,
  57 C<INCLUDE_PATH>, and C<LOAD_TEMPLATES>, which is set to use the
  58 provider.
  59
  60 If you want to use C<EVAL_PERL>, add something like this:
  61
  62     __PACKAGE__->config->{EVAL_PERL} = 1;
  63     __PACKAGE__->config->{LOAD_TEMPLATES} = undef;
  64
  65 If you have configured Catalyst for debug output, C<Catalyst::View::TT>
  66 will enable profiling of template processing (using
  67 L<Template::Timer>). This will embed HTML comments in the output from
  68 your templates, such as:
  69
  70     <!-- TIMER START: process mainmenu/mainmenu.ttml -->
  71     <!-- TIMER START: include mainmenu/cssindex.tt -->
  72     <!-- TIMER START: process mainmenu/cssindex.tt -->
  73     <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
  74     <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
  75
  76     ....
  77
  78     <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
  79
  80 You can suppress template profiling when debug is enabled by setting:
  81
  82     __PACKAGE__->config->{CONTEXT} = undef;
  83
  84
  85 =head2 METHODS
  86
  87 =over 4
  88
  89 =item new
  90
  91 The constructor for the TT view. Sets up the template provider,
  92 and reads the application config.
  93
  94 =cut
  95
  96 sub new {
  97     my ( $class, $c, $arguments ) = @_;
  98
  99     my $root = $c->config->{root};
 100
 101     my %config = (
 102         EVAL_PERL    => 0,
 103         INCLUDE_PATH => [ $root, "$root/base" ],
 104         %{ $class->config },
 105         %{ $arguments }
 106     );
 107
 108     if ( $c->debug && not exists $config{CONTEXT} ) {
 109        $config{CONTEXT} = Template::Timer->new(%config);
 110     }
 111
 112     return $class->NEXT::new( $c, { template => Template->new( \%config ) } );
 113 }
 114
 115 =item process
 116
 117 Renders the template specified in C<$c-E<gt>stash-E<gt>{template}> or
 118 C<$c-E<gt>request-E<gt>match>. Template variables are set up from the
 119 contents of C<$c-E<gt>stash>, augmented with C<base> set to
 120 C<$c-E<gt>req-E<gt>base>, C<c> to C<$c> and C<name> to
 121 C<$c-E<gt>config-E<gt>{name}>. Output is stored in
 122 C<$c-E<gt>response-E<gt>output>.
 123
 124 =cut
 125
 126 sub process {
 127     my ( $self, $c ) = @_;
 128
 129     my $template = $c->stash->{template} || $c->request->match;
 130
 131     unless ($template) {
 132         $c->log->debug('No template specified for rendering') if $c->debug;
 133         return 0;
 134     }
 135
 136     $c->log->debug(qq/Rendering template "$template"/) if $c->debug;
 137
 138     my $output;
 139
 140     unless (
 141         $self->template->process(
 142             $template,
 143             {
 144                 base => $c->req->base,
 145                 c    => $c,
 146                 name => $c->config->{name},
 147                 %{ $c->stash }
 148             },
 149             \$output
 150         )
 151       )
 152     {
 153         my $error = $self->template->error;
 154         $error = qq/Couldn't render template "$error"/;
 155         $c->log->error($error);
 156         $c->error($error);
 157         return 0;
 158     }
 159
 160     unless ( $c->response->content_type ) {
 161         $c->response->content_type('text/html; charset=utf-8');
 162     }
 163
 164     $c->response->body($output);
 165
 166     return 1;
 167 }
 168
 169 =item config
 170
 171 This allows your view subclass to pass additional settings to the
 172 TT config hash.
 173
 174 =back
 175
 176 =head1 SEE ALSO
 177
 178 L<Catalyst>, L<Template::Manual>
 179
 180 =head1 AUTHOR
 181
 182 Sebastian Riedel, C<sri@cpan.org>
 183 Marcus Ramberg, C<mramberg@cpan.org>
 184 Jesse Sheidlower, C<jester@panix.com>
 185
 186 =head1 COPYRIGHT
 187
 188 This program is free software, you can redistribute it and/or modify it
 189 under the same terms as Perl itself.
 190
 191 =cut
 192
 193 1;