Catalyst::View::TT(3pm)

1Catalyst::View::TT(3) User Contributed Perl DocumentationCatalyst::View::TT(3)
2
3
4

NAME

6       Catalyst::View::TT - Template View Class
7

SYNOPSIS

9       # use the helper to create your View
10           myapp_create.pl view TT TT
11
12       # configure in lib/MyApp.pm
13
14           MyApp->config(
15               name     => 'MyApp',
16               root     => MyApp->path_to('root'),
17               'View::TT' => {
18                   # any TT configurations items go here
19                   INCLUDE_PATH => [
20                     MyApp->path_to( 'root', 'src' ),
21                     MyApp->path_to( 'root', 'lib' ),
22                   ],
23                   PRE_PROCESS        => 'config/main',
24                   WRAPPER            => 'site/wrapper',
25                   TEMPLATE_EXTENSION => '.tt',
26
27                   # two optional config items
28                   CATALYST_VAR => 'Catalyst',
29                   TIMER        => 1,
30               },
31           );
32
33       # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
34
35           sub message : Global {
36               my ( $self, $c ) = @_;
37               $c->stash->{template} = 'message.tt2';
38               $c->stash->{message}  = 'Hello World!';
39               $c->forward('MyApp::V::TT');
40           }
41
42       # access variables from template
43
44           The message is: [% message %].
45
46           # example when CATALYST_VAR is set to 'Catalyst'
47           Context is [% Catalyst %]
48           The base is [% Catalyst.req.base %]
49           The name is [% Catalyst.config.name %]
50
51           # example when CATALYST_VAR isn't set
52           Context is [% c %]
53           The base is [% base %]
54           The name is [% name %]
55

DESCRIPTION

57       This is the Catalyst view class for the Template Toolkit.  Your appli‐
58       cation should defined a view class which is a subclass of this module.
59       The easiest way to achieve this is using the myapp_create.pl script
60       (where myapp should be replaced with whatever your application is
61       called).  This script is created as part of the Catalyst setup.
62
63           $ script/myapp_create.pl view TT TT
64
65       This creates a MyApp::V::TT.pm module in the lib directory (again,
66       replacing "MyApp" with the name of your application) which looks some‐
67       thing like this:
68
69           package FooBar::V::TT;
70
71           use strict;
72            use base 'Catalyst::View::TT';
73
74           __PACKAGE__->config->{DEBUG} = 'all';
75
76       Now you can modify your action handlers in the main application and/or
77       controllers to forward to your view class.  You might choose to do this
78       in the end() method, for example, to automatically forward all actions
79       to the TT view class.
80
81           # In MyApp or MyApp::Controller::SomeController
82
83           sub end : Private {
84               my( $self, $c ) = @_;
85               $c->forward('MyApp::V::TT');
86           }
87
88       CONFIGURATION
89
90       There are a three different ways to configure your view class.  The
91       first way is to call the "config()" method in the view subclass.  This
92       happens when the module is first loaded.
93
94           package MyApp::V::TT;
95
96           use strict;
97           use base 'Catalyst::View::TT';
98
99           MyApp::V::TT->config({
100               INCLUDE_PATH => [
101                   MyApp->path_to( 'root', 'templates', 'lib' ),
102                   MyApp->path_to( 'root', 'templates', 'src' ),
103               ],
104               PRE_PROCESS  => 'config/main',
105               WRAPPER      => 'site/wrapper',
106           });
107
108       The second way is to define a "new()" method in your view subclass.
109       This performs the configuration when the view object is created,
110       shortly after being loaded.  Remember to delegate to the base class
111       "new()" method (via "$self->NEXT::new()" in the example below) after
112       performing any configuration.
113
114           sub new {
115               my $self = shift;
116               $self->config({
117                   INCLUDE_PATH => [
118                       MyApp->path_to( 'root', 'templates', 'lib' ),
119                       MyApp->path_to( 'root', 'templates', 'src' ),
120                   ],
121                   PRE_PROCESS  => 'config/main',
122                   WRAPPER      => 'site/wrapper',
123               });
124               return $self->NEXT::new(@_);
125           }
126
127       The final, and perhaps most direct way, is to define a class item in
128       your main application configuration, again by calling the uniquitous
129       "config()" method.  The items in the class hash are added to those
130       already defined by the above two methods.  This happens in the base
131       class new() method (which is one reason why you must remember to call
132       it via "NEXT" if you redefine the "new()" method in a subclass).
133
134           package MyApp;
135
136           use strict;
137           use Catalyst;
138
139           MyApp->config({
140               name     => 'MyApp',
141               root     => MyApp->path_to('root'),
142               'V::TT' => {
143                   INCLUDE_PATH => [
144                       MyApp->path_to( 'root', 'templates', 'lib' ),
145                       MyApp->path_to( 'root', 'templates', 'src' ),
146                   ],
147                   PRE_PROCESS  => 'config/main',
148                   WRAPPER      => 'site/wrapper',
149               },
150           });
151
152       Note that any configuration items defined by one of the earlier methods
153       will be overwritten by items of the same name provided by the latter
154       methods.
155
156       DYNAMIC INCLUDE_PATH
157
158       Sometimes it is desirable to modify INCLUDE_PATH for your templates at
159       run time.
160
161       Additional paths can be added to the start of INCLUDE_PATH via the
162       stash as follows:
163
164           $c->stash->{additional_template_paths} =
165               [$c->config->{root} . '/test_include_path'];
166
167       If you need to add paths to the end of INCLUDE_PATH, there is also an
168       include_path() accessor available:
169
170           push( @{ $c->view('TT')->include_path }, qw/path/ );
171
172       Note that if you use include_path() to add extra paths to INCLUDE_PATH,
173       you MUST check for duplicate paths. Without such checking, the above
174       code will add "path" to INCLUDE_PATH at every request, causing a memory
175       leak.
176
177       A safer approach is to use include_path() to overwrite the array of
178       paths rather than adding to it. This eliminates both the need to per‐
179       form duplicate checking and the chance of a memory leak:
180
181           @{ $c->view('TT')->include_path } = qw/path another_path/;
182
183       If you are calling "render" directly then you can specify dynamic paths
184       by having a "additional_template_paths" key with a value of additonal
185       directories to search. See "CAPTURING TEMPLATE OUTPUT" for an example
186       showing this.
187
188       RENDERING VIEWS
189
190       The view plugin renders the template specified in the "template" item
191       in the stash.
192
193           sub message : Global {
194               my ( $self, $c ) = @_;
195               $c->stash->{template} = 'message.tt2';
196               $c->forward('MyApp::V::TT');
197           }
198
199       If a stash item isn't defined, then it instead uses the stringification
200       of the action dispatched to (as defined by $c->action) in the above
201       example, this would be "message", but because the default is to append
202       '.tt', it would load "root/message.tt".
203
204       The items defined in the stash are passed to the Template Toolkit for
205       use as template variables.
206
207           sub default : Private {
208               my ( $self, $c ) = @_;
209               $c->stash->{template} = 'message.tt2';
210               $c->stash->{message}  = 'Hello World!';
211               $c->forward('MyApp::V::TT');
212           }
213
214       A number of other template variables are also added:
215
216           c      A reference to the context object, $c
217           base   The URL base, from $c->req->base()
218           name   The application name, from $c->config->{ name }
219
220       These can be accessed from the template in the usual way:
221
222       <message.tt2>:
223
224           The message is: [% message %]
225           The base is [% base %]
226           The name is [% name %]
227
228       The output generated by the template is stored in "$c->response->body".
229
230       CAPTURING TEMPLATE OUTPUT
231
232       If you wish to use the output of a template for some other purpose than
233       displaying in the response, e.g. for sending an email, this is possible
234       using Catalyst::Plugin::Email and the render method:
235
236         sub send_email : Local {
237           my ($self, $c) = @_;
238
239           $c->email(
240             header => [
241               To      => 'me@localhost',
242               Subject => 'A TT Email',
243             ],
244             body => $c->view('TT')->render($c, 'email.tt', {
245               additional_template_paths => [ $c->config->{root} . '/email_templates'],
246               email_tmpl_param1 => 'foo'
247               }
248             ),
249           );
250         # Redirect or display a message
251         }
252
253       TEMPLATE PROFILING
254
255       See "TIMER" property of the config method.
256
257       METHODS
258
259       new
260
261       The constructor for the TT view. Sets up the template provider, and
262       reads the application config.
263
264       process
265
266       Renders the template specified in "$c->stash->{template}" or
267       "$c->action" (the private name of the matched action.  Calls render to
268       perform actual rendering. Output is stored in "$c->response->body".
269
270       render($c, $template, \%args)
271
272       Renders the given template and returns output, or a Template::Exception
273       object upon error.
274
275       The template variables are set to %$args if $args is a hashref, or
276       $"$c->stash" otherwise. In either case the variables are augmented with
277       "base" set to " << $c-"req->base >>, "c" to $c and "name" to "$c->con‐
278       fig->{name}". Alternately, the "CATALYST_VAR" configuration item can be
279       defined to specify the name of a template variable through which the
280       context reference ($c) can be accessed. In this case, the "c", "base"
281       and "name" variables are omitted.
282
283       $template can be anything that Template::process understands how to
284       process, including the name of a template file or a reference to a test
285       string.  See Template::process for a full list of supported formats.
286
287       template_vars
288
289       Returns a list of keys/values to be used as the catalyst variables in
290       the template.
291
292       config
293
294       This method allows your view subclass to pass additional settings to
295       the TT configuration hash, or to set the options as below:
296
297       paths
298
299       The list of paths TT will look for templates in.
300
301       "CATALYST_VAR"
302
303       Allows you to change the name of the Catalyst context object. If set,
304       it will also remove the base and name aliases, so you will have access
305       them through <context>.
306
307       For example:
308
309           MyApp->config({
310               name     => 'MyApp',
311               root     => MyApp->path_to('root'),
312               'V::TT' => {
313                   CATALYST_VAR => 'Catalyst',
314               },
315           });
316
317       message.tt2:
318
319           The base is [% Catalyst.req.base %]
320           The name is [% Catalyst.config.name %]
321
322       "TIMER"
323
324       If you have configured Catalyst for debug output, and turned on the
325       TIMER setting, "Catalyst::View::TT" will enable profiling of template
326       processing (using Template::Timer). This will embed HTML comments in
327       the output from your templates, such as:
328
329           <!-- TIMER START: process mainmenu/mainmenu.ttml -->
330           <!-- TIMER START: include mainmenu/cssindex.tt -->
331           <!-- TIMER START: process mainmenu/cssindex.tt -->
332           <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) -->
333           <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) -->
334
335           ....
336
337           <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
338
339       "TEMPLATE_EXTENSION"
340
341       a sufix to add when looking for templates bases on the "match" method
342       in Catalyst::Request.
343
344       For example:
345
346         package MyApp::C::Test;
347         sub test : Local { .. }
348
349       Would by default look for a template in <root>/test/test. If you set
350       TEMPLATE_EXTENSION to '.tt', it will look for <root>/test/test.tt.
351
352       HELPERS
353
354       The Catalyst::Helper::View::TT and Catalyst::Helper::View::TTSite
355       helper modules are provided to create your view module.  There are
356       invoked by the myapp_create.pl script:
357
358           $ script/myapp_create.pl view TT TT
359
360           $ script/myapp_create.pl view TT TTSite
361
362       The Catalyst::Helper::View::TT module creates a basic TT view module.
363       The Catalyst::Helper::View::TTSite module goes a little further.  It
364       also creates a default set of templates to get you started.  It also
365       configures the view module to locate the templates automatically.
366

AUTHORS

372       Sebastian Riedel, "sri@cpan.org"
373
374       Marcus Ramberg, "mramberg@cpan.org"
375
376       Jesse Sheidlower, "jester@panix.com"
377
378       Andy Wardley, "abw@cpan.org"
379

COPYRIGHT

381       This program is free software, you can redistribute it and/or modify it
382       under the same terms as Perl itself.
383
384
385
386perl v5.8.8                       2008-01-11             Catalyst::View::TT(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHORS

COPYRIGHT