local-lib5/man/man3/Catalyst::View::TT.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Catalyst::View::TT 3"
 127 .TH Catalyst::View::TT 3 "2010-04-07" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Catalyst::View::TT \- Template View Class
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 # use the helper to create your View
 137 .PP
 138 .Vb 1
 139 \&    myapp_create.pl view TT TT
 140 .Ve
 141 .PP
 142 # configure in lib/MyApp.pm (Could be set from configfile instead)
 143 .PP
 144 .Vb 10
 145 \&    _\|_PACKAGE_\|_\->config(
 146 \&        name         => \*(AqMyApp\*(Aq,
 147 \&        root         => MyApp\->path_to(\*(Aqroot\*(Aq),
 148 \&        default_view => \*(AqTT\*(Aq,
 149 \&        \*(AqView::TT\*(Aq => {
 150 \&            # any TT configurations items go here
 151 \&            INCLUDE_PATH => [
 152 \&              MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqsrc\*(Aq ),
 153 \&              MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqlib\*(Aq ),
 154 \&            ],
 155 \&            TEMPLATE_EXTENSION => \*(Aq.tt\*(Aq,
 156 \&            CATALYST_VAR => \*(Aqc\*(Aq,
 157 \&            TIMER        => 0,
 158 \&            # Not set by default
 159 \&            PRE_PROCESS        => \*(Aqconfig/main\*(Aq,
 160 \&            WRAPPER            => \*(Aqsite/wrapper\*(Aq,
 161 \&            render_die => 1, # Default for new apps, see render method docs
 162 \&        },
 163 \&    );
 164 .Ve
 165 .PP
 166 # render view from lib/MyApp.pm or lib/MyApp::Controller::SomeController.pm
 167 .PP
 168 .Vb 6
 169 \&    sub message : Global {
 170 \&        my ( $self, $c ) = @_;
 171 \&        $c\->stash\->{template} = \*(Aqmessage.tt2\*(Aq;
 172 \&        $c\->stash\->{message}  = \*(AqHello World!\*(Aq;
 173 \&        $c\->forward( $c\->view(\*(AqTT\*(Aq) );
 174 \&    }
 175 .Ve
 176 .PP
 177 # access variables from template
 178 .PP
 179 .Vb 1
 180 \&    The message is: [% message %].
 181 \&
 182 \&    # example when CATALYST_VAR is set to \*(AqCatalyst\*(Aq
 183 \&    Context is [% Catalyst %]
 184 \&    The base is [% Catalyst.req.base %]
 185 \&    The name is [% Catalyst.config.name %]
 186 \&
 187 \&    # example when CATALYST_VAR isn\*(Aqt set
 188 \&    Context is [% c %]
 189 \&    The base is [% base %]
 190 \&    The name is [% name %]
 191 .Ve
 192 .SH "DESCRIPTION"
 193 .IX Header "DESCRIPTION"
 194 This is the Catalyst view class for the Template Toolkit.
 195 Your application should defined a view class which is a subclass of
 196 this module.  The easiest way to achieve this is using the
 197 \&\fImyapp_create.pl\fR script (where \fImyapp\fR should be replaced with
 198 whatever your application is called).  This script is created as part
 199 of the Catalyst setup.
 200 .PP
 201 .Vb 1
 202 \&    $ script/myapp_create.pl view TT TT
 203 .Ve
 204 .PP
 205 This creates a MyApp::View::TT.pm module in the \fIlib\fR directory (again,
 206 replacing \f(CW\*(C`MyApp\*(C'\fR with the name of your application) which looks
 207 something like this:
 208 .PP
 209 .Vb 1
 210 \&    package FooBar::View::TT;
 211 \&
 212 \&    use strict;
 213 \&    use warnings;
 214 \&
 215 \&    use base \*(AqCatalyst::View::TT\*(Aq;
 216 \&
 217 \&    _\|_PACKAGE_\|_\->config(DEBUG => \*(Aqall\*(Aq);
 218 .Ve
 219 .PP
 220 Now you can modify your action handlers in the main application and/or
 221 controllers to forward to your view class.  You might choose to do this
 222 in the \fIend()\fR method, for example, to automatically forward all actions
 223 to the \s-1TT\s0 view class.
 224 .PP
 225 .Vb 1
 226 \&    # In MyApp or MyApp::Controller::SomeController
 227 \&
 228 \&    sub end : Private {
 229 \&        my( $self, $c ) = @_;
 230 \&        $c\->forward( $c\->view(\*(AqTT\*(Aq) );
 231 \&    }
 232 .Ve
 233 .PP
 234 But if you are using the standard auto-generated end action, you don't even need
 235 to do this!
 236 .PP
 237 .Vb 2
 238 \&    # in MyApp::Controller::Root
 239 \&    sub end : ActionClass(\*(AqRenderView\*(Aq) {} # no need to change this line
 240 \&
 241 \&    # in MyApp.pm
 242 \&    _\|_PACKAGE_\|_\->config(
 243 \&        ...
 244 \&        default_view => \*(AqTT\*(Aq,
 245 \&    );
 246 .Ve
 247 .PP
 248 This will Just Work.  And it has the advantages that:
 249 .IP "\(bu" 4
 250 If you want to use a different view for a given request, just set
 251 << \f(CW$c\fR\->stash\->{current_view} >>.  (See Catalyst's \f(CW\*(C`$c\->view\*(C'\fR method
 252 for details.
 253 .IP "\(bu" 4
 254 << \f(CW$c\fR\->res\->redirect >> is handled by default.  If you just forward to
 255 \&\f(CW\*(C`View::TT\*(C'\fR in your \f(CW\*(C`end\*(C'\fR routine, you could break this by sending additional
 256 content.
 257 .PP
 258 See Catalyst::Action::RenderView for more details.
 259 .SS "\s-1CONFIGURATION\s0"
 260 .IX Subsection "CONFIGURATION"
 261 There are a three different ways to configure your view class.  The
 262 first way is to call the \f(CW\*(C`config()\*(C'\fR method in the view subclass.  This
 263 happens when the module is first loaded.
 264 .PP
 265 .Vb 1
 266 \&    package MyApp::View::TT;
 267 \&
 268 \&    use strict;
 269 \&    use base \*(AqCatalyst::View::TT\*(Aq;
 270 \&
 271 \&    MyApp::View::TT\->config({
 272 \&        INCLUDE_PATH => [
 273 \&            MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqtemplates\*(Aq, \*(Aqlib\*(Aq ),
 274 \&            MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqtemplates\*(Aq, \*(Aqsrc\*(Aq ),
 275 \&        ],
 276 \&        PRE_PROCESS  => \*(Aqconfig/main\*(Aq,
 277 \&        WRAPPER      => \*(Aqsite/wrapper\*(Aq,
 278 \&    });
 279 .Ve
 280 .PP
 281 The second way is to define a \f(CW\*(C`new()\*(C'\fR method in your view subclass.
 282 This performs the configuration when the view object is created,
 283 shortly after being loaded.  Remember to delegate to the base class
 284 \&\f(CW\*(C`new()\*(C'\fR method (via \f(CW\*(C`$self\->next::method()\*(C'\fR in the example below) after
 285 performing any configuration.
 286 .PP
 287 .Vb 12
 288 \&    sub new {
 289 \&        my $self = shift;
 290 \&        $self\->config({
 291 \&            INCLUDE_PATH => [
 292 \&                MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqtemplates\*(Aq, \*(Aqlib\*(Aq ),
 293 \&                MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqtemplates\*(Aq, \*(Aqsrc\*(Aq ),
 294 \&            ],
 295 \&            PRE_PROCESS  => \*(Aqconfig/main\*(Aq,
 296 \&            WRAPPER      => \*(Aqsite/wrapper\*(Aq,
 297 \&        });
 298 \&        return $self\->next::method(@_);
 299 \&    }
 300 .Ve
 301 .PP
 302 The final, and perhaps most direct way, is to define a class
 303 item in your main application configuration, again by calling the
 304 ubiquitous \f(CW\*(C`config()\*(C'\fR method.  The items in the class hash are
 305 added to those already defined by the above two methods.  This happens
 306 in the base class \fInew()\fR method (which is one reason why you must
 307 remember to call it via \f(CW\*(C`MRO::Compat\*(C'\fR if you redefine the \f(CW\*(C`new()\*(C'\fR
 308 method in a subclass).
 309 .PP
 310 .Vb 1
 311 \&    package MyApp;
 312 \&
 313 \&    use strict;
 314 \&    use Catalyst;
 315 \&
 316 \&    MyApp\->config({
 317 \&        name     => \*(AqMyApp\*(Aq,
 318 \&        root     => MyApp\->path_to(\*(Aqroot\*(Aq),
 319 \&        \*(AqView::TT\*(Aq => {
 320 \&            INCLUDE_PATH => [
 321 \&                MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqtemplates\*(Aq, \*(Aqlib\*(Aq ),
 322 \&                MyApp\->path_to( \*(Aqroot\*(Aq, \*(Aqtemplates\*(Aq, \*(Aqsrc\*(Aq ),
 323 \&            ],
 324 \&            PRE_PROCESS  => \*(Aqconfig/main\*(Aq,
 325 \&            WRAPPER      => \*(Aqsite/wrapper\*(Aq,
 326 \&        },
 327 \&    });
 328 .Ve
 329 .PP
 330 Note that any configuration items defined by one of the earlier
 331 methods will be overwritten by items of the same name provided by the
 332 latter methods.
 333 .SS "\s-1DYNAMIC\s0 \s-1INCLUDE_PATH\s0"
 334 .IX Subsection "DYNAMIC INCLUDE_PATH"
 335 Sometimes it is desirable to modify \s-1INCLUDE_PATH\s0 for your templates at run time.
 336 .PP
 337 Additional paths can be added to the start of \s-1INCLUDE_PATH\s0 via the stash as
 338 follows:
 339 .PP
 340 .Vb 2
 341 \&    $c\->stash\->{additional_template_paths} =
 342 \&        [$c\->config\->{root} . \*(Aq/test_include_path\*(Aq];
 343 .Ve
 344 .PP
 345 If you need to add paths to the end of \s-1INCLUDE_PATH\s0, there is also an
 346 \&\fIinclude_path()\fR accessor available:
 347 .PP
 348 .Vb 1
 349 \&    push( @{ $c\->view(\*(AqTT\*(Aq)\->include_path }, qw/path/ );
 350 .Ve
 351 .PP
 352 Note that if you use \fIinclude_path()\fR to add extra paths to \s-1INCLUDE_PATH\s0, you
 353 \&\s-1MUST\s0 check for duplicate paths. Without such checking, the above code will add
 354 \&\*(L"path\*(R" to \s-1INCLUDE_PATH\s0 at every request, causing a memory leak.
 355 .PP
 356 A safer approach is to use \fIinclude_path()\fR to overwrite the array of paths
 357 rather than adding to it. This eliminates both the need to perform duplicate
 358 checking and the chance of a memory leak:
 359 .PP
 360 .Vb 1
 361 \&    @{ $c\->view(\*(AqTT\*(Aq)\->include_path } = qw/path another_path/;
 362 .Ve
 363 .PP
 364 If you are calling \f(CW\*(C`render\*(C'\fR directly then you can specify dynamic paths by
 365 having a \f(CW\*(C`additional_template_paths\*(C'\fR key with a value of additonal directories
 366 to search. See \*(L"\s-1CAPTURING\s0 \s-1TEMPLATE\s0 \s-1OUTPUT\s0\*(R" for an example showing this.
 367 .SS "\s-1RENDERING\s0 \s-1VIEWS\s0"
 368 .IX Subsection "RENDERING VIEWS"
 369 The view plugin renders the template specified in the \f(CW\*(C`template\*(C'\fR
 370 item in the stash.
 371 .PP
 372 .Vb 5
 373 \&    sub message : Global {
 374 \&        my ( $self, $c ) = @_;
 375 \&        $c\->stash\->{template} = \*(Aqmessage.tt2\*(Aq;
 376 \&        $c\->forward( $c\->view(\*(AqTT\*(Aq) );
 377 \&    }
 378 .Ve
 379 .PP
 380 If a stash item isn't defined, then it instead uses the
 381 stringification of the action dispatched to (as defined by \f(CW$c\fR\->action)
 382 in the above example, this would be \f(CW\*(C`message\*(C'\fR, but because the default
 383 is to append '.tt', it would load \f(CW\*(C`root/message.tt\*(C'\fR.
 384 .PP
 385 The items defined in the stash are passed to the Template Toolkit for
 386 use as template variables.
 387 .PP
 388 .Vb 6
 389 \&    sub default : Private {
 390 \&        my ( $self, $c ) = @_;
 391 \&        $c\->stash\->{template} = \*(Aqmessage.tt2\*(Aq;
 392 \&        $c\->stash\->{message}  = \*(AqHello World!\*(Aq;
 393 \&        $c\->forward( $c\->view(\*(AqTT\*(Aq) );
 394 \&    }
 395 .Ve
 396 .PP
 397 A number of other template variables are also added:
 398 .PP
 399 .Vb 3
 400 \&    c      A reference to the context object, $c
 401 \&    base   The URL base, from $c\->req\->base()
 402 \&    name   The application name, from $c\->config\->{ name }
 403 .Ve
 404 .PP
 405 These can be accessed from the template in the usual way:
 406 .PP
 407 <message.tt2>:
 408 .PP
 409 .Vb 3
 410 \&    The message is: [% message %]
 411 \&    The base is [% base %]
 412 \&    The name is [% name %]
 413 .Ve
 414 .PP
 415 The output generated by the template is stored in \f(CW\*(C`$c\->response\->body\*(C'\fR.
 416 .SS "\s-1CAPTURING\s0 \s-1TEMPLATE\s0 \s-1OUTPUT\s0"
 417 .IX Subsection "CAPTURING TEMPLATE OUTPUT"
 418 If you wish to use the output of a template for some other purpose than
 419 displaying in the response, e.g. for sending an email, this is possible using
 420 Catalyst::Plugin::Email and the render method:
 421 .PP
 422 .Vb 2
 423 \&  sub send_email : Local {
 424 \&    my ($self, $c) = @_;
 425 \&
 426 \&    $c\->email(
 427 \&      header => [
 428 \&        To      => \*(Aqme@localhost\*(Aq,
 429 \&        Subject => \*(AqA TT Email\*(Aq,
 430 \&      ],
 431 \&      body => $c\->view(\*(AqTT\*(Aq)\->render($c, \*(Aqemail.tt\*(Aq, {
 432 \&        additional_template_paths => [ $c\->config\->{root} . \*(Aq/email_templates\*(Aq],
 433 \&        email_tmpl_param1 => \*(Aqfoo\*(Aq
 434 \&        }
 435 \&      ),
 436 \&    );
 437 \&  # Redirect or display a message
 438 \&  }
 439 .Ve
 440 .SS "\s-1TEMPLATE\s0 \s-1PROFILING\s0"
 441 .IX Subsection "TEMPLATE PROFILING"
 442 See \f(CW\*(C`TIMER\*(C'\fR property of the config method.
 443 .SS "\s-1METHODS\s0"
 444 .IX Subsection "METHODS"
 445 .SS "new"
 446 .IX Subsection "new"
 447 The constructor for the \s-1TT\s0 view. Sets up the template provider,
 448 and reads the application config.
 449 .SS "process($c)"
 450 .IX Subsection "process($c)"
 451 Renders the template specified in \f(CW\*(C`$c\->stash\->{template}\*(C'\fR or
 452 \&\f(CW\*(C`$c\->action\*(C'\fR (the private name of the matched action).  Calls render to
 453 perform actual rendering. Output is stored in \f(CW\*(C`$c\->response\->body\*(C'\fR.
 454 .PP
 455 It is possible to forward to the process method of a \s-1TT\s0 view from inside
 456 Catalyst like this:
 457 .PP
 458 .Vb 1
 459 \&    $c\->forward(\*(AqView::TT\*(Aq);
 460 .Ve
 461 .PP
 462 N.B. This is usually done automatically by Catalyst::Action::RenderView.
 463 .ie n .SS "render($c, $template, \e%args)"
 464 .el .SS "render($c, \f(CW$template\fP, \e%args)"
 465 .IX Subsection "render($c, $template, %args)"
 466 Renders the given template and returns output. Throws a Template::Exception
 467 object upon error.
 468 .PP
 469 The template variables are set to \f(CW%$args\fR if \f(CW$args\fR is a hashref, or
 470 $\f(CW\*(C`$c\->stash\*(C'\fR otherwise. In either case the variables are augmented with
 471 \&\f(CW\*(C`base\*(C'\fR set to \f(CW\*(C` << $c\-\*(C'\fRreq\->base >>, \f(CW\*(C`c\*(C'\fR to \f(CW$c\fR and \f(CW\*(C`name\*(C'\fR to
 472 \&\f(CW\*(C`$c\->config\->{name}\*(C'\fR. Alternately, the \f(CW\*(C`CATALYST_VAR\*(C'\fR configuration item
 473 can be defined to specify the name of a template variable through which the
 474 context reference (\f(CW$c\fR) can be accessed. In this case, the \f(CW\*(C`c\*(C'\fR, \f(CW\*(C`base\*(C'\fR and
 475 \&\f(CW\*(C`name\*(C'\fR variables are omitted.
 476 .PP
 477 \&\f(CW$template\fR can be anything that Template::process understands how to
 478 process, including the name of a template file or a reference to a test string.
 479 See Template::process for a full list of supported formats.
 480 .PP
 481 To use the render method outside of your Catalyst app, just pass a undef context.
 482 This can be useful for tests, for instance.
 483 .PP
 484 It is possible to forward to the render method of a \s-1TT\s0 view from inside Catalyst
 485 to render page fragments like this:
 486 .PP
 487 .Vb 1
 488 \&    my $fragment = $c\->forward("View::TT", "render", $template_name, $c\->stash\->{fragment_data});
 489 .Ve
 490 .PP
 491 \fIBackwards compatibility note\fR
 492 .IX Subsection "Backwards compatibility note"
 493 .PP
 494 The render method used to just return the Template::Exception object, rather
 495 than just throwing it. This is now deprecated and instead the render method
 496 will throw an exception for new applications.
 497 .PP
 498 This behaviour can be activated (and is activated in the default skeleton
 499 configuration) by using \f(CW\*(C`render_die => 1\*(C'\fR. If you rely on the legacy
 500 behaviour then a warning will be issued.
 501 .PP
 502 To silence this warning, set \f(CW\*(C`render_die => 0\*(C'\fR, but it is recommended
 503 you adjust your code so that it works with \f(CW\*(C`render_die => 1\*(C'\fR.
 504 .PP
 505 In a future release, \f(CW\*(C`render_die => 1\*(C'\fR will become the default if
 506 unspecified.
 507 .SS "template_vars"
 508 .IX Subsection "template_vars"
 509 Returns a list of keys/values to be used as the catalyst variables in the
 510 template.
 511 .SS "config"
 512 .IX Subsection "config"
 513 This method allows your view subclass to pass additional settings to
 514 the \s-1TT\s0 configuration hash, or to set the options as below:
 515 .SS "paths"
 516 .IX Subsection "paths"
 517 The list of paths \s-1TT\s0 will look for templates in.
 518 .ie n .SS """CATALYST_VAR"""
 519 .el .SS "\f(CWCATALYST_VAR\fP"
 520 .IX Subsection "CATALYST_VAR"
 521 Allows you to change the name of the Catalyst context object. If set, it will also
 522 remove the base and name aliases, so you will have access them through <context>.
 523 .PP
 524 For example:
 525 .PP
 526 .Vb 7
 527 \&    MyApp\->config({
 528 \&        name     => \*(AqMyApp\*(Aq,
 529 \&        root     => MyApp\->path_to(\*(Aqroot\*(Aq),
 530 \&        \*(AqView::TT\*(Aq => {
 531 \&            CATALYST_VAR => \*(AqCatalyst\*(Aq,
 532 \&        },
 533 \&    });
 534 .Ve
 535 .PP
 536 \&\fImessage.tt2\fR:
 537 .PP
 538 .Vb 2
 539 \&    The base is [% Catalyst.req.base %]
 540 \&    The name is [% Catalyst.config.name %]
 541 .Ve
 542 .ie n .SS """TIMER"""
 543 .el .SS "\f(CWTIMER\fP"
 544 .IX Subsection "TIMER"
 545 If you have configured Catalyst for debug output, and turned on the \s-1TIMER\s0 setting,
 546 \&\f(CW\*(C`Catalyst::View::TT\*(C'\fR will enable profiling of template processing
 547 (using Template::Timer). This will embed \s-1HTML\s0 comments in the
 548 output from your templates, such as:
 549 .PP
 550 .Vb 5
 551 \&    <!\-\- TIMER START: process mainmenu/mainmenu.ttml \-\->
 552 \&    <!\-\- TIMER START: include mainmenu/cssindex.tt \-\->
 553 \&    <!\-\- TIMER START: process mainmenu/cssindex.tt \-\->
 554 \&    <!\-\- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) \-\->
 555 \&    <!\-\- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) \-\->
 556 \&
 557 \&    ....
 558 \&
 559 \&    <!\-\- TIMER END: process mainmenu/footer.tt (0.003016 seconds) \-\->
 560 .Ve
 561 .ie n .SS """TEMPLATE_EXTENSION"""
 562 .el .SS "\f(CWTEMPLATE_EXTENSION\fP"
 563 .IX Subsection "TEMPLATE_EXTENSION"
 564 a sufix to add when looking for templates bases on the \f(CW\*(C`match\*(C'\fR method in Catalyst::Request.
 565 .PP
 566 For example:
 567 .PP
 568 .Vb 2
 569 \&  package MyApp::Controller::Test;
 570 \&  sub test : Local { .. }
 571 .Ve
 572 .PP
 573 Would by default look for a template in <root>/test/test. If you set \s-1TEMPLATE_EXTENSION\s0 to '.tt', it will look for
 574 <root>/test/test.tt.
 575 .ie n .SS """PROVIDERS"""
 576 .el .SS "\f(CWPROVIDERS\fP"
 577 .IX Subsection "PROVIDERS"
 578 Allows you to specify the template providers that \s-1TT\s0 will use.
 579 .PP
 580 .Vb 10
 581 \&    MyApp\->config({
 582 \&        name     => \*(AqMyApp\*(Aq,
 583 \&        root     => MyApp\->path_to(\*(Aqroot\*(Aq),
 584 \&        \*(AqView::TT\*(Aq => {
 585 \&            PROVIDERS => [
 586 \&                {
 587 \&                    name    => \*(AqDBI\*(Aq,
 588 \&                    args    => {
 589 \&                        DBI_DSN => \*(Aqdbi:DB2:books\*(Aq,
 590 \&                        DBI_USER=> \*(Aqfoo\*(Aq
 591 \&                    }
 592 \&                }, {
 593 \&                    name    => \*(Aq_file_\*(Aq,
 594 \&                    args    => {}
 595 \&                }
 596 \&            ]
 597 \&        },
 598 \&    });
 599 .Ve
 600 .PP
 601 The 'name' key should correspond to the class name of the provider you
 602 want to use.  The _file_ name is a special case that represents the default
 603 \&\s-1TT\s0 file-based provider.  By default the name is will be prefixed with
 604 \&'Template::Provider::'.  You can fully qualify the name by using a unary
 605 plus:
 606 .PP
 607 .Vb 1
 608 \&    name => \*(Aq+MyApp::Provider::Foo\*(Aq
 609 .Ve
 610 .PP
 611 You can also specify the 'copy_config' key as an arrayref, to copy those keys
 612 from the general config, into the config for the provider:
 613 .PP
 614 .Vb 7
 615 \&    DEFAULT_ENCODING    => \*(Aqutf\-8\*(Aq,
 616 \&    PROVIDERS => [
 617 \&        {
 618 \&            name    => \*(AqEncoding\*(Aq,
 619 \&            copy_config => [qw(DEFAULT_ENCODING INCLUDE_PATH)]
 620 \&        }
 621 \&    ]
 622 .Ve
 623 .PP
 624 This can prove useful when you want to use the additional_template_paths hack
 625 in your own provider, or if you need to use Template::Provider::Encoding
 626 .SS "\s-1HELPERS\s0"
 627 .IX Subsection "HELPERS"
 628 The Catalyst::Helper::View::TT and
 629 Catalyst::Helper::View::TTSite helper modules are provided to create
 630 your view module.  There are invoked by the \fImyapp_create.pl\fR script:
 631 .PP
 632 .Vb 1
 633 \&    $ script/myapp_create.pl view TT TT
 634 \&
 635 \&    $ script/myapp_create.pl view TT TTSite
 636 .Ve
 637 .PP
 638 The Catalyst::Helper::View::TT module creates a basic \s-1TT\s0 view
 639 module.  The Catalyst::Helper::View::TTSite module goes a little
 640 further.  It also creates a default set of templates to get you
 641 started.  It also configures the view module to locate the templates
 642 automatically.
 643 .SH "NOTES"
 644 .IX Header "NOTES"
 645 If you are using the \s-1CGI\s0 module inside your templates, you will
 646 experience that the Catalyst server appears to hang while rendering
 647 the web page. This is due to the debug mode of \s-1CGI\s0 (which is
 648 waiting for input in the terminal window). Turning off the
 649 debug mode using the \*(L"\-no_debug\*(R" option solves the
 650 problem, eg.:
 651 .PP
 652 .Vb 1
 653 \&    [% USE CGI(\*(Aq\-no_debug\*(Aq) %]
 654 .Ve
 655 .SH "SEE ALSO"
 656 .IX Header "SEE ALSO"
 657 Catalyst, Catalyst::Helper::View::TT,
 658 Catalyst::Helper::View::TTSite, Template::Manual
 659 .SH "AUTHORS"
 660 .IX Header "AUTHORS"
 661 Sebastian Riedel, \f(CW\*(C`sri@cpan.org\*(C'\fR
 662 .PP
 663 Marcus Ramberg, \f(CW\*(C`mramberg@cpan.org\*(C'\fR
 664 .PP
 665 Jesse Sheidlower, \f(CW\*(C`jester@panix.com\*(C'\fR
 666 .PP
 667 Andy Wardley, \f(CW\*(C`abw@cpan.org\*(C'\fR
 668 .SH "COPYRIGHT"
 669 .IX Header "COPYRIGHT"
 670 This program is free software. You can redistribute it and/or modify it
 671 under the same terms as Perl itself.