1 package Maypole::View::TT;
2 use base 'Maypole::View::Base';
3 use Maypole::Constants;
5 use File::Spec::Functions qw(catdir tmpdir);
6 use Template::Constants qw( :all );
9 { local $/; $error_template = <DATA>; }
11 our $VERSION = '2.12';
13 my $debug_flags = DEBUG_ON;
18 my ( $self, $r ) = @_;
19 unless ($self->{tt}) {
20 my $view_options = $r->config->view_options || {};
22 $view_options->{DEBUG} = $debug_flags;
25 $view_options->{POST_CHOMP} = 1 unless (exists $view_options->{POST_CHOMP});
26 $self->{provider} = Template::Provider->new($view_options);
27 $self->{tt} = Template->new({
29 LOAD_TEMPLATES => [ $self->{provider} ],
33 $self->{provider}->include_path([ $self->paths($r) ]);
35 my $template_file = $r->template;
37 my $ext = $r->config->template_extension;
38 $template_file .= $ext if defined $ext;
41 my $processed_ok = eval{$self->{tt}->process($template_file, { $self->vars($r) }, \$output );};
43 $r->{output} = $output;
47 my $error = "fatal error in template '$template_file' : $@\nTT paths : " . join(', ',$self->paths($r)) . "\n";
51 my $error = "TT error for template '$template_file'\n" . $self->{tt}->error . "\nTT paths : " . join(', ',$self->paths($r)) . "\n";
61 my ($self, $r, $error, $type) = @_;
64 # Need to be very careful here.
65 my $tt = Template->new;
66 unless (ref $r->{config}) {
67 $r->warn("no config for this request");
68 $error .= '<br> There was a problem finding configuration for this request';
72 $r->warn("report_error - reporting error to user : $error\n");
74 if ($tt->process(\$error_template,
75 { err_type => $type, error => $error,
76 config => $r->{config},
78 paths => [ $self->paths($r) ],
79 eval{$self->vars($r)} }, \$output )) {
80 $r->{output} = $output;
81 if ($tt->error) { $r->{output} = "<html><body>Even the error template
82 errored - ".$tt->error."</body></html>"; }
83 $r->{content_type} ||= "text/html";
84 $r->{document_encoding} ||= "utf-8";
93 Maypole::View::TT - A Template Toolkit view class for Maypole
97 BeerDB->config->view("Maypole::View::TT"); # The default anyway
99 # Set some Template Toolkit options
100 BeerDB->config->view_options( {
102 COMPILE_DIR => '/var/tmp/mysite/templates',
113 [% maybe_link_view %]
117 This is the default view class for Maypole; it uses the Template Toolkit to fill
118 in templates with the objects produced by Maypole's model classes. Please see
119 the L<Maypole manual|Maypole::Manual>, and in particular, the
120 L<view|Maypole::Manual::View> chapter for the template variables available and
121 for a refresher on how template components are resolved.
123 The underlying Template toolkit object is configured through
124 C<$r-E<gt>config-E<gt>view_options>. See L<Template|Template> for available
131 Processes the template and sets the output. See L<Maypole::View::Base>
135 Reports the details of an error, current state and parameters
139 =head1 TEMPLATE TOOLKIT INTRODUCTION
141 The Template Toolkit uses it's own mini language described in
142 L<Template::Manual::Directives>.
144 A simple example would be :
150 Dear [% title %] [% surname %],
151 Thank you for your letter dated [% your.date %]. This is to
152 confirm that we have received it and will respond with a more
153 detailed response as soon as possible. In the mean time, we
154 enclose more details of ...
158 TT uses '[%' and '%]' (by default) to delimit directives within a template, and
159 the simple directives above just display the value of variable named within
160 those delimiters -- [% title %] will be replaced inline with the value of the
161 'title' variable passed in the 'stash' to the template when it is processed.
163 You can access nested data through the dot ('.') operator, which will
164 dereference array or hash elements, but can also be used to call methods on
165 objects, i.e. '[% name.salutation("Dear %s,") %]'. The other main operator is
166 underscore ('_'), which will concatonate strings or variables.
168 The value returned by a directive replaces the directive inline when the
169 template is processes, you can also SET a value which will not return anything,
170 or CALL a method or operation which will also not return anything.
172 You can specify expressions using the logical (and, or, not, ?:) and mathematic
173 operators (+ - * / % mod div).
175 Results of TT commands are interpolated in the place of the template tags, unless
176 using SET or CALL, i.e. [% SET foo = 1 %], [% GET foo.bar('quz'); %]
180 [% template.title or default.title %]
184 [% order.nitems ? checkout(order.total) : 'no items' %]
188 TT allows you to include or re-use templates through it's INCLUDE, PROCESS and
189 INSERT directives, which are fairly self explainatory. You can also re-use parts
190 of template with the BLOCK or MACRO directives.
192 Conditional and Looping constructs are simple and powerful, and TT provides an
193 inbuilt iterator and helper functions and classes that make life sweet.
195 Conditional directives are IF, UNLESS, ELSIF, ELSE and behave as they would in
201 Hello [% name %], does your mother know you're using her AOL account?
203 Sorry, you're not old enough to enter (and too dumb to lie about your age)
208 [% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %]
212 Looping directives are FOREACH, LAST and BREAK.
214 FOREACH loops through a HASH or ARRAY processing the enclosed block for each
217 Looping through an array
219 [% FOREACH i = items %]
223 Looping through a hash
225 [% FOREACH u IN users %]
226 * [% u.key %] : [% u.value %]
229 Looping through an array of hashes
231 [% FOREACH user IN userlist %]
232 * [% user.id %] [% user.name %]
235 The LAST and BREAK directive can be used to exit the loop.
237 The FOREACH directive is implemented using the Template::Iterator module. A
238 reference to the iterator object for a FOREACH directive is implicitly available
239 in the 'loop' variable. The loop iterator object provides a selection of methods
240 including size(), max(), first(), last(), count(), etc
244 [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%]
245 [%- "<ul>\n" IF loop.first %]
246 <li>[% loop.count %]/[% loop.size %]: [% item %]
247 [%- "</ul>\n" IF loop.last %]
252 See Template::Iterator for further details on looping and the Iterator.
254 You might notice the minus ('-') operator in the example above, it is used to
255 remove a newline before or after a directive so that you can layout the Template
256 logic as above but the resulting output will look exactly how you require it.
258 You will also frequently see comments and multi-line directives, # at the start
259 of a directive marks it as a comment, i.e. '[%# this is a comment %]'. A
260 multiline directive looks like :
266 You can see that lines are terminated with a semi-colon (';') unless the
267 delimter ('%]') closes the directive.
269 For full details of the Template Toolkit see Template::Manual and
270 Template::Manual::Directives, you can also check the website, mailing list or
271 the Template Toolkit book published by O Reilly.
273 =head1 TEMPLATE PLUGINS, FILTERS AND MACROS
275 The Template Toolkit has a popular and powerful selection of Plugins and
278 TT Plugins provide additional functionality within Templates, from accessing CGI
279 and databases directly, handling paging or simple integration with Class::DBI
280 (for those rare occasions where you don't actually need Maypole). See
281 L<Template::Manual::Plugins>.
283 One plugin that is indispensible when using Maypole and the Template View is
284 C<Template::Plugin::Class> -- This allows you to import and use any class
285 installed within a template. For example :
289 [% USE foo = Class('Foo') %]
294 Would do the equivilent of 'use Foo; Foo->bar;' in perl. See
295 L<Template::Plugin::Class> for details.
297 TT Filters process strings or blocks within a template, allowing you to
298 truncate, format, escape or encode trivially. A useful selection is included
299 with Template Toolkit and they can also be found on CPAN or can be written
300 easily. See L<Template::Manual::Filters>.
302 TT provides stderr and stdout filters, which allow you to write handy macros
303 like this one to output debug information to your web server log, etc :
307 [% MACRO debug_msg(text)
308 FILTER stderr; "[TT debug_msg] $text\n"; END;
314 TT Macros allow you to reuse small blocks of content, directives, etc. The MACRO
315 directive allows you to define a directive or directive block which is then
316 evaluated each time the macro is called. Macros can be passed named parameters
319 Once a MACRO is defined within a template or 'include'd template it can be used
320 as if it were a native TT directive. Maypole provides a selection of powerful
321 and useful macros in the templates/ directory of the package and these are used
322 in the beerdb and default templates. See the MACRO section of the
323 L<Template::Manual::Directives> documentation.
325 =head1 ACCESSING MAYPOLE VALUES
329 You can access the request in your templates in order to see the action, table, etc as well
330 as parameters passed through forms :
334 Hello [% request.params.forename %] [% request.params.surname %] !
338 Are you want to [% request.action %] in the [% request.table %] ?
342 You can access your maypole application configuration through the config variable :
344 <link base="[% config.uri_base %]"/>
346 =head2 object and objects
348 Objects are passed to the request using r->objects($arrayref) and are accessed in the templates
349 as an array called objects.
351 [% FOR objects %] <a href="[% config.uri_base %]/[% request.table %]/view/[% object.id %]"> [% object %] </a> [% END %]
353 =head1 MAYPOLE MACROS AND FILTERS
355 Maypole provides a collection of useful and powerful macros in the templates/factory/macros
356 and other templates. These can be used in any template with [% PROCESS templatename %].
360 This creates an <A HREF="..."> to a command in the Apache::MVC system by
361 catenating the base URL, table, command, and any arguments.
363 =head2 maybe_link_view
365 C<maybe_link_view> takes something returned from the database - either
366 some ordinary data, or an object in a related class expanded by a
367 has-a relationship. If it is an object, it constructs a link to the view
368 command for that object. Otherwise, it just displays the data.
372 This is an include template rather than a macro, and it controls the pager
373 display at the bottom (by default) of the factory list and search views/template.
374 It expects a C<pager> template argument which responds to the L<Data::Page> interface.
376 This macro is in the pager template and used as :
380 Maypole provides a pager for list and search actions, otherwise you can
381 provide a pager in the template using Template::Plugin::Pagination.
383 [% USE pager = Pagination(objects, page.current, page.rows) %]
387 The pager will use a the request action as the action in the url unless the
388 pager_action variable is set, which it will use instead if available.
401 <html><head><title>Maypole error page</title>
402 <style type="text/css">
403 body { background-color:#7d95b5; font-family: sans-serif}
404 p { background-color: #fff; padding: 5px; }
405 pre { background-color: #fff; padding: 5px; border: 1px dotted black }
408 .lhs {background-color: #ffd; }
409 .rhs {background-color: #dff; }
412 <h1> Maypole application error </h1>
414 <p> This application living at <code>[%request.config.uri_base%]</code>,
415 [%request.config.application_name || "which is unnamed" %], has
416 produced an error. The adminstrator should be able to understand
417 this error message and fix the problem.</p>
419 <h2> Some basic facts </h2>
421 <p> The error was found in the [% err_type %] stage of processing
422 the path "[% request.path %]". The error text returned was:
428 <h2> Request details </h2>
430 <table width="85%" cellspacing="2" cellpadding="1">
431 [% FOR attribute = ["model_class", "table", "template", "path",
432 "content_type", "document_encoding", "action", "args", "objects"] %]
433 <tr> <td class="lhs" width="35%"> <b>[% attribute %]</b> </td> <td class="rhs" width="65%"> [%
434 request.$attribute.list.join(" , ") %] </td></tr>
436 <tr><td colspan="2"></tr>
437 <tr><td class="lhs" colspan="2"><b>CGI Parameters</b> </td></tr>
438 [% FOREACH param IN request.params %]
439 <tr> <td class="lhs" width="35%">[% param.key %]</td> <td class="rhs" width="65%"> [% param.value %] </td></tr>
443 <h2> Website / Template Paths </h2>
444 <table width="85%" cellspacing="2" cellpadding="1">
445 <tr><td class="lhs" width="35%"> <b>Base URI</b> </td><td class="rhs" width="65%">[% request.config.uri_base %]</td></tr>
446 <tr><td class="lhs" width="35%"> <b>Paths</b> </td><td class="rhs" width="65%"> [% paths %] </td></tr>
449 <h2> Application configuration </h2>
450 <table width="85%" cellspacing="2" cellpadding="1">
451 <tr><td class="lhs" width="35%"> <b>Model </b> </td><td class="rhs" width="65%"> [% request.config.model %] </td></tr>
452 <tr><td class="lhs" width="35%"> <b>View </b> </td><td class="rhs" width="65%"> [% request.config.view %] </td></tr>
453 <tr><td class="lhs" width="35%"> <b>Classes</b> </td><td class="rhs" width="65%"> [% request.config.classes.list.join(" , ") %] </td></tr>
454 <tr><td class="lhs" width="35%"> <b>Tables</b> </td><td class="rhs" width="65%"> [% request.config.display_tables.list.join(" , ") %] </td></tr>