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
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 The underlying Template toolkit object is configured through
35 "$r->config->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
45 Template::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
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 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 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
91 provides 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
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 [% 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
162 Template::Manual::Directives, you can also check the website, mailing
163 list 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
171 integration with Class::DBI (for those rare occasions where you don't
172 actually 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
181 Template::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
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
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 for example
212 Hello [% request.params.forename %] [% request.params.surname %] !
214 or
216 Are you want to [% request.action %] in the [% request.table %] ?
218 config
220 You can access your maypole application configuration through the
221 config variable :
222 <link base="[% config.uri_base %]"/>
224 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 [% FOR objects %] <a href="[% config.uri_base %]/[% request.table
230 %]/view/[% object.id %]"> [% object %] </a> [% END %]
231
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 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 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 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 This macro is in the pager template and used as :
255 [% PROCESS pager %]
257 Maypole provides a pager for list and search actions, otherwise you can
259 provide a pager in the template using Template::Plugin::Pagination.
260 [% USE pager = Pagination(objects, page.current, page.rows) %] ... [%
262 PROCESS pager %]
263 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 other macros
270 Simon Cozens
271perl v5.12.0 2008-04-18 Maypole::View::TT(3)