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 | our $ROOT = '/home/dent/catalyst/MyApp'; |
8077080c |
10 | |
c0eb0527 |
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 | } |
8077080c |
37 | |
c0eb0527 |
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 %] |
8077080c |
46 | |
c0eb0527 |
47 | # example when CATALYST_VAR isn't set |
48 | Context is [% c %] |
49 | The base is [% base %] |
50 | The name is [% name %] |
8077080c |
51 | |
52 | DESCRIPTION |
c0eb0527 |
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 %] |
2599ee6f |
180 | |
c0eb0527 |
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. |
8077080c |
184 | |
c0eb0527 |
185 | MyApp->config({ |
186 | name => 'MyApp', |
187 | root => $ROOT, |
188 | 'MyApp::V::TT' => { |
189 | CATALYST_VAR => 'Catalyst', |
190 | }, |
191 | }); |
caa61517 |
192 | |
c0eb0527 |
193 | message.tt2: |
caa61517 |
194 | |
c0eb0527 |
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: |
2599ee6f |
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 | |
c0eb0527 |
217 | You can suppress template profiling by setting the "TIMER" configuration |
218 | item to a false value. |
2599ee6f |
219 | |
c0eb0527 |
220 | MyApp->config({ |
221 | 'MyApp::V::TT' => { |
222 | TIMER => 0, |
223 | }, |
224 | }); |
2599ee6f |
225 | |
caa61517 |
226 | METHODS |
c0eb0527 |
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. |
8077080c |
245 | |
c0eb0527 |
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. |
8077080c |
259 | |
260 | SEE ALSO |
c0eb0527 |
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" |
8077080c |
270 | |
c0eb0527 |
271 | Andy Wardley, "abw@cpan.org" |
8077080c |
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 | |