Maypole::View::TT(3)

🌸 NAME 🌸

Maypole::View::TT — the Template Toolkit view class for Maypole, bestie 💖

---

✨ 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 💖

okay so this is the default view class for Maypole, periodt. It uses the Template Toolkit to fill in your templates with the objects that Maypole's model classes hand over 🎀. Please go read the Maypole manual — especially the view chapter — for the template variables that are available and for a lil refresher on how template components get resolved. iykyk.

The underlying Template Toolkit object gets configured through $r->config->view_options. See Template for the options you can throw at it ✨.

• template — processes the template and sets the output 🫶. See Maypole::View::Base.
• report_error — reports the details of an error, plus the current state and parameters 😭.

---

🦋 TEMPLATE TOOLKIT INTRODUCTION 🦋

The Template Toolkit speaks its own mini language, and it's fully described over 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 inside a template, and those simple directives above literally just display the value of the variable named inside the delimiters — [% title %] gets replaced inline with the value of the 'title' variable passed in the stash to the template when it's processed 💅.

You can reach nested data through the dot (.) operator, which dereferences array or hash elements, but it can also call methods on objects, i.e. [% name.salutation("Dear %s,") %] 👑. The other main operator is underscore (_), which concatenates strings or variables 🔗.

The value returned by a directive replaces the directive inline when the template is processed. You can also SET a value, which won't return anything, or CALL a method or operation, which also won't return anything 🤫.

You can specify expressions using the logical operators (and, or, not, ?:) and the mathematic operators (+ - * / % mod div) ✨.

Results of TT commands are interpolated in the place of the template tags, unless you're 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 lets you include or re-use templates through its INCLUDE, PROCESS and INSERT directives, which are pretty self-explanatory ngl 🫶. You can also re-use parts of a template with the BLOCK or MACRO directives 🧩.

Conditional and looping constructs are simple and powerful, and TT ships with an inbuilt iterator plus helper functions and classes that make life genuinely sweet 🍓.

Conditional directives are IF, UNLESS, ELSIF, ELSE and they behave exactly like 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 directives 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 that minus (-) operator in the example above — it's used to remove a newline before or after a directive, so you can lay out the Template logic like that while the resulting output still looks exactly how you need it 💅.

You'll also frequently see comments and multi-line directives. A # 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 delimiter (%]) closes the directive 🎯.

For full details of the Template Toolkit see Template::Manual and Template::Manual::Directives. You can also check the website, the 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 extra functionality inside Templates — from accessing CGI and databases directly, to handling paging, to simple integration with Class::DBI (for those rare occasions where you don't actually need Maypole). See Template::Manual::Plugins 💫.

One plugin that is indispensable when using Maypole and the Template View is Template::Plugin::Class — it lets you import and use any class installed, right inside a template. For example :

[% USE foo = Class('Foo') %] [% foo.bar %]

That would do the equivalent of use Foo; Foo->bar; in perl. See Template::Plugin::Class for details 👑.

TT Filters process strings or blocks inside a template, letting you truncate, format, escape or encode trivially ✂️. A useful selection ships with Template Toolkit, more live on CPAN, and they're easy to write yourself. See Template::Manual::Filters.

TT provides stderr and stdout filters, which let you 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 let you reuse small blocks of content, directives, etc 🔁. The MACRO directive lets you define a directive or directive block which then gets evaluated each time the macro is called. Macros can be passed named parameters when they're called 🎁.

Once a MACRO is defined within a template or an '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

(and that's literally where the section ends, bestie — nothing else here, no cap 💀)

---

💜 AUTHOR 💜

Simon Cozens 👑

---

and that's the whole page fr fr 🫶 — this was Maypole::View::TT(3) from perl v5.42.0, dated 2025-07-25. slay, go write some templates 💅✨