|template||Processes the template and sets the output. See Maypole::View::Base|
|report_error||Reports the details of an error, current state and parameters|
The Template Toolkit uses its 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 its 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 youre using her AOL account? [% ELSIF age < 18 %]
Sorry, youre 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 %]
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.
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 dont actually need Maypole). See Template::Manual::Plugins.
[% 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 included 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.
You can access the request in your templates in order to see the action, table, etc as well as parameters passed through forms :
Hello [% request.params.forename %] [% request.params.surname %] !
Are you want to [% request.action %] in the [% request.table %] ?
You can access your maypole application configuration through the config variable :
<link base=[% config.uri_base %]/>
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 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 %].
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 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.
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 %]
[% 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.
|perl v5.20.3||MAYPOLE::VIEW::TT (3)||2008-04-18|