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 fill
  62 in templates with the objects produced by Maypole's model classes. Please see
  63 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
  82 L<Template::Manual::Directives>.
  83
  84 A simple example would be :
  85
  86 =over 4
  87
  88 re:[% subject %]
  89
  90 Dear [% title %] [% surname %],
  91 Thank you for your letter dated [% your.date %]. This is to
  92 confirm that we have received it and will respond with a more
  93 detailed response as soon as possible. In the mean time, we
  94 enclose more details of ...
  95
  96 =back
  97
  98 TT uses '[%' and '%]' (by default) to delimit directives within a template, and
  99 the simple directives above just display the value of variable named within
 100 those delimiters -- [% title %] will be replaced inline with the value of the
 101 'title' variable passed in the 'stash' to the template when it is processed.
 102
 103 You can access nested data through the dot ('.') operator, which will
 104 dereference array or hash elements, but can also be used to call methods on
 105 objects, i.e. '[% name.salutation("Dear %s,") %]'. The other main operator is
 106 underscore ('_'), which will concatonate strings or variables.
 107
 108 The value returned by a directive replaces the directive inline when the
 109 template is processes, you can also SET a value which will not return anything,
 110 or CALL a method or operation which will also not return anything.
 111
 112 You can specify expressions using the logical (and, or, not, ?:) and mathematic
 113 operators (+ - * / % mod div).
 114
 115 =over 4
 116
 117 [% template.title or default.title %]
 118
 119 [% score * 100 %]
 120
 121 [% order.nitems ? checkout(order.total) : 'no items' %]
 122
 123 =back
 124
 125 TT allows you to include or re-use templates through it's INCLUDE, PROCESS and
 126 INSERT directives, which are fairly self explainatory. You can also re-use parts
 127 of template with the BLOCK or MACRO directives.
 128
 129 Conditional and Looping constructs are simple and powerful, and TT provides an
 130 inbuilt iterator and helper functions and classes that make life sweet.
 131
 132 Conditional directives are IF, UNLESS, ELSIF, ELSE and behave as they would in
 133 perl :
 134
 135 =over 4
 136
 137 [% IF age < 10 %]
 138   Hello [% name %], does your mother know you're  using her AOL account?
 139 [% ELSIF age < 18 %]
 140   Sorry, you're not old enough to enter (and too dumb to lie about your age)
 141 [% ELSE %]
 142   Welcome [% name %].
 143 [% END %]
 144
 145 [% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %]
 146
 147 =back
 148
 149 Looping directives are FOREACH, LAST and BREAK.
 150
 151 FOREACH loops through a HASH or ARRAY processing the enclosed block for each
 152 element.
 153
 154 Looping through an array
 155
 156  [% FOREACH i = items %]
 157  [% i %]
 158  [% END %]
 159
 160 Looping through a hash
 161
 162  [% FOREACH u IN users %]
 163  * [% u.key %] : [% u.value %]
 164  [% END %]
 165
 166 Looping through an array of hashes
 167
 168  [% FOREACH user IN userlist %]
 169  * [% user.id %] [% user.name %]
 170  [% END %]
 171
 172 The LAST and BREAK directive can be used to exit the loop.
 173
 174 The FOREACH directive is implemented using the Template::Iterator module. A
 175 reference to the iterator object for a FOREACH directive is implicitly available
 176 in the 'loop' variable. The loop iterator object provides a selection of methods
 177 including size(), max(), first(), last(), count(), etc
 178
 179 =over 4
 180
 181   [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%]
 182     [%- "<ul>\n" IF loop.first %]
 183       <li>[% loop.count %]/[% loop.size %]: [% item %]
 184     [%- "</ul>\n" IF loop.last %]
 185   [% END %]
 186
 187 =back
 188
 189 See Template::Iterator for further details on looping and the Iterator.
 190
 191 You might notice the minus ('-') operator in the example above, it is used to
 192 remove a newline before or after a directive so that you can layout the Template
 193 logic as above but the resulting output will look exactly how you require it.
 194
 195 You will also frequently see comments and multi-line directives, # at the start
 196 of a directive marks it as a comment, i.e. '[%# this is a comment %]'. A
 197 multiline directive looks like :
 198
 199  [% do.this;
 200     do.that;
 201     do.the_other %]
 202
 203 You can see that lines are terminated with a semi-colon (';') unless the
 204 delimter ('%]') closes the directive.
 205
 206 For full details of the Template Toolkit see Template::Manual and
 207 Template::Manual::Directives, you can also check the website, mailing list or
 208 the Template Toolkit book published by O Reilly.
 209
 210 =head1 TEMPLATE PLUGINS, FILTERS AND MACROS
 211
 212 The Template Toolkit has a popular and powerful selection of Plugins and
 213 Filters.
 214
 215 TT Plugins provide additional functionality within Templates, from accessing CGI
 216 and databases directly, handling paging or simple integration with Class::DBI
 217 (for those rare occasions where you don't actually need Maypole). See
 218 L<Template::Manual::Plugins>.
 219
 220 One plugin that is indispensible when using Maypole and the Template View is
 221 C<Template::Plugin::Class> -- This allows you to import and use any class
 222 installed within a template. For example :
 223
 224 =over 4
 225
 226 [% USE foo = Class('Foo') %]
 227 [% foo.bar %]
 228
 229 =back
 230
 231 Would do the equivilent of 'use Foo; Foo->bar;' in perl. See
 232 L<Template::Plugin::Class> for details.
 233
 234 TT Filters process strings or blocks within a template, allowing you to
 235 truncate, format, escape or encode trivially. A useful selection is included
 236 with Template Toolkit and they can also be found on CPAN or can be written
 237 easily. See L<Template::Manual::Filters>.
 238
 239 TT Macros allow you to reuse small blocks of content, directives, etc. The MACRO
 240 directive allows you to define a directive or directive block which is then
 241 evaluated each time the macro is called. Macros can be passed named parameters
 242 when called.
 243
 244 Once a MACRO is defined within a template or 'include'd template it can be used
 245 as if it were a native TT directive. Maypole provides a selection of powerful
 246 and useful macros in the templates/ directory of the package and these are used
 247 in the beerdb and default templates. See the MACRO section of the
 248 L<Template::Manual::Directives> documentation.
 249
 250 =head1 MAYPOLE MACROS AND FILTERS
 251
 252 Maypole provides a collection of useful and powerful macros...TO DO
 253
 254 =head2 link
 255
 256 =head2 other macros
 257
 258 =head2 finish this documentation
 259
 260 =head1 AUTHOR
 261
 262 Simon Cozens
 263
 264 =cut
 265