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.12';
  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     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     1;
  30
  31     # Meanwhile, maybe in an '!end' action
  32     $c->forward('MyApp::View::TT');
  33
  34
  35 =head1 DESCRIPTION
  36
  37 This is the C<Template> view class. Your subclass should inherit from this
  38 class.  The plugin renders the template specified in C<< $c->stash->{template} >>
  39 or C<< $c->request->match >>.  The template variables are set up from the
  40 contents of C<< $c->stash >>, augmented with C<base> set to C<< $c->req->base >>,
  41 C<c> to C<$c> and C<name> to C<< $c->config->{name} >>.  The output is
  42 stored in C<< $c->response->output >>.
  43
  44
  45 If you want to override TT config settings, you can do it there by setting
  46 C<< __PACKAGE__->config->{OPTION} >> as shown in the synopsis. Of interest might be
  47 C<EVAL_PERL>, which is disabled by default, and C<LOAD_TEMPLATES>, which is set to
  48 use the provider.
  49
  50 If you want to use EVAL perl, add something like this:
  51
  52     __PACKAGE__->config->{EVAL_PERL} = 1;
  53     __PACKAGE__->config->{LOAD_TEMPLATES} = undef;
  54
  55 If you have configured Catalyst for debug output C<Catalyst::View::TT> will
  56 enable profiling of template processing (using C<Template::Timer>.  This will cause
  57 HTML comments will get embedded in the output from your templates, such as:
  58
  59     <!-- TIMER START: process mainmenu/mainmenu.ttml -->
  60     <!-- TIMER START: include mainmenu/cssindex.tt -->
  61     <!-- TIMER START: process mainmenu/cssindex.tt -->
  62     <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
  63     <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
  64
  65     ....
  66
  67     <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
  68
  69 You can supress template profiling when debug is enabled by setting:
  70
  71     __PACKAGE__->config->{CONTEXT} = undef;
  72
  73
  74 =head2 METHODS
  75
  76 =over 4
  77
  78 =item new
  79
  80 The constructor for the TT view. Sets up the template provider,
  81 and reads the application config.
  82
  83 =cut
  84
  85 sub new {
  86     my $self = shift;
  87     my $c    = shift;
  88     $self = $self->NEXT::new(@_);
  89     my $root   = $c->config->{root};
  90     my %config = (
  91         EVAL_PERL    => 0,
  92         INCLUDE_PATH => [ $root, "$root/base" ],
  93         %{ $self->config() }
  94     );
  95
  96     if ( $c->debug && not exists $config{CONTEXT} ) {
  97        $config{CONTEXT} = Template::Timer->new(%config);
  98     }
  99
 100     $self->template( Template->new( \%config ) );
 101     return $self;
 102 }
 103
 104 =item process
 105
 106 Renders the template specified in C<< $c->stash->{template} >> or C<<
 107 $c->request->match >>.
 108 Template variables are set up from the contents of C<< $c->stash >>,
 109 Jaugmented with C<base> set to C<< $c->req->base >>, C<c> to C<$c> and
 110 C<name> to C<< $c->config->{name} >>.  Output is stored in
 111 C<< $c->response->output >>.
 112
 113 =cut
 114
 115 sub process {
 116     my ( $self, $c ) = @_;
 117
 118     my $template = $c->stash->{template} || $c->request->match;
 119
 120     unless ($template) {
 121         $c->log->debug('No template specified for rendering') if $c->debug;
 122         return 0;
 123     }
 124
 125     $c->log->debug(qq/Rendering template "$template"/) if $c->debug;
 126
 127     my $output;
 128
 129     unless (
 130         $self->template->process(
 131             $template,
 132             {
 133                 base => $c->req->base,
 134                 c    => $c,
 135                 name => $c->config->{name},
 136                 %{ $c->stash }
 137             },
 138             \$output
 139         )
 140       )
 141     {
 142         my $error = $self->template->error;
 143         $error = qq/Couldn't render template "$error"/;
 144         $c->log->error($error);
 145         $c->error($error);
 146         return 0;
 147     }
 148
 149     unless ( $c->response->content_type ) {
 150         $c->response->content_type('text/html; charset=utf-8');
 151     }
 152
 153     $c->response->body($output);
 154
 155     return 1;
 156 }
 157
 158 =item config
 159
 160 This allows your view subclass to pass additional settings to the
 161 TT config hash.
 162
 163 =back
 164
 165 =head1 SEE ALSO
 166
 167 L<Catalyst>. L<Template::Manual>
 168
 169 =head1 AUTHOR
 170
 171 Sebastian Riedel, C<sri@cpan.org>
 172 Marcus Ramberg, C<mramberg@cpan.org>
 173
 174 =head1 COPYRIGHT
 175
 176 This program is free software, you can redistribute it and/or modify it
 177 under the same terms as Perl itself.
 178
 179 =cut
 180
 181 1;