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