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