1Maypole::View::TT(3) User Contributed Perl Documentation Maypole::View::TT(3)
2
6 Maypole::View::TT - A Template Toolkit view class for Maypole
7
9 BeerDB->config->view("Maypole::View::TT"); # The default anyway
10 # Set some Template Toolkit options
12 BeerDB->config->view_options( {
13 TRIM => 1,
14 COMPILE_DIR => '/var/tmp/mysite/templates',
15 } );
16 .....
18 [% PROCESS macros %]
20 [% pager %]
22 [% link %]
24 [% maybe_link_view %]
26
28 This is the default view class for Maypole; it uses the Template Tool‐
29 kit to fill in templates with the objects produced by Maypole's model
30 classes. Please see the Maypole manual, and in particular, the view
31 chapter for the template variables available and for a refresher on how
32 template components are resolved.
33 The underlying Template toolkit object is configured through "$r->con‐
35 fig->view_options". See Template for available options.
36 template
38 Processes the template and sets the output. See Maypole::View::Base
39 report_error
41 Reports the details of an error, current state and parameters
42
44 The Template Toolkit uses it's own mini language described in Tem‐
45 plate::Manual::Directives.
46 A simple example would be :
48 re:[% subject %]
50 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 TT uses '[%' and '%]' (by default) to delimit directives within a tem‐
57 plate, and the simple directives above just display the value of vari‐
58 able 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 You can access nested data through the dot ('.') operator, which will
63 dereference array or hash elements, but can also be used to call meth‐
64 ods on objects, i.e. '[% name.salutation("Dear %s,") %]'. The other
65 main operator is underscore ('_'), which will concatonate strings or
66 variables.
67 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 You can specify expressions using the logical (and, or, not, ?:) and
74 mathematic operators (+ - * / % mod div).
75 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 [% template.title or default.title %]
81 [% score * 100 %]
83 [% order.nitems ? checkout(order.total) : 'no items' %]
85 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 Conditional and Looping constructs are simple and powerful, and TT pro‐
91 vides an inbuilt iterator and helper functions and classes that make
92 life sweet.
93 Conditional directives are IF, UNLESS, ELSIF, ELSE and behave as they
95 would in perl :
96 [% 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 [% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %]
105 Looping directives are FOREACH, LAST and BREAK.
107 FOREACH loops through a HASH or ARRAY processing the enclosed block for
109 each element.
110 Looping through an array
112 [% FOREACH i = items %]
114 [% i %]
115 [% END %]
116 Looping through a hash
118 [% FOREACH u IN users %]
120 * [% u.key %] : [% u.value %]
121 [% END %]
122 Looping through an array of hashes
124 [% FOREACH user IN userlist %]
126 * [% user.id %] [% user.name %]
127 [% END %]
128 The LAST and BREAK directive can be used to exit the loop.
130 The FOREACH directive is implemented using the Template::Iterator mod‐
132 ule. 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 [% 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 See Template::Iterator for further details on looping and the Iterator.
144 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 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 [% do.this;
155 do.that;
156 do.the_other %]
157 You can see that lines are terminated with a semi-colon (';') unless
159 the delimter ('%]') closes the directive.
160 For full details of the Template Toolkit see Template::Manual and Tem‐
162 plate::Manual::Directives, you can also check the website, mailing list
163 or the Template Toolkit book published by O Reilly.
164
166 The Template Toolkit has a popular and powerful selection of Plugins
167 and Filters.
168 TT Plugins provide additional functionality within Templates, from
170 accessing CGI and databases directly, handling paging or simple inte‐
171 gration with Class::DBI (for those rare occasions where you don't actu‐
172 ally need Maypole). See Template::Manual::Plugins.
173 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 [% USE foo = Class('Foo') %] [% foo.bar %]
179 Would do the equivilent of 'use Foo; Foo->bar;' in perl. See Tem‐
181 plate::Plugin::Class for details.
182 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 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 [% MACRO debug_msg(text)
193 FILTER stderr; "[TT debug_msg] $text\n"; END; %]
194 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 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 selec‐
202 tion of powerful and useful macros in the templates/ directory of the
203 package and these are used in the beerdb and default templates. See the
204 MACRO section of the Template::Manual::Directives documentation.
205
207 request
208 You can access the request in your templates in order to see the
210 action, table, etc as well as parameters passed through forms :
211 for example
213 Hello [% request.params.forename %] [% request.params.surname %] !
215 or
217 Are you want to [% request.action %] in the [% request.table %] ?
219 config
221 You can access your maypole application configuration through the con‐
223 fig variable :
224 <link base="[% config.uri_base %]"/>
226 object and objects
228 Objects are passed to the request using r->objects($arrayref) and are
230 accessed in the templates as an array called objects.
231 [% FOR objects %] <a href="[% config.uri_base %]/[% request.table
233 %]/view/[% object.id %]"> [% object %] </a> [% END %]
234
236 Maypole provides a collection of useful and powerful macros in the tem‐
237 plates/factory/macros
238 and other templates. These can be used in any template with [% PROCESS
239 templatename %].
240 link
242 This creates an <A HREF="..."> to a command in the Apache::MVC system
244 by catenating the base URL, table, command, and any arguments.
245 maybe_link_view
247 "maybe_link_view" takes something returned from the database - either
249 some ordinary data, or an object in a related class expanded by a has-a
250 relationship. If it is an object, it constructs a link to the view com‐
251 mand for that object. Otherwise, it just displays the data.
252 pager
254 This is an include template rather than a macro, and it controls the
256 pager display at the bottom (by default) of the factory list and search
257 views/template. It expects a "pager" template argument which responds
258 to the Data::Page interface.
259 This macro is in the pager template and used as :
261 [% PROCESS pager %]
263 Maypole provides a pager for list and search actions, otherwise you can
265 provide a pager in the template using Template::Plugin::Pagination.
266 [% USE pager = Pagination(objects, page.current, page.rows) %] ... [%
268 PROCESS pager %]
269 The pager will use a the request action as the action in the url
271 unless the pager_action variable is set, which it will use instead if
272 available.
273 other macros
275
277 Simon Cozens
278perl v5.8.8 2005-11-23 Maypole::View::TT(3)