lib/Catalyst/View/TT.pm

   1 package Catalyst::View::TT;
   2
   3 use strict;
   4 use base qw/Catalyst::View/;
   5 use Template;
   6 use Template::Timer;
   7 use NEXT;
   8
   9 our $VERSION = '0.22';
  10
  11 __PACKAGE__->mk_accessors('template');
  12 __PACKAGE__->mk_accessors('include_path');
  13
  14 =head1 NAME
  15
  16 Catalyst::View::TT - Template View Class
  17
  18 =head1 SYNOPSIS
  19
  20 # use the helper to create View
  21     myapp_create.pl view TT TT
  22
  23 # configure in lib/MyApp.pm
  24
  25     MyApp->config(
  26         name     => 'MyApp',
  27         root     => MyApp->path_to('root');,
  28         'View::TT' => {
  29             # any TT configurations items go here
  30             INCLUDE_PATH => [
  31               MyApp->path_to( 'root', 'src' ),
  32               MyApp->path_to( 'root', 'lib' ),
  33             ],
  34             PRE_PROCESS        => 'config/main',
  35             WRAPPER            => 'site/wrapper',
  36             TEMPLATE_EXTENSION => '.tt',
  37
  38             # two optional config items
  39             CATALYST_VAR => 'Catalyst',
  40             TIMER        => 1,
  41         },
  42     );
  43
  44 # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
  45
  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');
  51     }
  52
  53 # access variables from template
  54
  55     The message is: [% message %].
  56
  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 %]
  61
  62     # example when CATALYST_VAR isn't set
  63     Context is [% c %]
  64     The base is [% base %]
  65     The name is [% name %]
  66
  67 =head1 DESCRIPTION
  68
  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.
  75
  76     $ script/myapp_create.pl view TT TT
  77
  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
  80 something like this:
  81
  82     package FooBar::V::TT;
  83
  84     use strict;
  85      use base 'Catalyst::View::TT';
  86
  87     __PACKAGE__->config->{DEBUG} = 'all';
  88
  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
  92 to the TT view class.
  93
  94     # In MyApp or MyApp::Controller::SomeController
  95
  96     sub end : Private {
  97         my( $self, $c ) = @_;
  98         $c->forward('MyApp::V::TT');
  99     }
 100
 101 =head2 CONFIGURATION
 102
 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.
 106
 107     package MyApp::V::TT;
 108
 109     use strict;
 110     use base 'Catalyst::View::TT';
 111
 112     MyApp::V::TT->config({
 113         INCLUDE_PATH => [
 114             MyApp->path_to( 'root', 'templates', 'lib' ),
 115             MyApp->path_to( 'root', 'templates', 'src' ),
 116         ],
 117         PRE_PROCESS  => 'config/main',
 118         WRAPPER      => 'site/wrapper',
 119     });
 120
 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.
 126
 127     sub new {
 128         my $self = shift;
 129         $self->config({
 130             INCLUDE_PATH => [
 131                 MyApp->path_to( 'root', 'templates', 'lib' ),
 132                 MyApp->path_to( 'root', 'templates', 'src' ),
 133             ],
 134             PRE_PROCESS  => 'config/main',
 135             WRAPPER      => 'site/wrapper',
 136         });
 137         return $self->NEXT::new(@_);
 138     }
 139
 140 The final, and perhaps most direct way, is to define a class
 141 item in your main application configuration, again by calling the
 142 uniquitous C<config()> method.  The items in the class hash are
 143 added to those already defined by the above two methods.  This happens
 144 in the base class new() method (which is one reason why you must
 145 remember to call it via C<NEXT> if you redefine the C<new()> method in a
 146 subclass).
 147
 148     package MyApp;
 149
 150     use strict;
 151     use Catalyst;
 152
 153     MyApp->config({
 154         name     => 'MyApp',
 155         root     => MyApp->path_to('root'),
 156         'V::TT' => {
 157             INCLUDE_PATH => [
 158                 MyApp->path_to( 'root', 'templates', 'lib' ),
 159                 MyApp->path_to( 'root', 'templates', 'src' ),
 160             ],
 161             PRE_PROCESS  => 'config/main',
 162             WRAPPER      => 'site/wrapper',
 163         },
 164     });
 165
 166 Note that any configuration items defined by one of the earlier
 167 methods will be overwritten by items of the same name provided by the
 168 latter methods.
 169
 170 =head2 DYNAMIC INCLUDE_PATH
 171
 172 Sometimes it is desirable to modify INCLUDE_PATH for your templates at run time.
 173
 174 Additional paths can be added to the start of INCLUDE_PATH via the stash as
 175 follows:
 176
 177     $c->stash->{additional_template_paths} =
 178         [$c->config->{root} . '/test_include_path'];
 179
 180 If you need to add paths to the end of INCLUDE_PATH, there is also an
 181 include_path() accessor available:
 182
 183     push( @{ $c->view('TT')->include_path }, qw/path/ );
 184
 185 Note that if you use include_path() to add extra paths to INCLUDE_PATH, you
 186 MUST check for duplicate paths. Without such checking, the above code will add
 187 "path" to INCLUDE_PATH at every request, causing a memory leak.
 188
 189 A safer approach is to use include_path() to overwrite the array of paths
 190 rather than adding to it. This eliminates both the need to perform duplicate
 191 checking and the chance of a memory leak:
 192
 193     @{ $c->view('TT')->include_path } = qw/path another_path/;
 194
 195 If you are calling C<render> directly then you can specify dynamic paths by
 196 having a C<additional_include_paths> key with a value of additonal directories
 197 to search. See L<CAPTURING TEMPLATE OUTPUT> for an example showing this.
 198
 199 =head2 RENDERING VIEWS
 200
 201 The view plugin renders the template specified in the C<template>
 202 item in the stash.
 203
 204     sub message : Global {
 205         my ( $self, $c ) = @_;
 206         $c->stash->{template} = 'message.tt2';
 207         $c->forward('MyApp::V::TT');
 208     }
 209
 210 If a class item isn't defined, then it instead uses the
 211 current match, as returned by C<< $c->match >>.  In the above
 212 example, this would be C<message>.
 213
 214 The items defined in the stash are passed to the Template Toolkit for
 215 use as template variables.
 216
 217     sub default : Private {
 218         my ( $self, $c ) = @_;
 219         $c->stash->{template} = 'message.tt2';
 220         $c->stash->{message}  = 'Hello World!';
 221         $c->forward('MyApp::V::TT');
 222     }
 223
 224 A number of other template variables are also added:
 225
 226     c      A reference to the context object, $c
 227     base   The URL base, from $c->req->base()
 228     name   The application name, from $c->config->{ name }
 229
 230 These can be accessed from the template in the usual way:
 231
 232 <message.tt2>:
 233
 234     The message is: [% message %]
 235     The base is [% base %]
 236     The name is [% name %]
 237
 238
 239 The output generated by the template is stored in C<< $c->response->body >>.
 240
 241 =head2 CAPTURING TEMPLATE OUTPUT
 242
 243 If you wish to use the output of a template for some other purpose than
 244 displaying in the response, e.g. for sending an email, this is possible using
 245 L<Catalyst::Plugin::Email> and the L<render> method:
 246
 247   sub send_email : Local {
 248     my ($self, $c) = @_;
 249
 250     $c->email(
 251       header => [
 252         To      => 'me@localhost',
 253         Subject => 'A TT Email',
 254       ],
 255       body => $c->view('TT')->render($c, 'email.tt', {
 256         additional_include_paths => [ $c->config->{root} . '/email_templates'],
 257         email_tmpl_param1 => 'foo'
 258         }
 259       ),
 260     );
 261   # Redirect or display a message
 262   }
 263
 264 =head2 TEMPLATE PROFILING
 265
 266 See L<C<TIMER>> property of the L<config> method.
 267
 268 =head2 METHODS
 269
 270 =over 4
 271
 272 =item new
 273
 274 The constructor for the TT view. Sets up the template provider,
 275 and reads the application config.
 276
 277 =cut
 278
 279 sub _coerce_paths {
 280     my ( $paths, $dlim ) = shift;
 281     return () if ( !$paths );
 282     return @{$paths} if ( ref $paths eq 'ARRAY' );
 283
 284     # tweak delim to ignore C:/
 285     unless ( defined $dlim ) {
 286         $dlim = ( $^O eq 'MSWin32' ) ? ':(?!\\/)' : ':';
 287     }
 288     return split( /$dlim/, $paths );
 289 }
 290
 291 sub new {
 292     my ( $class, $c, $arguments ) = @_;
 293     my $config = {
 294         EVAL_PERL          => 0,
 295         TEMPLATE_EXTENSION => '',
 296         %{ $class->config },
 297         %{$arguments},
 298     };
 299     if ( !( ref $config->{INCLUDE_PATH} eq 'ARRAY' ) ) {
 300         my $delim = $config->{DELIMITER};
 301         my @include_path = _coerce_paths( $config->{INCLUDE_PATH}, $delim );
 302         if ( !@include_path ) {
 303             my $root = $c->config->{root};
 304             my $base = Path::Class::dir( $root, 'base' );
 305             @include_path = ( "$root", "$base" );
 306         }
 307         $config->{INCLUDE_PATH} = \@include_path;
 308     }
 309
 310     # if we're debugging and/or the TIMER option is set, then we install
 311     # Template::Timer as a custom CONTEXT object, but only if we haven't
 312     # already got a custom CONTEXT defined
 313
 314     if ( $config->{TIMER} ) {
 315         if ( $config->{CONTEXT} ) {
 316             $c->log->error(
 317                 'Cannot use Template::Timer - a TT CONTEXT is already defined'
 318             );
 319         }
 320         else {
 321             $config->{CONTEXT} = Template::Timer->new(%$config);
 322         }
 323     }
 324
 325     if ( $c->debug && $config->{DUMP_CONFIG} ) {
 326         use Data::Dumper;
 327         $c->log->debug( "TT Config: ", Dumper($config) );
 328     }
 329     if ( $config->{PROVIDERS} ) {
 330         my @providers = ();
 331         if ( ref( $config->{PROVIDERS} ) eq 'ARRAY' ) {
 332             foreach my $p ( @{ $config->{PROVIDERS} } ) {
 333                 my $pname = $p->{name};
 334                 eval "require Template::Provider::$pname";
 335                 if ( !$@ ) {
 336                     push @providers,
 337                       "Template::Provider::${pname}"->new( $p->{args} );
 338                 }
 339             }
 340         }
 341         delete $config->{PROVIDERS};
 342         if (@providers) {
 343             $config->{LOAD_TEMPLATES} = \@providers;
 344         }
 345     }
 346
 347     my $self = $class->NEXT::new(
 348         $c,
 349         {
 350             template => Template->new($config) || do {
 351                 my $error = Template->error();
 352                 $c->log->error($error);
 353                 $c->error($error);
 354                 return undef;
 355             },
 356             %{$config},
 357         },
 358     );
 359     $self->include_path( $config->{INCLUDE_PATH} );
 360     $self->config($config);
 361
 362     return $self;
 363 }
 364
 365 =item process
 366
 367 Renders the template specified in C<< $c->stash->{template} >> or
 368 C<< $c->action >> (the private name of the matched action.  Calls L<render> to
 369 perform actual rendering. Output is stored in C<< $c->response->body >>.
 370
 371 =cut
 372
 373 sub process {
 374     my ( $self, $c ) = @_;
 375
 376     my $template = $c->stash->{template}
 377       || $c->action . $self->config->{TEMPLATE_EXTENSION};
 378
 379     unless ($template) {
 380         $c->log->debug('No template specified for rendering') if $c->debug;
 381         return 0;
 382     }
 383
 384     my $output = $self->render( $c, $template );
 385
 386     if ( (Scalar::Util::blessed($output)||'') eq 'Template::Exception' ) {
 387         my $error = qq/Coldn't render template "$output"/;
 388         $c->log->error($error);
 389         $c->error($error);
 390         return 0;
 391     }
 392
 393     unless ( $c->response->content_type ) {
 394         $c->response->content_type('text/html; charset=utf-8');
 395     }
 396
 397     $c->response->body($output);
 398
 399     return 1;
 400 }
 401
 402 =item render($c, $template, \%args)
 403
 404 Renders the given template and returns output, or a L<Template::Exception>
 405 object upon error.
 406
 407 The template variables are set to C<%$args> if $args is a hashref, or
 408 $C<< $c->stash >> otherwise. In either case the variables are augmented with
 409 C<base> set to C< << $c->req->base >>, C<c> to C<$c> and C<name> to
 410 C<< $c->config->{name} >>. Alternately, the C<CATALYST_VAR> configuration item
 411 can be defined to specify the name of a template variable through which the
 412 context reference (C<$c>) can be accessed. In this case, the C<c>, C<base> and
 413 C<name> variables are omitted.
 414
 415 C<$template> can be anything that Template::process understands how to
 416 process, including the name of a template file or a reference to a test string.
 417 See L<Template::process|Template/process> for a full list of supported formats.
 418
 419 =cut
 420
 421 sub render {
 422     my ( $self, $c, $template, $args ) = @_;
 423
 424     $c->log->debug(qq/Rendering template "$template"/) if $c->debug;
 425
 426     my $output;
 427     my $vars = {
 428         ( ref $args eq 'HASH' ? %$args : %{ $c->stash() } ),
 429         $self->template_vars($c)
 430     };
 431
 432     local $self->{include_path} = $self->include_path;
 433     unshift @{ $self->{include_path} }, @{ $vars->{additional_template_paths} }
 434       if ref $c->stash->{additional_template_paths};
 435
 436     unless ( $self->template->process( $template, $vars, \$output ) ) {
 437         return $self->template->error;
 438     }
 439     else {
 440         return $output;
 441     }
 442 }
 443
 444 =item template_vars
 445
 446 Returns a list of keys/values to be used as the catalyst variables in the
 447 template.
 448
 449 =cut
 450
 451 sub template_vars {
 452     my ( $self, $c ) = @_;
 453
 454     my $cvar = $self->config->{CATALYST_VAR};
 455
 456     defined $cvar
 457       ? ( $cvar => $c )
 458       : (
 459         c    => $c,
 460         base => $c->req->base,
 461         name => $c->config->{name}
 462       );
 463 }
 464
 465 =item config
 466
 467 This method allows your view subclass to pass additional settings to
 468 the TT configuration hash, or to set the options as below:
 469
 470 =over 2
 471
 472 =item C<CATALYST_VAR>
 473
 474 Allows you to change the name of the Catalyst context object. If set, it will also
 475 remove the base and name aliases, so you will have access them through <context>.
 476
 477 For example:
 478
 479     MyApp->config({
 480         name     => 'MyApp',
 481         root     => MyApp->path_to('root'),
 482         'V::TT' => {
 483             CATALYST_VAR => 'Catalyst',
 484         },
 485     });
 486
 487 F<message.tt2>:
 488
 489     The base is [% Catalyst.req.base %]
 490     The name is [% Catalyst.config.name %]
 491
 492 =item C<TIMER>
 493
 494 If you have configured Catalyst for debug output, and turned on the TIMER setting,
 495 C<Catalyst::View::TT> will enable profiling of template processing
 496 (using L<Template::Timer>). This will embed HTML comments in the
 497 output from your templates, such as:
 498
 499     <!-- TIMER START: process mainmenu/mainmenu.ttml -->
 500     <!-- TIMER START: include mainmenu/cssindex.tt -->
 501     <!-- TIMER START: process mainmenu/cssindex.tt -->
 502     <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
 503     <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
 504
 505     ....
 506
 507     <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
 508
 509
 510 =item C<TEMPLATE_EXTENSION>
 511
 512 a sufix to add when looking for templates bases on the C<match> method in L<Catalyst::Request>.
 513
 514 For example:
 515
 516   package MyApp::C::Test;
 517   sub test : Local { .. }
 518
 519 Would by default look for a template in <root>/test/test. If you set TEMPLATE_EXTENSION to '.tt', it will look for
 520 <root>/test/test.tt.
 521
 522 =back
 523
 524 =back
 525
 526 =head2 HELPERS
 527
 528 The L<Catalyst::Helper::View::TT> and
 529 L<Catalyst::Helper::View::TTSite> helper modules are provided to create
 530 your view module.  There are invoked by the F<myapp_create.pl> script:
 531
 532     $ script/myapp_create.pl view TT TT
 533
 534     $ script/myapp_create.pl view TT TTSite
 535
 536 The L<Catalyst::Helper::View::TT> module creates a basic TT view
 537 module.  The L<Catalyst::Helper::View::TTSite> module goes a little
 538 further.  It also creates a default set of templates to get you
 539 started.  It also configures the view module to locate the templates
 540 automatically.
 541
 542 =head1 SEE ALSO
 543
 544 L<Catalyst>, L<Catalyst::Helper::View::TT>,
 545 L<Catalyst::Helper::View::TTSite>, L<Template::Manual>
 546
 547 =head1 AUTHORS
 548
 549 Sebastian Riedel, C<sri@cpan.org>
 550
 551 Marcus Ramberg, C<mramberg@cpan.org>
 552
 553 Jesse Sheidlower, C<jester@panix.com>
 554
 555 Andy Wardley, C<abw@cpan.org>
 556
 557 =head1 COPYRIGHT
 558
 559 This program is free software, you can redistribute it and/or modify it
 560 under the same terms as Perl itself.
 561
 562 =cut
 563
 564 1;