2 Catalyst::View::TT - Template View Class
5 # use the helper to create View myapp_create.pl view TT TT
7 # configure in lib/MyApp.pm
11 root => MyApp->path_to('root');,
13 # any TT configurations items go here
15 MyApp->path_to( 'root', 'src' ),
16 MyApp->path_to( 'root', 'lib' ),
18 PRE_PROCESS => 'config/main',
19 WRAPPER => 'site/wrapper',
20 TEMPLATE_EXTENSION => '.tt',
22 # two optional config items
23 CATALYST_VAR => 'Catalyst',
28 # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
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');
37 # access variables from template
39 The message is: [% message %].
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 %]
46 # example when CATALYST_VAR isn't set
48 The base is [% base %]
49 The name is [% name %]
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.
58 $ script/myapp_create.pl view TT TT
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
64 package FooBar::V::TT;
67 use base 'Catalyst::View::TT';
69 __PACKAGE__->config->{DEBUG} = 'all';
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
76 # In MyApp or MyApp::Controller::SomeController
80 $c->forward('MyApp::V::TT');
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.
91 use base 'Catalyst::View::TT';
93 MyApp::V::TT->config({
95 MyApp->path_to( 'root', 'templates', 'lib' ),
96 MyApp->path_to( 'root', 'templates', 'src' ),
98 PRE_PROCESS => 'config/main',
99 WRAPPER => 'site/wrapper',
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
112 MyApp->path_to( 'root', 'templates', 'lib' ),
113 MyApp->path_to( 'root', 'templates', 'src' ),
115 PRE_PROCESS => 'config/main',
116 WRAPPER => 'site/wrapper',
118 return $self->NEXT::new(@_);
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).
135 root => MyApp->path_to('root'),
138 MyApp->path_to( 'root', 'templates', 'lib' ),
139 MyApp->path_to( 'root', 'templates', 'src' ),
141 PRE_PROCESS => 'config/main',
142 WRAPPER => 'site/wrapper',
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
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:
156 $c->stash->{additional_template_paths} = [$c->config->{root} . '/test_include_path'];
159 The view plugin renders the template specified in the "template" item in
162 sub message : Global {
163 my ( $self, $c ) = @_;
164 $c->stash->{template} = 'message.tt2';
165 $c->forward('MyApp::V::TT');
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
172 The items defined in the stash are passed to the Template Toolkit for
173 use as template variables.
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'); }
179 A number of other template variables are also added:
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 }
185 These can be accessed from the template in the usual way:
189 The message is: [% message %]
190 The base is [% base %]
191 The name is [% name %]
193 The output generated by the template is stored in
194 "$c->response->output".
198 new The constructor for the TT view. Sets up the template provider, and
199 reads the application config.
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".
213 This method allows your view subclass to pass additional settings to
214 the TT configuration hash, or to set the options as below:
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>.
225 root => MyApp->path_to('root'),
227 CATALYST_VAR => 'Catalyst',
233 The base is [% Catalyst.req.base %]
234 The name is [% Catalyst.config.name %]
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:
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) -->
250 <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) -->
253 a sufix to add when looking for templates bases on the "match"
254 method in Catalyst::Request.
258 package MyApp::C::Test;
259 sub test : Local { .. }
261 Would by default look for a template in <root>/test/test. If you
262 set TEMPLATE_EXTENSION to '.tt', it will look for
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:
270 $ script/myapp_create.pl view TT TT
272 $ script/myapp_create.pl view TT TTSite
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.
280 Catalyst, Catalyst::Helper::View::TT, Catalyst::Helper::View::TTSite,
284 Sebastian Riedel, "sri@cpan.org"
286 Marcus Ramberg, "mramberg@cpan.org"
288 Jesse Sheidlower, "jester@panix.com"
290 Andy Wardley, "abw@cpan.org"
293 This program is free software, you can redistribute it and/or modify it
294 under the same terms as Perl itself.