Maypole::View::TT(3) User Contributed Perl Documentation Maypole::View::TT(3)NAMEMaypole::View::TT - A Template Toolkit view class for Maypole
SYNOPSIS
BeerDB->config->view("Maypole::View::TT"); # The default anyway
# Set some Template Toolkit options
BeerDB->config->view_options( {
TRIM => 1,
COMPILE_DIR => '/var/tmp/mysite/templates',
} );
.....
[% PROCESS macros %]
[% pager %]
[% link %]
[% maybe_link_view %]
DESCRIPTION
This is the default view class for Maypole; it uses the Template
Toolkit to fill in templates with the objects produced by Maypole's
model classes. Please see the Maypole manual, and in particular, the
view chapter for the template variables available and for a refresher
on how template components are resolved.
The underlying Template toolkit object is configured through
"$r->config->view_options". See Template for available options.
template
Processes the template and sets the output. See Maypole::View::Base
report_error
Reports the details of an error, current state and parameters
TEMPLATE TOOLKIT INTRODUCTION
The Template Toolkit uses it's own mini language described in
Template::Manual::Directives.
A simple example would be :
re:[% subject %]
Dear [% title %] [% surname %], Thank you for your letter dated [%
your.date %]. This is to confirm that we have received it and will
respond with a more detailed response as soon as possible. In the
mean time, we enclose more details of ...
TT uses '[%' and '%]' (by default) to delimit directives within a
template, and the simple directives above just display the value of
variable named within those delimiters -- [% title %] will be replaced
inline with the value of the 'title' variable passed in the 'stash' to
the template when it is processed.
You can access nested data through the dot ('.') operator, which will
dereference array or hash elements, but can also be used to call
methods on objects, i.e. '[% name.salutation("Dear %s,") %]'. The other
main operator is underscore ('_'), which will concatonate strings or
variables.
The value returned by a directive replaces the directive inline when
the template is processes, you can also SET a value which will not
return anything, or CALL a method or operation which will also not
return anything.
You can specify expressions using the logical (and, or, not, ?:) and
mathematic operators (+ - * / % mod div).
Results of TT commands are interpolated in the place of the template
tags, unless using SET or CALL, i.e. [% SET foo = 1 %], [% GET
foo.bar('quz'); %]
[% template.title or default.title %]
[% score * 100 %]
[% order.nitems ? checkout(order.total) : 'no items' %]
TT allows you to include or re-use templates through it's INCLUDE,
PROCESS and INSERT directives, which are fairly self explainatory. You
can also re-use parts of template with the BLOCK or MACRO directives.
Conditional and Looping constructs are simple and powerful, and TT
provides an inbuilt iterator and helper functions and classes that make
life sweet.
Conditional directives are IF, UNLESS, ELSIF, ELSE and behave as they
would in perl :
[% IF age < 10 %]
Hello [% name %], does your mother know you're using her AOL
account? [% ELSIF age < 18 %]
Sorry, you're not old enough to enter (and too dumb to lie about
your age) [% ELSE %]
Welcome [% name %]. [% END %]
[% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %]
Looping directives are FOREACH, LAST and BREAK.
FOREACH loops through a HASH or ARRAY processing the enclosed block for
each element.
Looping through an array
[% FOREACH i = items %]
[% i %]
[% END %]
Looping through a hash
[% FOREACH u IN users %]
* [% u.key %] : [% u.value %]
[% END %]
Looping through an array of hashes
[% FOREACH user IN userlist %]
* [% user.id %] [% user.name %]
[% END %]
The LAST and BREAK directive can be used to exit the loop.
The FOREACH directive is implemented using the Template::Iterator
module. A reference to the iterator object for a FOREACH directive is
implicitly available in the 'loop' variable. The loop iterator object
provides a selection of methods including size(), max(), first(),
last(), count(), etc
[% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%]
[%- "<ul>\n" IF loop.first %]
<li>[% loop.count %]/[% loop.size %]: [% item %]
[%- "</ul>\n" IF loop.last %]
[% END %]
See Template::Iterator for further details on looping and the Iterator.
You might notice the minus ('-') operator in the example above, it is
used to remove a newline before or after a directive so that you can
layout the Template logic as above but the resulting output will look
exactly how you require it.
You will also frequently see comments and multi-line directives, # at
the start of a directive marks it as a comment, i.e. '[%# this is a
comment %]'. A multiline directive looks like :
[% do.this;
do.that;
do.the_other %]
You can see that lines are terminated with a semi-colon (';') unless
the delimter ('%]') closes the directive.
For full details of the Template Toolkit see Template::Manual and
Template::Manual::Directives, you can also check the website, mailing
list or the Template Toolkit book published by O Reilly.
TEMPLATE PLUGINS, FILTERS AND MACROS
The Template Toolkit has a popular and powerful selection of Plugins
and Filters.
TT Plugins provide additional functionality within Templates, from
accessing CGI and databases directly, handling paging or simple
integration with Class::DBI (for those rare occasions where you don't
actually need Maypole). See Template::Manual::Plugins.
One plugin that is indispensible when using Maypole and the Template
View is "Template::Plugin::Class" -- This allows you to import and use
any class installed within a template. For example :
[% USE foo = Class('Foo') %] [% foo.bar %]
Would do the equivilent of 'use Foo; Foo->bar;' in perl. See
Template::Plugin::Class for details.
TT Filters process strings or blocks within a template, allowing you to
truncate, format, escape or encode trivially. A useful selection is
included with Template Toolkit and they can also be found on CPAN or
can be written easily. See Template::Manual::Filters.
TT provides stderr and stdout filters, which allow you to write handy
macros like this one to output debug information to your web server
log, etc :
[% MACRO debug_msg(text)
FILTER stderr; "[TT debug_msg] $text\n"; END; %]
TT Macros allow you to reuse small blocks of content, directives, etc.
The MACRO directive allows you to define a directive or directive block
which is then evaluated each time the macro is called. Macros can be
passed named parameters when called.
Once a MACRO is defined within a template or 'include'd template it can
be used as if it were a native TT directive. Maypole provides a
selection of powerful and useful macros in the templates/ directory of
the package and these are used in the beerdb and default templates. See
the MACRO section of the Template::Manual::Directives documentation.
ACCESSING MAYPOLE VALUES
request
You can access the request in your templates in order to see the
action, table, etc as well as parameters passed through forms :
for example
Hello [% request.params.forename %] [% request.params.surname %] !
or
Are you want to [% request.action %] in the [% request.table %] ?
config
You can access your maypole application configuration through the
config variable :
<link base="[% config.uri_base %]"/>
object and objects
Objects are passed to the request using r->objects($arrayref) and are
accessed in the templates as an array called objects.
[% FOR objects %] <a href="[% config.uri_base %]/[% request.table
%]/view/[% object.id %]"> [% object %] </a> [% END %]
MAYPOLE MACROS AND FILTERS
Maypole provides a collection of useful and powerful macros in the
templates/factory/macros
and other templates. These can be used in any template with [% PROCESS
templatename %].
link
This creates an <A HREF="..."> to a command in the Apache::MVC system
by catenating the base URL, table, command, and any arguments.
maybe_link_view
"maybe_link_view" takes something returned from the database - either
some ordinary data, or an object in a related class expanded by a has-a
relationship. If it is an object, it constructs a link to the view
command for that object. Otherwise, it just displays the data.
pager
This is an include template rather than a macro, and it controls the
pager display at the bottom (by default) of the factory list and search
views/template. It expects a "pager" template argument which responds
to the Data::Page interface.
This macro is in the pager template and used as :
[% PROCESS pager %]
Maypole provides a pager for list and search actions, otherwise you can
provide a pager in the template using Template::Plugin::Pagination.
[% USE pager = Pagination(objects, page.current, page.rows) %] ... [%
PROCESS pager %]
The pager will use a the request action as the action in the url
unless the pager_action variable is set, which it will use instead if
available.
other macros
AUTHOR
Simon Cozens
perl v5.14.1 2008-04-18 Maypole::View::TT(3)
