Commit | Line | Data |
8077080c |
1 | NAME |
2 | Catalyst::View::TT - Template View Class |
3 | |
4 | SYNOPSIS |
c0eb0527 |
5 | # use the helper to create View myapp_create.pl view TT TT |
8077080c |
6 | |
c0eb0527 |
7 | # configure in lib/MyApp.pm |
8077080c |
8 | |
c0eb0527 |
9 | MyApp->config({ |
10 | name => 'MyApp', |
3cf1e0a6 |
11 | root => MyApp->path_to('root');, |
12 | 'V::TT' => { |
c0eb0527 |
13 | # any TT configurations items go here |
14 | INCLUDE_PATH => [ |
3cf1e0a6 |
15 | MyApp->path_to( 'root', 'src' ), |
16 | MyApp->path_to( 'root', 'lib' ), |
c0eb0527 |
17 | ], |
3cf1e0a6 |
18 | PRE_PROCESS => 'config/main', |
19 | WRAPPER => 'site/wrapper', |
20 | TEMPLATE_EXTENSION => '.tt', |
c0eb0527 |
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 | } |
8077080c |
36 | |
c0eb0527 |
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 %] |
8077080c |
45 | |
c0eb0527 |
46 | # example when CATALYST_VAR isn't set |
47 | Context is [% c %] |
48 | The base is [% base %] |
49 | The name is [% name %] |
8077080c |
50 | |
51 | DESCRIPTION |
c0eb0527 |
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 | |
c0eb0527 |
93 | MyApp::V::TT->config({ |
3cf1e0a6 |
94 | INCLUDE_PATH => [ |
95 | MyApp->path_to( 'root', 'templates', 'lib' ), |
96 | MyApp->path_to( 'root', 'templates', 'src' ), |
97 | ], |
c0eb0527 |
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({ |
3cf1e0a6 |
111 | INCLUDE_PATH => [ |
112 | MyApp->path_to( 'root', 'templates', 'lib' ), |
113 | MyApp->path_to( 'root', 'templates', 'src' ), |
114 | ], |
c0eb0527 |
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 | |
c0eb0527 |
133 | MyApp->config({ |
134 | name => 'MyApp', |
3cf1e0a6 |
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 | ], |
c0eb0527 |
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 | |
3cf1e0a6 |
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 | |
c0eb0527 |
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 %] |
2599ee6f |
192 | |
c0eb0527 |
193 | The output generated by the template is stored in |
194 | "$c->response->output". |
195 | |
196 | TEMPLATE PROFILING |
caa61517 |
197 | METHODS |
c0eb0527 |
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 |
3cf1e0a6 |
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. |
8077080c |
264 | |
c0eb0527 |
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. |
8077080c |
278 | |
279 | SEE ALSO |
c0eb0527 |
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" |
8077080c |
289 | |
c0eb0527 |
290 | Andy Wardley, "abw@cpan.org" |
8077080c |
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 | |