1Maypole::View::TT(3)  User Contributed Perl Documentation Maypole::View::TT(3)
2
3
4

NAME

6       Maypole::View::TT - A Template Toolkit view class for Maypole
7

SYNOPSIS

9           BeerDB->config->view("Maypole::View::TT"); # The default anyway
10
11           # Set some Template Toolkit options
12           BeerDB->config->view_options( {
13               TRIM        => 1,
14               COMPILE_DIR => '/var/tmp/mysite/templates',
15           } );
16
17           .....
18
19           [% PROCESS macros %]
20
21           [% pager %]
22
23           [% link %]
24
25           [% maybe_link_view %]
26

DESCRIPTION

28       This is the default view class for Maypole; it uses the Template
29       Toolkit to fill in templates with the objects produced by Maypole's
30       model classes. Please see the Maypole manual, and in particular, the
31       view chapter for the template variables available and for a refresher
32       on how template components are resolved.
33
34       The underlying Template toolkit object is configured through
35       "$r->config->view_options". See Template for available options.
36
37       template
38           Processes the template and sets the output. See Maypole::View::Base
39
40       report_error
41           Reports the details of an error, current state and parameters
42

TEMPLATE TOOLKIT INTRODUCTION

44       The Template Toolkit uses it's own mini language described in
45       Template::Manual::Directives.
46
47       A simple example would be :
48
49           re:[% subject %]
50
51           Dear [% title %] [% surname %], Thank you for your letter dated [%
52           your.date %]. This is to confirm that we have received it and will
53           respond with a more detailed response as soon as possible. In the
54           mean time, we enclose more details of ...
55
56       TT uses '[%' and '%]' (by default) to delimit directives within a
57       template, and the simple directives above just display the value of
58       variable named within those delimiters -- [% title %] will be replaced
59       inline with the value of the 'title' variable passed in the 'stash' to
60       the template when it is processed.
61
62       You can access nested data through the dot ('.') operator, which will
63       dereference array or hash elements, but can also be used to call
64       methods on objects, i.e. '[% name.salutation("Dear %s,") %]'. The other
65       main operator is underscore ('_'), which will concatonate strings or
66       variables.
67
68       The value returned by a directive replaces the directive inline when
69       the template is processes, you can also SET a value which will not
70       return anything, or CALL a method or operation which will also not
71       return anything.
72
73       You can specify expressions using the logical (and, or, not, ?:) and
74       mathematic operators (+ - * / % mod div).
75
76       Results of TT commands are interpolated in the place of the template
77       tags, unless using SET or CALL, i.e. [% SET foo = 1 %], [% GET
78       foo.bar('quz'); %]
79
80           [% template.title or default.title %]
81
82           [% score * 100 %]
83
84           [% order.nitems ? checkout(order.total) : 'no items' %]
85
86       TT allows you to include or re-use templates through it's INCLUDE,
87       PROCESS and INSERT directives, which are fairly self explainatory. You
88       can also re-use parts of template with the BLOCK or MACRO directives.
89
90       Conditional and Looping constructs are simple and powerful, and TT
91       provides an inbuilt iterator and helper functions and classes that make
92       life sweet.
93
94       Conditional directives are IF, UNLESS, ELSIF, ELSE and behave as they
95       would in perl :
96
97           [% IF age < 10 %]
98             Hello [% name %], does your mother know you're  using her AOL
99           account?  [% ELSIF age < 18 %]
100             Sorry, you're not old enough to enter (and too dumb to lie about
101           your age) [% ELSE %]
102             Welcome [% name %].  [% END %]
103
104           [% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %]
105
106       Looping directives are FOREACH, LAST and BREAK.
107
108       FOREACH loops through a HASH or ARRAY processing the enclosed block for
109       each element.
110
111       Looping through an array
112
113        [% FOREACH i = items %]
114        [% i %]
115        [% END %]
116
117       Looping through a hash
118
119        [% FOREACH u IN users %]
120        * [% u.key %] : [% u.value %]
121        [% END %]
122
123       Looping through an array of hashes
124
125        [% FOREACH user IN userlist %]
126        * [% user.id %] [% user.name %]
127        [% END %]
128
129       The LAST and BREAK directive can be used to exit the loop.
130
131       The FOREACH directive is implemented using the Template::Iterator
132       module. A reference to the iterator object for a FOREACH directive is
133       implicitly available in the 'loop' variable. The loop iterator object
134       provides a selection of methods including size(), max(), first(),
135       last(), count(), etc
136
137         [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%]
138           [%- "<ul>\n" IF loop.first %]
139             <li>[% loop.count %]/[% loop.size %]: [% item %]
140           [%- "</ul>\n" IF loop.last %]
141         [% END %]
142
143       See Template::Iterator for further details on looping and the Iterator.
144
145       You might notice the minus ('-') operator in the example above, it is
146       used to remove a newline before or after a directive so that you can
147       layout the Template logic as above but the resulting output will look
148       exactly how you require it.
149
150       You will also frequently see comments and multi-line directives, # at
151       the start of a directive marks it as a comment, i.e. '[%# this is a
152       comment %]'. A multiline directive looks like :
153
154        [% do.this;
155           do.that;
156           do.the_other %]
157
158       You can see that lines are terminated with a semi-colon (';') unless
159       the delimter ('%]') closes the directive.
160
161       For full details of the Template Toolkit see Template::Manual and
162       Template::Manual::Directives, you can also check the website, mailing
163       list or the Template Toolkit book published by O Reilly.
164

TEMPLATE PLUGINS, FILTERS AND MACROS

166       The Template Toolkit has a popular and powerful selection of Plugins
167       and Filters.
168
169       TT Plugins provide additional functionality within Templates, from
170       accessing CGI and databases directly, handling paging or simple
171       integration with Class::DBI (for those rare occasions where you don't
172       actually need Maypole). See Template::Manual::Plugins.
173
174       One plugin that is indispensible when using Maypole and the Template
175       View is "Template::Plugin::Class" -- This allows you to import and use
176       any class installed within a template. For example :
177
178           [% USE foo = Class('Foo') %] [% foo.bar %]
179
180       Would do the equivilent of 'use Foo; Foo->bar;' in perl. See
181       Template::Plugin::Class for details.
182
183       TT Filters process strings or blocks within a template, allowing you to
184       truncate, format, escape or encode trivially. A useful selection is
185       included with Template Toolkit and they can also be found on CPAN or
186       can be written easily. See Template::Manual::Filters.
187
188       TT provides stderr and stdout filters, which allow you to write handy
189       macros like this one to output debug information to your web server
190       log, etc :
191
192           [% MACRO debug_msg(text)
193               FILTER stderr; "[TT debug_msg] $text\n"; END; %]
194
195       TT Macros allow you to reuse small blocks of content, directives, etc.
196       The MACRO directive allows you to define a directive or directive block
197       which is then evaluated each time the macro is called. Macros can be
198       passed named parameters when called.
199
200       Once a MACRO is defined within a template or 'include'd template it can
201       be used as if it were a native TT directive. Maypole provides a
202       selection of powerful and useful macros in the templates/ directory of
203       the package and these are used in the beerdb and default templates. See
204       the MACRO section of the Template::Manual::Directives documentation.
205

ACCESSING MAYPOLE VALUES

207   request
208       You can access the request in your templates in order to see the
209       action, table, etc as well as parameters passed through forms :
210
211       for example
212
213       Hello [% request.params.forename %] [% request.params.surname %] !
214
215       or
216
217       Are you want to [% request.action %] in the [% request.table %] ?
218
219   config
220       You can access your maypole application configuration through the
221       config variable :
222
223       <link base="[% config.uri_base %]"/>
224
225   object and objects
226       Objects are passed to the request using r->objects($arrayref) and are
227       accessed in the templates as an array called objects.
228
229       [% FOR objects %] <a href="[% config.uri_base %]/[% request.table
230       %]/view/[% object.id %]"> [% object %] </a> [% END %]
231

MAYPOLE MACROS AND FILTERS

233       Maypole provides a collection of useful and powerful macros in the
234       templates/factory/macros
235        and other templates. These can be used in any template with [% PROCESS
236       templatename %].
237
238   link
239       This creates an <A HREF="..."> to a command in the Apache::MVC system
240       by catenating the base URL, table, command, and any arguments.
241
242   maybe_link_view
243       "maybe_link_view" takes something returned from the database - either
244       some ordinary data, or an object in a related class expanded by a has-a
245       relationship. If it is an object, it constructs a link to the view
246       command for that object. Otherwise, it just displays the data.
247
248   pager
249       This is an include template rather than a macro, and it controls the
250       pager display at the bottom (by default) of the factory list and search
251       views/template.  It expects a "pager" template argument which responds
252       to the Data::Page interface.
253
254       This macro is in the pager template and used as :
255
256       [% PROCESS pager %]
257
258       Maypole provides a pager for list and search actions, otherwise you can
259       provide a pager in the template using Template::Plugin::Pagination.
260
261       [% USE pager = Pagination(objects, page.current, page.rows) %] ...  [%
262       PROCESS pager %]
263
264       The pager will use a the request action  as the action in the url
265       unless the pager_action variable is set, which it will use instead if
266       available.
267
268   other macros

AUTHOR

270       Simon Cozens
271
272
273
274perl v5.32.1                      2021-01-27              Maypole::View::TT(3)
Impressum