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.10';
  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     $c->res->headers->content_type('text/html; charset=utf-8')
 118     unless $c->res->headers->content_type();
 119     my $output;
 120     my $name = $c->stash->{template} || $c->req->match;
 121     unless ($name) {
 122         $c->log->debug('No template specified for rendering') if $c->debug;
 123         return 0;
 124     }
 125     $c->log->debug(qq/Rendering template "$name"/) if $c->debug;
 126     unless (
 127         $self->template->process(
 128             $name,
 129             {
 130                 base => $c->req->base,
 131                 c    => $c,
 132                 name => $c->config->{name},
 133                 %{ $c->stash }
 134             },
 135             \$output
 136         )
 137       )
 138     {
 139         my $error = $self->template->error;
 140         $error = qq/Couldn't render template "$error"/;
 141         $c->log->error($error);
 142         $c->error($error);
 143     }
 144     $c->res->output($output);
 145     return 1;
 146 }
 147
 148 =item config
 149
 150 This allows your view subclass to pass additional settings to the
 151 TT config hash.
 152
 153 =back
 154
 155 =head1 SEE ALSO
 156
 157 L<Catalyst>. L<Template::Manual>
 158
 159 =head1 AUTHOR
 160
 161 Sebastian Riedel, C<sri@cpan.org>
 162 Marcus Ramberg, C<mramberg@cpan.org>
 163
 164 =head1 COPYRIGHT
 165
 166 This program is free software, you can redistribute it and/or modify it
 167 under the same terms as Perl itself.
 168
 169 =cut
 170
 171 1;