lib/Maypole/View/TT.pm

   1 package Maypole::View::TT;
   2 use base 'Maypole::View::Base';
   3 use Maypole::Constants;
   4 use Template;
   5 use File::Spec::Functions qw(catdir tmpdir);
   6
   7 use strict;
   8 our $VERSION = 2.11;
   9
  10 sub template {
  11     my ( $self, $r ) = @_;
  12
  13     unless ($self->{tt}) {
  14         my $view_options = $r->config->view_options || {};
  15         $self->{provider} = Template::Provider->new($view_options);
  16         $self->{tt}       = Template->new({
  17             %$view_options,
  18             LOAD_TEMPLATES => [ $self->{provider} ],
  19         });
  20     }
  21
  22     $self->{provider}->include_path([ $self->paths($r) ]);
  23
  24     my $template_file = $r->template;
  25     my $ext = $r->config->template_extension;
  26     $template_file .= $ext if defined $ext;
  27
  28     my $output;
  29     if ($self->{tt}->process($template_file, { $self->vars($r) }, \$output )) {
  30         $r->{output} = $output;
  31         return OK;
  32     }
  33     else {
  34         $r->{error} = "TT error for template '$template_file'\n" . $self->{tt}->error;
  35         return ERROR;
  36     }
  37 }
  38
  39 1;
  40
  41 =head1 NAME
  42
  43 Maypole::View::TT - A Template Toolkit view class for Maypole
  44
  45 =head1 SYNOPSIS
  46
  47     BeerDB->config->view("Maypole::View::TT"); # The default anyway
  48
  49     # Set some Template Toolkit options
  50     BeerDB->config->view_options( {
  51         TRIM        => 1,
  52         COMPILE_DIR => '/var/tmp/mysite/templates',
  53     } );
  54
  55     .....
  56
  57     [%# Template Toolkit directives and maypole macros go here %]
  58
  59 =head1 DESCRIPTION
  60
  61 This is the default view class for Maypole; it uses the Template Toolkit to
  62 fill in templates with the objects produced by Maypole's model classes.  Please
  63 see the L<Maypole manual|Maypole::Manual>, and in particular, the
  64 L<view|Maypole::Manual::View> chapter for the template variables available and
  65 for a refresher on how template components are resolved.
  66
  67 The underlying Template toolkit object is configured through
  68 C<$r-E<gt>config-E<gt>view_options>. See L<Template|Template> for available
  69 options.
  70
  71 =over 4
  72
  73 =item template
  74
  75 Processes the template and sets the output. See L<Maypole::View::Base>
  76
  77 =back
  78
  79 =head1 TEMPLATE TOOLKIT INTRODUCTION
  80
  81 The Template Toolkit uses it's own mini language described in L<Template::Manual::Directives>.
  82
  83 A simple example would be :
  84
  85 =over 4
  86
  87 re:[% subject %]
  88
  89 Dear [% title %] [% surname %],
  90 Thank you for your letter dated [% your.date %]. This is to
  91 confirm that we have received it and will respond with a more
  92 detailed response as soon as possible. In the mean time, we
  93 enclose more details of ...
  94
  95 =back
  96
  97 TT uses '[%' and '%]' (by default) to delimit directives within a template, and the simple directives
  98 above just display the value of variable named within those delimiters -- [% title %] will be replaced
  99 inline with the value of the 'title' variable passed in the 'stash' to the template when it is processed.
 100
 101 You can access nested data through the dot ('.') operator, which will dereference array or hash elements,
 102 but can also be used to call methods on objects, i.e. '[% name.salutation("Dear %s,") %]'. The other main
 103 operator is underscore ('_'), which will concatonate strings or variables.
 104
 105 The value returned by a directive replaces the directive inline when the template is processes, you can also
 106 SET a value which will not return anything, or CALL a method or operation which will also not return anything.
 107
 108 You can specify expressions using the logical (and, or, not, ?:) and mathematic operators (+ - * / % mod div).
 109
 110 =over 4
 111
 112 [% template.title or default.title %]
 113
 114 [% score * 100 %]
 115
 116 [% order.nitems ? checkout(order.total) : 'no items' %]
 117
 118 =back
 119
 120 TT allows you to include or re-use templates through it's INCLUDE, PROCESS and INSERT directives, which
 121 are fairly self explainatory. You can also re-use parts of template with the BLOCK or MACRO directives.
 122
 123 Conditional and Looping constructs are simple and powerful, and TT provides an inbuilt iterator and helper
 124 functions and classes that make life sweet.
 125
 126 Conditional directives are IF, UNLESS, ELSIF, ELSE and behave as they would in perl :
 127
 128 =over 4
 129
 130 [% IF age < 10 %]
 131   Hello [% name %], does your mother know you're  using her AOL account?
 132 [% ELSIF age < 18 %]
 133   Sorry, you're not old enough to enter (and too dumb to lie about your age)
 134 [% ELSE %]
 135   Welcome [% name %].
 136 [% END %]
 137
 138 [% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %]
 139
 140 =back
 141
 142 Looping directives are FOREACH, LAST and BREAK.
 143
 144 FOREACH loops through a HASH or ARRAY processing the enclosed block for each element.
 145
 146 Looping through an array
 147
 148  [% FOREACH i = items %]
 149  [% i %]
 150  [% END %]
 151
 152 Looping through a hash
 153
 154  [% FOREACH u IN users %]
 155  * [% u.key %] : [% u.value %]
 156  [% END %]
 157
 158 Looping through an array of hashes
 159
 160  [% FOREACH user IN userlist %]
 161  * [% user.id %] [% user.name %]
 162  [% END %]
 163
 164 The LAST and BREAK directive can be used to exit the loop.
 165
 166 The FOREACH directive is implemented using the Template::Iterator module.  A reference
 167 to the iterator object for a FOREACH directive is implicitly available in the 'loop' variable.
 168 The loop iterator object provides a selection of methods including size(), max(), first(), last(),
 169 count(), etc
 170
 171 =over 4
 172
 173   [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%]
 174     [%- "<ul>\n" IF loop.first %]
 175       <li>[% loop.count %]/[% loop.size %]: [% item %]
 176     [%- "</ul>\n" IF loop.last %]
 177   [% END %]
 178
 179 =back
 180
 181 See Template::Iterator for further details on looping and the Iterator.
 182
 183 You might notice the minus ('-') operator in the example above, it is used to remove a newline
 184 before or after a directive so that you can layout the Template logic as above but the resulting
 185 output will look exactly how you require it.
 186
 187 You will also frequently see comments and multi-line directives, # at the start of a directive
 188 marks it as a comment, i.e. '[%# this is a comment %]'. A multiline directive looks like :
 189
 190  [% do.this;
 191     do.that;
 192     do.the_other %]
 193
 194 You can see that lines are terminated with a semi-colon (';') unless the delimter ('%]') closes the directive.
 195
 196 For full details of the Template Toolkit see Template::Manual and Template::Manual::Directives, you can
 197 also check the website, mailing list or the Template Toolkit book published by O Reilly.
 198
 199 =head1 TEMPLATE PLUGINS, FILTERS AND MACROS
 200
 201 The Template Toolkit has a popular and powerful selection of Plugins and Filters.
 202
 203 TT Plugins provide additional functionality within Templates, from accessing CGI and
 204 databases directly, handling paging or simple integration with Class::DBI (for those
 205 rare occasions where you don't actually need Maypole). See L<Template::Manual::Plugins>.
 206
 207 One plugin that is indispensible when using Maypole and the Template View is
 208 C<Template::Plugin::Class> -- This allows you to import and use any class installed
 209 within a template. For example :
 210
 211 =over 4
 212
 213 [% USE foo = Class('Foo') %]
 214 [% foo.bar %]
 215
 216 =back
 217
 218 Would do the equivilent of 'use Foo; Foo->bar;' in perl. See L<Template::Plugin::Class>
 219 for details.
 220
 221 TT Filters process strings or blocks within a template, allowing you to truncate,
 222 format, escape or encode trivially. A useful selection is included with Template Toolkit
 223 and they can also be found on CPAN or can be written easily.
 224 See L<Template::Manual::Filters>.
 225
 226 TT Macros allow you to reuse small blocks of content, directives, etc. The MACRO directive
 227 allows you to define a directive or directive block which is then evaluated each time the
 228 macro is called. Macros can be passed named parameters when called.
 229
 230 Once a MACRO is defined within a template or 'include'd template it can be used as if it
 231 were a native TT directive. Maypole provides a selection of powerful and useful macros
 232 in the templates/ directory of the package and these are used in the beerdb and default
 233 templates. See the MACRO section of the L<Template::Manual::Directives> documentation.
 234
 235 =head1 MAYPOLE MACROS AND FILTERS
 236
 237 Maypole provides a collection of useful and powerful macros...TO DO
 238
 239 =head2 link
 240
 241 =head2 other macros
 242
 243 =head2 finish this documentation
 244
 245 =head1 AUTHOR
 246
 247 Simon Cozens
 248
 249 =cut
 250