Feedback on TemplateToolkitPlugin

Exactly four years ago Andrea Sterbini wrote:

I must admit that I did not check for the existence of this topic when I hacked my TemplateToolkitPlugin (did Andrea really mean Toolkit instead of Tooltip?). But now, after four years, I dare to snatch it anyway.

Following a suggestion by PeterThoeny on the twiki-dev mailing list, I'll present here some design considerations which made TemplateToolkitPlugin behave the way it does:

Delimiter Judo

Per default, Template Toolkit wraps its directives between [% ... %] delimiters. These are infrequent in usual text, but TWiki occasionally needs exactly that, e.g. when writing a reference to an attachment: [[%ATTACHURL%/...][some text]].

Of course, TT's delimiter can be configured. However, my main target when writing the plugin was to use my own TT libraries, which happen to use the default delimiters. So what I did is retain TT's default, but trying to make it robust against usual TWiki syntax as in the example above.

SvenDowideit came up with the idea to define the TT delimiters in a way that would allow to write TT in a very TWiki way as:

%TT2{" ...your tt code goes here ... "}%=

While this happens to be possible thanks to TT's configurability, I'd recommend that only for the simplest possible uses of TT, otherwise I am afraid that TWiki's parser might choke on TT directive syntax. But alas, if you really want to do this, here's how: In your lib/LocalSite.cfg file add the lines

$TWiki::cfg{Plugins}{TemplateToolkitPlugin}{TTOptions}{START_TAG} = '%TT2{"';
$TWiki::cfg{Plugins}{TemplateToolkitPlugin}{TTOptions}{END_TAG}   = '"}%';

If you guessed that everything in the Hash reference $TWiki::cfg{Plugins}{TemplateToolkitPlugin}{TTOptions} will be passed to the constructor of the Template object, then you guessed right. Use with care

Plugin Handler Selection

The current implementation is not targeted at replacing TWiki's own template mechanism. A plugin is not really able to do that. Instead, plugins are called at certain defined steps during render processing.

Two candidates have been considered:

1. preRenderingHandler - called before the TML to HTML conversion, with verbatim blocks protected, and
2. postRenderingHandler - called after everything is HTML, with verbatim blocks in place.

My first idea was to use preRenderingHandler, to be able to write TML in TT templates as well. However, I discarded that due to two obstacles:

1. Text added by a preRenderingHandler gets its TML (lists, headers etc) expanded, but not its variables. This makes it much less useful.
2. Existing TT templates often make use of line indenting or empty lines, just to make them more readable. However, this creates loads of empty paragraphs and broken multiline HTML tags when run through TML expansion.

So currently the plugin is using the postRenderingHandler, with the side effect that it is not possible to protect TT blocks from the plugin by embedding them in <verbatim>...</verbatim>.

-- HaraldJoerg - 24 Sep 2006

Thanks Harald for sharing, yet another plugin!

-- PeterThoeny - 28 Sep 2006