create new tag
, view all tags

TemplateToolkitPluginDev Discussion: Page for developer collaboration, enhancement requests, patches and improved versions on TemplateToolkitPlugin contributed by the TWikiCommunity.
• Please let us know what you think of this extension.
• For support, check the existing questions, or ask a new support question in the Support web!
• Please file bug reports in the TemplateToolkitPlugin bug database.

Feedback on TemplateToolkitPlugin

Exactly four years ago Andrea Sterbini wrote:

I am packaging a simple TemplateTooltipPlugin from some code FrancoBagnoli has written for his WebComplex site ... see you soon! smile

A question to our fellow developers:

  • what twiki variables would you like to make available to the TemplateToolkit?
-- AndreaSterbini - 24 Sep 2002

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 smile

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

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2006-09-28 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.