README

   1 NAME
   2     Catalyst::View::TT - Template View Class
   3
   4 SYNOPSIS
   5     # use the helper to create View myapp_create.pl view TT TT
   6
   7     # configure in lib/MyApp.pm
   8
   9         MyApp->config({
  10             name     => 'MyApp',
  11             root     => MyApp->path_to('root');,
  12             'V::TT' => {
  13                 # any TT configurations items go here
  14                 INCLUDE_PATH => [
  15                   MyApp->path_to( 'root', 'src' ),
  16                   MyApp->path_to( 'root', 'lib' ),
  17                 ],
  18                 PRE_PROCESS        => 'config/main',
  19                 WRAPPER            => 'site/wrapper',
  20                 TEMPLATE_EXTENSION => '.tt',
  21
  22                 # two optional config items
  23                 CATALYST_VAR => 'Catalyst',
  24                 TIMER        => 1,
  25             },
  26         });
  27
  28     # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
  29
  30         sub message : Global {
  31             my ( $self, $c ) = @_;
  32             $c->stash->{template} = 'message.tt2';
  33             $c->stash->{message}  = 'Hello World!';
  34             $c->forward('MyApp::V::TT');
  35         }
  36
  37     # access variables from template
  38
  39         The message is: [% message %].
  40
  41         # example when CATALYST_VAR is set to 'Catalyst'
  42         Context is [% Catalyst %]
  43         The base is [% Catalyst.req.base %]
  44         The name is [% Catalyst.config.name %]
  45
  46         # example when CATALYST_VAR isn't set
  47         Context is [% c %]
  48         The base is [% base %]
  49         The name is [% name %]
  50
  51 DESCRIPTION
  52     This is the Catalyst view class for the Template Toolkit. Your
  53     application should defined a view class which is a subclass of this
  54     module. The easiest way to achieve this is using the myapp_create.pl
  55     script (where myapp should be replaced with whatever your application is
  56     called). This script is created as part of the Catalyst setup.
  57
  58         $ script/myapp_create.pl view TT TT
  59
  60     This creates a MyApp::V::TT.pm module in the lib directory (again,
  61     replacing "MyApp" with the name of your application) which looks
  62     something like this:
  63
  64         package FooBar::V::TT;
  65
  66         use strict;
  67          use base 'Catalyst::View::TT';
  68
  69         __PACKAGE__->config->{DEBUG} = 'all';
  70
  71     Now you can modify your action handlers in the main application and/or
  72     controllers to forward to your view class. You might choose to do this
  73     in the end() method, for example, to automatically forward all actions
  74     to the TT view class.
  75
  76         # In MyApp or MyApp::Controller::SomeController
  77
  78         sub end : Private {
  79             my( $self, $c ) = @_;
  80             $c->forward('MyApp::V::TT');
  81         }
  82
  83   CONFIGURATION
  84     There are a three different ways to configure your view class. The first
  85     way is to call the "config()" method in the view subclass. This happens
  86     when the module is first loaded.
  87
  88         package MyApp::V::TT;
  89
  90         use strict;
  91         use base 'Catalyst::View::TT';
  92
  93         MyApp::V::TT->config({
  94             INCLUDE_PATH => [
  95                 MyApp->path_to( 'root', 'templates', 'lib' ),
  96                 MyApp->path_to( 'root', 'templates', 'src' ),
  97             ],
  98             PRE_PROCESS  => 'config/main',
  99             WRAPPER      => 'site/wrapper',
 100         });
 101
 102     The second way is to define a "new()" method in your view subclass. This
 103     performs the configuration when the view object is created, shortly
 104     after being loaded. Remember to delegate to the base class "new()"
 105     method (via "$self->NEXT::new()" in the example below) after performing
 106     any configuration.
 107
 108         sub new {
 109             my $self = shift;
 110             $self->config({
 111                 INCLUDE_PATH => [
 112                     MyApp->path_to( 'root', 'templates', 'lib' ),
 113                     MyApp->path_to( 'root', 'templates', 'src' ),
 114                 ],
 115                 PRE_PROCESS  => 'config/main',
 116                 WRAPPER      => 'site/wrapper',
 117             });
 118             return $self->NEXT::new(@_);
 119         }
 120
 121     The final, and perhaps most direct way, is to define a class item in
 122     your main application configuration, again by calling the uniquitous
 123     "config()" method. The items in the class hash are added to those
 124     already defined by the above two methods. This happens in the base class
 125     new() method (which is one reason why you must remember to call it via
 126     "NEXT" if you redefine the "new()" method in a subclass).
 127
 128         package MyApp;
 129
 130         use strict;
 131         use Catalyst;
 132
 133         MyApp->config({
 134             name     => 'MyApp',
 135             root     => MyApp->path_to('root'),
 136             'V::TT' => {
 137                 INCLUDE_PATH => [
 138                     MyApp->path_to( 'root', 'templates', 'lib' ),
 139                     MyApp->path_to( 'root', 'templates', 'src' ),
 140                 ],
 141                 PRE_PROCESS  => 'config/main',
 142                 WRAPPER      => 'site/wrapper',
 143             },
 144         });
 145
 146     Note that any configuration items defined by one of the earlier methods
 147     will be overwritten by items of the same name provided by the latter
 148     methods.
 149
 150   DYNAMIC INCLUDE_PATH
 151     It is sometimes needed to dynamically add additional paths to the
 152     INCLUDE_PATH variable of the template object. This can be done by
 153     setting 'additional_include_paths' on stash to a referrence to an array
 154     with additional paths:
 155
 156         $c->stash->{additional_template_paths} = [$c->config->{root} . '/test_include_path'];
 157
 158   RENDERING VIEWS
 159     The view plugin renders the template specified in the "template" item in
 160     the stash.
 161
 162         sub message : Global {
 163             my ( $self, $c ) = @_;
 164             $c->stash->{template} = 'message.tt2';
 165             $c->forward('MyApp::V::TT');
 166         }
 167
 168     If a class item isn't defined, then it instead uses the current match,
 169     as returned by "$c->match". In the above example, this would be
 170     "message".
 171
 172     The items defined in the stash are passed to the Template Toolkit for
 173     use as template variables.
 174
 175     sub message : Global { sub default : Private { my ( $self, $c ) = @_;
 176     $c->stash->{template} = 'message.tt2'; $c->stash->{message} = 'Hello
 177     World!'; $c->forward('MyApp::V::TT'); }
 178
 179     A number of other template variables are also added:
 180
 181         c      A reference to the context object, $c
 182         base   The URL base, from $c->req->base()
 183         name   The application name, from $c->config->{ name }
 184
 185     These can be accessed from the template in the usual way:
 186
 187     <message.tt2>:
 188
 189         The message is: [% message %]
 190         The base is [% base %]
 191         The name is [% name %]
 192
 193     The output generated by the template is stored in
 194     "$c->response->output".
 195
 196   TEMPLATE PROFILING
 197   METHODS
 198     new The constructor for the TT view. Sets up the template provider, and
 199         reads the application config.
 200
 201     process
 202         Renders the template specified in "$c->stash->{template}" or
 203         "$c->request->match". Template variables are set up from the
 204         contents of "$c->stash", augmented with "base" set to
 205         "$c->req->base", "c" to $c and "name" to "$c->config->{name}".
 206         Alternately, the "CATALYST_VAR" configuration item can be defined to
 207         specify the name of a template variable through which the context
 208         reference ($c) can be accessed. In this case, the "c", "base" and
 209         "name" variables are omitted. Output is stored in
 210         "$c->response->output".
 211
 212     config
 213         This method allows your view subclass to pass additional settings to
 214         the TT configuration hash, or to set the options as below:
 215
 216         "CATALYST_VAR"
 217           Allows you to change the name of the Catalyst context object. If
 218           set, it will also remove the base and name aliases, so you will
 219           have access them through <context>.
 220
 221           For example:
 222
 223               MyApp->config({
 224                   name     => 'MyApp',
 225                   root     => MyApp->path_to('root'),
 226                   'V::TT' => {
 227                       CATALYST_VAR => 'Catalyst',
 228                   },
 229               });
 230
 231           message.tt2:
 232
 233               The base is [% Catalyst.req.base %]
 234               The name is [% Catalyst.config.name %]
 235
 236         "TIMER"
 237           If you have configured Catalyst for debug output, and turned on
 238           the TIMER setting, "Catalyst::View::TT" will enable profiling of
 239           template processing (using Template::Timer). This will embed HTML
 240           comments in the output from your templates, such as:
 241
 242               <!-- TIMER START: process mainmenu/mainmenu.ttml -->
 243               <!-- TIMER START: include mainmenu/cssindex.tt -->
 244               <!-- TIMER START: process mainmenu/cssindex.tt -->
 245               <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
 246               <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
 247
 248               ....
 249
 250               <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
 251
 252         "TEMPLATE_EXTENSION"
 253           a sufix to add when looking for templates bases on the "match"
 254           method in Catalyst::Request.
 255
 256           For example:
 257
 258             package MyApp::C::Test;
 259             sub test : Local { .. }
 260
 261           Would by default look for a template in <root>/test/test. If you
 262           set TEMPLATE_EXTENSION to '.tt', it will look for
 263           <root>/test/test.tt.
 264
 265   HELPERS
 266     The Catalyst::Helper::View::TT and Catalyst::Helper::View::TTSite helper
 267     modules are provided to create your view module. There are invoked by
 268     the myapp_create.pl script:
 269
 270         $ script/myapp_create.pl view TT TT
 271
 272         $ script/myapp_create.pl view TT TTSite
 273
 274     The Catalyst::Helper::View::TT module creates a basic TT view module.
 275     The Catalyst::Helper::View::TTSite module goes a little further. It also
 276     creates a default set of templates to get you started. It also
 277     configures the view module to locate the templates automatically.
 278
 279 SEE ALSO
 280     Catalyst, Catalyst::Helper::View::TT, Catalyst::Helper::View::TTSite,
 281     Template::Manual
 282
 283 AUTHORS
 284     Sebastian Riedel, "sri@cpan.org"
 285
 286     Marcus Ramberg, "mramberg@cpan.org"
 287
 288     Jesse Sheidlower, "jester@panix.com"
 289
 290     Andy Wardley, "abw@cpan.org"
 291
 292 COPYRIGHT
 293     This program is free software, you can redistribute it and/or modify it
 294     under the same terms as Perl itself.
 295