NAME Text::Template::Library - a derived class of Text::Template SYNOPSIS use Text::Template::Library; my $tmpl=Text::Template::Library->new(...); $tmpl->fill_in(...); in the template: { define macro1 } macro text { /define } ... { define macro2 } macro text { /define } ... { fill_in_module('macro2') } INSTALLATION Before you install this module apply the necessary patches to the Text::Template distribution, see ""Text::Template" patches" below. perl Makefile.PL make make test make install DESCRIPTION I have used "Text::Template" for several years in different projects. Allways I have missed the possibility to create macros. For example suppose this template: [% for (@rows) { $OUT.="<... EOR } %]
This works perfectly well but all my HTML editors get confused by the "< [% for (@rows) { $OUT.=fill_in_file('/path/to/row.tmpl'); } %] But that would mean to have hundreds of small files laying about. "Text::Template::Library" allows you to include these subtemplates in the main template: [% define row %] ... [% /define %] [% for (@rows) { $OUT.=fill_in_module('row'); } %]
Details To make this module work with "Text::Template" as base class I had to enhance it a bit. I have tried to contact the author M-J. Dominus several times to get my patches into "Text::Template" but never got a reply. In the end I decided to include a renamed and patched version of "Text::Template" 1.45 with this distribution. It is named Text::Template::Base. For more information about the changes see ""Text::Template" patches" below. So, strictly speaking "Text::Template::Library" is not anymore a derived class of "Text::Template" but of "Text::Template::Base". Other than with "Text::Template::Base" custom delimiters must be passed to the "new()" method. Passing them to "fill_in()" is not supported. Further, "SAFE" compartments are not (yet) supported. The "Text::Template::Library" module inherits from "Text::Template::Base". It overrides 2 methods, "_acquire_data" and "fill_in". The first one reads the template and converts it to type "STRING". After that is done our own "_acquire_data" greps out all parts of the template that are included in a "DEFINE.../DEFINE" sequence. The "DEFINE" statement consists of the current opening delimiter followed by literally one space (except newline), the string "define", again one space (except newline), the name of the macro that must match "^\w+$", another space (except newline) and the closing delimiter. For example: { define name } # assuming default delimiters or [% define name %] # assuming DELIMITERS=>[qw/[% %]/] The "/DEFINE" statement accordingly consists of the opening delimiter followed by one space, the string "/define", another space and the closing delimiter. White spaces including newlines following the closing "/DEFINE" statement are cut out of the template. So subsequent definitions like these: { define m1 } ... { /define } { define m2 } ... { /define } do not create additional white spaces (newlines) in the main template. Otherwise you would have to write that this way: { define m1 } ... { /define }{ define m2 } ... { /define } Also, white spaces up to the first newline (including) following the opening "DEFINE" statement are cut out. Hence, you can write { define m1 } ... { /define } instead of { define m1 }... { /define } The subtemplates are created as "Text::Template::Base" objects not "Text::Template::Library" objects. This made the parsing process a lot simpler. But it denies nesting of "DEFINE" statements. Subtemplates are evaluated in the same package as the parent template. "OUTPUT", "EVALCACHE", "BROKEN", "BROKEN_ARG", "PREPEND" and "FILENAME" settings are also passed from the parent template to subtemplates. Methods new creates a "Text::Template::Library" object. fill_in evaluates the template. Almost all parameters for "Text::Template::Base::fill_in" are supported except "DELIMITERS" (which must be passed to "new()") and "SAFE". Prior to calling "Text::Template::Base::fill_in" this method localizes $Text::Template::Library::T and stores there the current template. This variable can be used in subtemplates directly or indirectly via "fill_in_module()". module($name) returns the compiled subtemplate named $name. The subtemplate is a "Text::Template::Base" object, not "Text::Template::Library". library($name, @params) evaluates the subtemplate $name. @params are passed to "Text::Template::Base::fill_in". Unlike "Text::Template::Base::fill_in" this method throws an exception if there was an error. So, it can be used in combination with "OUTPUT", see Text::Template::Base. If the "OUTPUT" option was given to the parent template "library" returns an empty string on success, otherwise the computed string. In templates you can use it this way: $Text::Template::Library::T->library($name, @params); fill_in_module($name, @params) Shortcut for $Text::Template::Library::T->library($name, @params); to be used in templates. But calling Text::Template::Library::fill_in_module(...) is not much of a shortcut. To make it work normally you can import it into the package in which the template is evaluated: { package Q; use Text::Template::Library qw/fill_in_module/; } $tmpl->fill_in(PACKAGE=>'Q', ...); or even simpler: local *Q::call_module=\&Text::Template::Library; $tmpl->fill_in(PACKAGE=>'Q', ...); This way you can use "call_module()" like "fill_in_module()" in your templates. EXPORT "fill_in_module" on demand. "Text::Template" patches While working on the module I have dicovered a few bugs in "Text::Template" 1.45. Further, some improvements were made. You'll find all patches in the "patches" directory. For more information see the doc.diff patch. I have sent these patches to the author of "Text::Template", Mark Jason Dominus but haven't yet received an answer. None of my changes should break existing code working with "Text::Template" 1.45. Please apply all the patches to the "Text::Template" distribution prior to running "make test" with this distribution. The patches are applied in this order: cd Text-Template-1.45 cp /path/to/Text-Template-Library-0.01/patches/*.diff . patch -p0 COPYRIGHT AND LICENSE Copyright (C) 2008-2009 by Torsten Foertsch This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.